DescriptionFactory::lex() - Code Metrics - Inspection of "Merge pull request #77 from Soullivaneuh/example-t..." - phpDocumentor/ReflectionDocBlock - Measure and Improve Code Quality continuously with Scrutinizer

Completed

Push — master ( 45ada3...ea48fd )

by Mike

created 2016-06-10 07:04 UTC

DescriptionFactory::lex() B

↳ Parent: DescriptionFactory

Complexity

Conditions	2
Paths	2

Size

Total Lines	39
Code Lines	9

Duplication

Lines	0
Ratio	0 %

Code Coverage

Tests	8
CRAP Score	2

Importance

Changes	2
Bugs	0	Features	0

Metric	Value
c	2
b	0
f	0
dl	0
loc	39
ccs	8
cts	8
cp	1
rs	8.8571
cc	2
eloc	9
nc	2
nop	1
crap	2

<?php
/**
 * This file is part of phpDocumentor.
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 *
 * @copyright 2010-2015 Mike van Riel<[email protected]>
 * @license   http://www.opensource.org/licenses/mit-license.php MIT
 * @link      http://phpdoc.org
 */

namespace phpDocumentor\Reflection\DocBlock;

use phpDocumentor\Reflection\Types\Context as TypeContext;

/**
 * Creates a new Description object given a body of text.
 *
 * Descriptions in phpDocumentor are somewhat complex entities as they can contain one or more tags inside their
 * body that can be replaced with a readable output. The replacing is done by passing a Formatter object to the
 * Description object's `render` method.
 *
 * In addition to the above does a Description support two types of escape sequences:
 *
 * 1. `{@}` to escape the `@` character to prevent it from being interpreted as part of a tag, i.e. `{{@}link}`
 * 2. `{}` to escape the `}` character, this can be used if you want to use the `}` character in the description
 *    of an inline tag.
 *
 * If a body consists of multiple lines then this factory will also remove any superfluous whitespace at the beginning
 * of each line while maintaining any indentation that is used. This will prevent formatting parsers from tripping
 * over unexpected spaces as can be observed with tag descriptions.
 */
class DescriptionFactory
{
    /** @var TagFactory */
    private $tagFactory;

    /**
     * Initializes this factory with the means to construct (inline) tags.
     *
     * @param TagFactory $tagFactory
     */
    public function __construct(TagFactory $tagFactory)
    {
        $this->tagFactory = $tagFactory;
    }

    /**
     * Returns the parsed text of this description.
     *
     * @param string $contents
     * @param TypeContext $context
     *
     * @return Description
     */
    public function create($contents, TypeContext $context = null)
    {
        list($text, $tags) = $this->parse($this->lex($contents), $context);
/** @return stdClass|null */
function mayReturnNull() { }

function doesNotAcceptNull(stdClass $x) { }

// With potential error.
function withoutCheck() {
    $x = mayReturnNull();
    doesNotAcceptNull($x); // Potential error here.
}

// Safe - Alternative 1
function withCheck1() {
    $x = mayReturnNull();
    if ( ! $x instanceof stdClass) {
        throw new \LogicException('$x must be defined.');
    }
    doesNotAcceptNull($x);
}

// Safe - Alternative 2
function withCheck2() {
    $x = mayReturnNull();
    if ($x instanceof stdClass) {
        doesNotAcceptNull($x);
    }
}

        return new Description($text, $tags);
    }

