4 * This file is part of Psy Shell.
6 * (c) 2012-2017 Justin Hileman
8 * For the full copyright and license information, please view the LICENSE
9 * file that was distributed with this source code.
15 * A docblock representation.
17 * Based on PHP-DocBlock-Parser by Paul Scott:
19 * {@link http://www.github.com/icio/PHP-DocBlock-Parser}
21 * @author Paul Scott <paul@duedil.com>
22 * @author Justin Hileman <justin@justinhileman.info>
27 * Tags in the docblock that have a whitespace-delimited number of parameters
28 * (such as `@param type var desc` and `@return type desc`) and the names of
33 public static $vectors = array(
34 'throws' => array('type', 'desc'),
35 'param' => array('type', 'var', 'desc'),
36 'return' => array('type', 'desc'),
42 * The description of the symbol.
49 * The tags defined in the docblock.
51 * The array has keys which are the tag names (excluding the @) and values
52 * that are arrays, each of which is an entry for the tag.
54 * In the case where the tag name is defined in {@see DocBlock::$vectors} the
55 * value within the tag-value array is an array in itself with keys as
56 * described by {@see DocBlock::$vectors}.
63 * The entire DocBlock comment that was parsed.
70 * Docblock constructor.
72 * @param \Reflector $reflector
74 public function __construct(\Reflector $reflector)
76 $this->reflector = $reflector;
77 $this->setComment($reflector->getDocComment());
81 * Set and parse the docblock comment.
83 * @param string $comment The docblock
85 protected function setComment($comment)
88 $this->tags = array();
89 $this->comment = $comment;
91 $this->parseComment($comment);
95 * Find the length of the docblock prefix.
99 * @return int Prefix length
101 protected static function prefixLength(array $lines)
103 // find only lines with interesting things
104 $lines = array_filter($lines, function ($line) {
105 return substr($line, strspn($line, "* \t\n\r\0\x0B"));
108 // if we sort the lines, we only have to compare two items
111 $first = reset($lines);
114 // find the longest common substring
115 $count = min(strlen($first), strlen($last));
116 for ($i = 0; $i < $count; $i++) {
117 if ($first[$i] !== $last[$i]) {
126 * Parse the comment into the component parts and set the state of the object.
128 * @param string $comment The docblock
130 protected function parseComment($comment)
132 // Strip the opening and closing tags of the docblock
133 $comment = substr($comment, 3, -2);
135 // Split into arrays of lines
136 $comment = array_filter(preg_split('/\r?\n\r?/', $comment));
138 // Trim asterisks and whitespace from the beginning and whitespace from the end of lines
139 $prefixLength = self::prefixLength($comment);
140 $comment = array_map(function ($line) use ($prefixLength) {
141 return rtrim(substr($line, $prefixLength));
144 // Group the lines together by @tags
147 foreach ($comment as $line) {
148 if (self::isTagged($line)) {
151 } elseif ($b === -1) {
155 $blocks[$b][] = $line;
159 foreach ($blocks as $block => $body) {
160 $body = trim(implode("\n", $body));
162 if ($block === 0 && !self::isTagged($body)) {
163 // This is the description block
166 // This block is tagged
167 $tag = substr(self::strTag($body), 1);
168 $body = ltrim(substr($body, strlen($tag) + 2));
170 if (isset(self::$vectors[$tag])) {
171 // The tagged block is a vector
172 $count = count(self::$vectors[$tag]);
174 $parts = preg_split('/\s+/', $body, $count);
179 // Default the trailing values
180 $parts = array_pad($parts, $count, null);
182 // Store as a mapped array
183 $this->tags[$tag][] = array_combine(self::$vectors[$tag], $parts);
185 // The tagged block is only text
186 $this->tags[$tag][] = $body;
193 * Whether or not a docblock contains a given @tag.
195 * @param string $tag The name of the @tag to check for
199 public function hasTag($tag)
201 return is_array($this->tags) && array_key_exists($tag, $this->tags);
205 * The value of a tag.
211 public function tag($tag)
213 return $this->hasTag($tag) ? $this->tags[$tag] : null;
217 * Whether or not a string begins with a @tag.
223 public static function isTagged($str)
225 return isset($str[1]) && $str[0] === '@' && ctype_alpha($str[1]);
229 * The tag at the beginning of a string.
233 * @return string|null
235 public static function strTag($str)
237 if (preg_match('/^@[a-z0-9_]+/', $str, $matches)) {