    /**
     * Strips the contents from superfluous whitespace and splits the description into a series of tokens.
     *
     * @param string $contents
     *
     * @return string[] A series of tokens of which the description text is composed.
     */
    private function lex($contents)
    {
        $contents = $this->removeSuperfluousStartingWhitespace($contents);

        // performance optimalization; if there is no inline tag, don't bother splitting it up.
        if (strpos($contents, '{@') === false) {
            return [$contents];
        }

        return preg_split(
            '/\{
                # "{@}" is not a valid inline tag. This ensures that we do not treat it as one, but treat it literally.
                (?!@\})
                # We want to capture the whole tag line, but without the inline tag delimiters.
                (\@
                    # Match everything up to the next delimiter.
                    [^{}]*
                    # Nested inline tag content should not be captured, or it will appear in the result separately.
                    (?:
                        # Match nested inline tags.
                        (?:
                            # Because we did not catch the tag delimiters earlier, we must be explicit with them here.
                            # Notice that this also matches "{}", as a way to later introduce it as an escape sequence.
                            \{(?1)?\}
                            |
                            # Make sure we match hanging "{".
                            \{
                        )
                        # Match content after the nested inline tag.
                        [^{}]*
                    )* # If there are more inline tags, match them as well. We use "*" since there may not be any
                       # nested inline tags.
                )
            \}/Sux',
            $contents,
            null,
            PREG_SPLIT_DELIM_CAPTURE
        );
    }

    /**
     * Parses the stream of tokens in to a new set of tokens containing Tags.
     *
     * @param string[] $tokens
     * @param TypeContext $context
     *
     * @return string[]|Tag[]
     */
    private function parse($tokens, TypeContext $context)
    {
        $count = count($tokens);
        $tagCount = 0;
        $tags  = [];

        for ($i = 1; $i < $count; $i += 2) {
            $tags[] = $this->tagFactory->create($tokens[$i], $context);
            $tokens[$i] = '%' . ++$tagCount . '$s';
        }

        //In order to allow "literal" inline tags, the otherwise invalid
        //sequence "{@}" is changed to "@", and "{}" is changed to "}".
        //See unit tests for examples.
        for ($i = 0; $i < $count; $i += 2) {
            $tokens[$i] = str_replace(['{@}', '{}'], ['@', '}'], $tokens[$i]);
        }

        return [implode('', $tokens), $tags];
    }

    /**
     * Removes the superfluous from a multi-line description.
     *
     * When a description has more than one line then it can happen that the second and subsequent lines have an
     * additional indentation. This is commonly in use with tags like this:
     *
     *     {@}since 1.1.0 This is an example
     *         description where we have an
     *         indentation in the second and
     *         subsequent lines.
     *
     * If we do not normalize the indentation then we have superfluous whitespace on the second and subsequent
     * lines and this may cause rendering issues when, for example, using a Markdown converter.
     *
     * @param string $contents
     *
     * @return string
     */
    private function removeSuperfluousStartingWhitespace($contents)
    {
        $lines = explode("\n", $contents);

        // if there is only one line then we don't have lines with superfluous whitespace and
        // can use the contents as-is
        if (count($lines) <= 1) {
            return $contents;
        }

        // determine how many whitespace characters need to be stripped
        $startingSpaceCount = 9999999;
        for ($i = 1; $i < count($lines); $i++) {
for ($i=0; $i<count($array); $i++) { // calls count() on each iteration
}

// Better
for ($i=0, $c=count($array); $i<$c; $i++) { // calls count() just once
}
            // lines with a no length do not count as they are not indented at all
            if (strlen(trim($lines[$i])) === 0) {
                continue;
            }

            // determine the number of prefixing spaces by checking the difference in line length before and after
            // an ltrim
            $startingSpaceCount = min($startingSpaceCount, strlen($lines[$i]) - strlen(ltrim($lines[$i])));
        }

        // strip the number of spaces from each line
        if ($startingSpaceCount > 0) {
            for ($i = 1; $i < count($lines); $i++) {
for ($i=0; $i<count($array); $i++) { // calls count() on each iteration
}

// Better
for ($i=0, $c=count($array); $i<$c; $i++) { // calls count() just once
}
                $lines[$i] = substr($lines[$i], $startingSpaceCount);
            }
        }

        return implode("\n", $lines);
    }

}


1		<?php
2		/**
3		* This file is part of phpDocumentor.
4		*
5		* For the full copyright and license information, please view the LICENSE
6		* file that was distributed with this source code.
7		*
8		* @copyright 2010-2015 Mike van Riel<[email protected]>
9		* @license http://www.opensource.org/licenses/mit-license.php MIT
10		* @link http://phpdoc.org
11		*/
12
13		namespace phpDocumentor\Reflection\DocBlock;
14
15		use phpDocumentor\Reflection\Types\Context as TypeContext;
16
17		/**
18		* Creates a new Description object given a body of text.
19		*
20		* Descriptions in phpDocumentor are somewhat complex entities as they can contain one or more tags inside their
21		* body that can be replaced with a readable output. The replacing is done by passing a Formatter object to the
22		* Description object's `render` method.
23		*
24		* In addition to the above does a Description support two types of escape sequences:
25		*
26		* 1. `{@}` to escape the `@` character to prevent it from being interpreted as part of a tag, i.e. `{{@}link}`
27		* 2. `{}` to escape the `}` character, this can be used if you want to use the `}` character in the description
28		* of an inline tag.
29		*
30		* If a body consists of multiple lines then this factory will also remove any superfluous whitespace at the beginning
31		* of each line while maintaining any indentation that is used. This will prevent formatting parsers from tripping
32		* over unexpected spaces as can be observed with tag descriptions.
33		*/
34		class DescriptionFactory
35		{
36		/** @var TagFactory */
37		private $tagFactory;
38
39		/**
40		* Initializes this factory with the means to construct (inline) tags.
41		*
42		* @param TagFactory $tagFactory
43		*/
44	9	public function __construct(TagFactory $tagFactory)
45		{
46	9	$this->tagFactory = $tagFactory;
47	9	}
48
49		/**
50		* Returns the parsed text of this description.
51		*
52		* @param string $contents
53		* @param TypeContext $context
54		*
55		* @return Description
56		*/
57	9	public function create($contents, TypeContext $context = null)
58		{
59	9	list($text, $tags) = $this->parse($this->lex($contents), $context);
		0 ignored issues – show Bug introduced 2015-12-22 13:00 UTC by Report Bug Copy Issue Report It seems like `$context` can be `null`; however, `parse()` does not accept `null`, maybe add an additional type check? Unless you are absolutely sure that the expression can never be null because of other conditions, we strongly recommend to add an additional type check to your code: /** @return stdClass\|null */ function mayReturnNull() { } function doesNotAcceptNull(stdClass $x) { } // With potential error. function withoutCheck() { $x = mayReturnNull(); doesNotAcceptNull($x); // Potential error here. } // Safe - Alternative 1 function withCheck1() { $x = mayReturnNull(); if ( ! $x instanceof stdClass) { throw new \LogicException('$x must be defined.'); } doesNotAcceptNull($x); } // Safe - Alternative 2 function withCheck2() { $x = mayReturnNull(); if ($x instanceof stdClass) { doesNotAcceptNull($x); } } Loading history...
60
61	9	return new Description($text, $tags);
62		}
63
64		/**
65		* Strips the contents from superfluous whitespace and splits the description into a series of tokens.
66		*
67		* @param string $contents
68		*
69		* @return string[] A series of tokens of which the description text is composed.
70		*/
71	9	private function lex($contents)
72		{
73	9	$contents = $this->removeSuperfluousStartingWhitespace($contents);
74
75		// performance optimalization; if there is no inline tag, don't bother splitting it up.
76	9	if (strpos($contents, '{@') === false) {
77	6	return [$contents];
78		}
79
80	3	return preg_split(
81		'/\{
82		# "{@}" is not a valid inline tag. This ensures that we do not treat it as one, but treat it literally.
83		(?!@\})
84		# We want to capture the whole tag line, but without the inline tag delimiters.
85		(\@
86		# Match everything up to the next delimiter.
87		[^{}]*
88		# Nested inline tag content should not be captured, or it will appear in the result separately.
89		(?:
90		# Match nested inline tags.
91		(?:
92		# Because we did not catch the tag delimiters earlier, we must be explicit with them here.
93		# Notice that this also matches "{}", as a way to later introduce it as an escape sequence.
94		\{(?1)?\}
95		\|
96		# Make sure we match hanging "{".
97		\{
98		)
99		# Match content after the nested inline tag.
100		[^{}]*
101		)* # If there are more inline tags, match them as well. We use "*" since there may not be any
102		# nested inline tags.
103		)
104	3	\}/Sux',
105		$contents,
106	3	null,
107	3	PREG_SPLIT_DELIM_CAPTURE
108		);
109		}
110
111		/**
112		* Parses the stream of tokens in to a new set of tokens containing Tags.
113		*
114		* @param string[] $tokens
115		* @param TypeContext $context
116		*
117		* @return string[]\|Tag[]
118		*/
119	9	private function parse($tokens, TypeContext $context)
120		{
121	9	$count = count($tokens);
122	9	$tagCount = 0;
123	9	$tags = [];
124
125	9	for ($i = 1; $i < $count; $i += 2) {
126	2	$tags[] = $this->tagFactory->create($tokens[$i], $context);
127	2	$tokens[$i] = '%' . ++$tagCount . '$s';
128		}
129
130		//In order to allow "literal" inline tags, the otherwise invalid
131		//sequence "{@}" is changed to "@", and "{}" is changed to "}".
132		//See unit tests for examples.
133	9	for ($i = 0; $i < $count; $i += 2) {
134	9	$tokens[$i] = str_replace(['{@}', '{}'], ['@', '}'], $tokens[$i]);
135		}
136
137	9	return [implode('', $tokens), $tags];
138		}
139
140		/**
141		* Removes the superfluous from a multi-line description.
142		*
143		* When a description has more than one line then it can happen that the second and subsequent lines have an
144		* additional indentation. This is commonly in use with tags like this:
145		*
146		* {@}since 1.1.0 This is an example
147		* description where we have an
148		* indentation in the second and
149		* subsequent lines.
150		*
151		* If we do not normalize the indentation then we have superfluous whitespace on the second and subsequent
152		* lines and this may cause rendering issues when, for example, using a Markdown converter.
153		*
154		* @param string $contents
155		*
156		* @return string
157		*/
158	9	private function removeSuperfluousStartingWhitespace($contents)
159		{
160	9	$lines = explode("\n", $contents);
161
162		// if there is only one line then we don't have lines with superfluous whitespace and
163		// can use the contents as-is
164	9	if (count($lines) <= 1) {
165	8	return $contents;
166		}
167
168		// determine how many whitespace characters need to be stripped
169	1	$startingSpaceCount = 9999999;
170	1	for ($i = 1; $i < count($lines); $i++) {
		0 ignored issues – show Performance Best Practice introduced 2015-12-22 13:00 UTC by Report Bug Copy Issue Report It seems like you are calling the size function `count()` as part of the test condition. You might want to compute the size beforehand, and not on each iteration. If the size of the collection does not change during the iteration, it is generally a good practice to compute it beforehand, and not on each iteration: for ($i=0; $i<count($array); $i++) { // calls count() on each iteration } // Better for ($i=0, $c=count($array); $i<$c; $i++) { // calls count() just once } Loading history...
171		// lines with a no length do not count as they are not indented at all
172	1	if (strlen(trim($lines[$i])) === 0) {
173	1	continue;
174		}
175
176		// determine the number of prefixing spaces by checking the difference in line length before and after
177		// an ltrim
178	1	$startingSpaceCount = min($startingSpaceCount, strlen($lines[$i]) - strlen(ltrim($lines[$i])));
179		}
180
181		// strip the number of spaces from each line
182	1	if ($startingSpaceCount > 0) {
183	1	for ($i = 1; $i < count($lines); $i++) {
		0 ignored issues – show Performance Best Practice introduced 2015-12-22 13:00 UTC by Report Bug Copy Issue Report It seems like you are calling the size function `count()` as part of the test condition. You might want to compute the size beforehand, and not on each iteration. If the size of the collection does not change during the iteration, it is generally a good practice to compute it beforehand, and not on each iteration: for ($i=0; $i<count($array); $i++) { // calls count() on each iteration } // Better for ($i=0, $c=count($array); $i<$c; $i++) { // calls count() just once } Loading history...
184	1	$lines[$i] = substr($lines[$i], $startingSpaceCount);
185		}
186		}
187
188	1	return implode("\n", $lines);
189		}
190
191		}
192

phpDocumentor / ReflectionDocBlock

Push — master ( 45ada3...ea48fd )

DescriptionFactory::lex() B

Complexity

Size

Duplication

Code Coverage

Importance

Duplication Side-by-Side

Filter issues like