Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 122 lines (108 sloc) 3.588 kb
e7f3c313 » gwoo
2009-10-12 going lithium
1 <?php
2 /**
3 * Lithium: the most rad php framework
4 *
14de7bf7 » gwoo
2012-01-02 Happy 2012!
5 * @copyright Copyright 2012, Union of RAD (http://union-of-rad.org)
e7f3c313 » gwoo
2009-10-12 going lithium
6 * @license http://opensource.org/licenses/bsd-license.php The BSD License
7 */
8
33eafcca » nateabele
2010-01-13 Moving all classes in `util\reflection` to `analysis` package. Removi…
9 namespace lithium\analysis;
e7f3c313 » gwoo
2009-10-12 going lithium
10
2499b21f » jperras
2009-11-16 Adding doc blocks for util\reflection\Docblock
11 /**
12 * A source code doc block parser.
13 *
14 * This parser may be used as the basis for a variety of secondary tools, including
1dab0c32 » nateabele
2010-04-22 Adding / updating docblocks for classes in `\analysis`.
15 * a reflection-based API generator, a code metrics analyzer, and various other code or structural
16 * analysis tools.
2499b21f » jperras
2009-11-16 Adding doc blocks for util\reflection\Docblock
17 */
e7f3c313 » gwoo
2009-10-12 going lithium
18 class Docblock extends \lithium\core\StaticObject {
19
20 /**
453e1ab4 » nateabele
2010-04-20 Refactored `\analysis\Docblock`, fixed misc docblock tag parsing issu…
21 * List of supported docblock tags.
22 *
23 * @var array
24 */
25 public static $tags = array(
26 'todo', 'discuss', 'fix', 'important', 'var',
27 'param', 'return', 'throws', 'see', 'link',
a9ebcd5c » nateabele
2010-07-09 Refactoring `\net\http\Media` to move code for finding physical asset…
28 'task', 'dependencies', 'filter'
453e1ab4 » nateabele
2010-04-20 Refactored `\analysis\Docblock`, fixed misc docblock tag parsing issu…
29 );
30
31 /**
2499b21f » jperras
2009-11-16 Adding doc blocks for util\reflection\Docblock
32 * Parses a doc block into its major components of `description`, `text` and `tags`.
e7f3c313 » gwoo
2009-10-12 going lithium
33 *
453e1ab4 » nateabele
2010-04-20 Refactored `\analysis\Docblock`, fixed misc docblock tag parsing issu…
34 * @param string $comment The doc block string to be parsed
2499b21f » jperras
2009-11-16 Adding doc blocks for util\reflection\Docblock
35 * @return array An associative array of the parsed comment, whose keys are `description`,
453e1ab4 » nateabele
2010-04-20 Refactored `\analysis\Docblock`, fixed misc docblock tag parsing issu…
36 * `text` and `tags`.
e7f3c313 » gwoo
2009-10-12 going lithium
37 */
453e1ab4 » nateabele
2010-04-20 Refactored `\analysis\Docblock`, fixed misc docblock tag parsing issu…
38 public static function comment($comment) {
e7f3c313 » gwoo
2009-10-12 going lithium
39 $text = null;
40 $tags = array();
453e1ab4 » nateabele
2010-04-20 Refactored `\analysis\Docblock`, fixed misc docblock tag parsing issu…
41 $description = null;
556b6d0f » nateabele
2010-09-20 Fixing issue with parsing docblocks with two `**` in the closing deli…
42 $comment = trim(preg_replace('/^(\s*\/\*\*|\s*\*{1,2}\/|\s*\* ?)/m', '', $comment));
28d1afc3 » nateabele
2010-06-27 Updating `\analysis\Docblock::comment()` to account for Windows newli…
43 $comment = str_replace("\r\n", "\n", $comment);
e7f3c313 » gwoo
2009-10-12 going lithium
44
453e1ab4 » nateabele
2010-04-20 Refactored `\analysis\Docblock`, fixed misc docblock tag parsing issu…
45 if ($items = preg_split('/\n@/ms', $comment, 2)) {
46 list($description, $tags) = $items + array('', '');
47 $tags = $tags ? static::tags("@{$tags}") : array();
e7f3c313 » gwoo
2009-10-12 going lithium
48 }
49
50 if (strpos($description, "\n\n")) {
51 list($description, $text) = explode("\n\n", $description, 2);
52 }
53 $text = trim($text);
54 $description = trim($description);
55 return compact('description', 'text', 'tags');
56 }
57
58 /**
33eafcca » nateabele
2010-01-13 Moving all classes in `util\reflection` to `analysis` package. Removi…
59 * Parses `@<tagname>` docblock tags and their descriptions from a docblock.
2499b21f » jperras
2009-11-16 Adding doc blocks for util\reflection\Docblock
60 *
453e1ab4 » nateabele
2010-04-20 Refactored `\analysis\Docblock`, fixed misc docblock tag parsing issu…
61 * See the `$tags` property for the list of supported tags.
e7f3c313 » gwoo
2009-10-12 going lithium
62 *
453e1ab4 » nateabele
2010-04-20 Refactored `\analysis\Docblock`, fixed misc docblock tag parsing issu…
63 * @param string $string The string to be parsed for tags
64 * @return array Returns an array where each docblock tag is a key name, and the corresponding
65 * values are either strings (if one of each tag), or arrays (if multiple of the same
66 * tag).
e7f3c313 » gwoo
2009-10-12 going lithium
67 */
453e1ab4 » nateabele
2010-04-20 Refactored `\analysis\Docblock`, fixed misc docblock tag parsing issu…
68 public static function tags($string) {
69 $regex = '/\n@(?P<type>' . join('|', static::$tags) . ")/msi";
70 $string = trim($string);
e7f3c313 » gwoo
2009-10-12 going lithium
71
28d1afc3 » nateabele
2010-06-27 Updating `\analysis\Docblock::comment()` to account for Windows newli…
72 $result = preg_split($regex, "\n$string", -1, PREG_SPLIT_DELIM_CAPTURE);
453e1ab4 » nateabele
2010-04-20 Refactored `\analysis\Docblock`, fixed misc docblock tag parsing issu…
73 $tags = array();
74
75 for ($i = 1; $i < count($result) - 1; $i += 2) {
76 $type = trim(strtolower($result[$i]));
77 $text = trim($result[$i + 1]);
78
79 if (isset($tags[$type])) {
80 $tags[$type] = is_array($tags[$type]) ? $tags[$type] : (array) $tags[$type];
81 $tags[$type][] = $text;
82 } else {
83 $tags[$type] = $text;
84 }
e7f3c313 » gwoo
2009-10-12 going lithium
85 }
86
453e1ab4 » nateabele
2010-04-20 Refactored `\analysis\Docblock`, fixed misc docblock tag parsing issu…
87 if (isset($tags['param'])) {
88 $params = $tags['param'];
89 $tags['params'] = static::_params((array) $tags['param']);
90 unset($tags['param']);
91 }
92 return $tags;
93 }
94
95 /**
2b7c21dd » Howard3
2011-06-12 Doing a general QA and Docblock
96 * Parses `@param` docblock tags to separate out the parameter type from the description.
453e1ab4 » nateabele
2010-04-20 Refactored `\analysis\Docblock`, fixed misc docblock tag parsing issu…
97 *
98 * @param array $params An array of `@param` tags, as parsed from the `tags()` method.
99 * @return array Returns an array where each key is a parameter name, and each value is an
100 * associative array containing `'type'` and `'text'` keys.
101 */
102 protected static function _params(array $params) {
103 $result = array();
104 foreach ($params as $param) {
105 $param = explode(' ', $param, 3);
106 $type = $name = $text = null;
107
108 foreach (array('type', 'name', 'text') as $i => $key) {
109 if (!isset($param[$i])) {
110 break;
111 }
112 ${$key} = $param[$i];
113 }
114 if ($name) {
115 $result[$name] = compact('type', 'text');
116 }
e7f3c313 » gwoo
2009-10-12 going lithium
117 }
453e1ab4 » nateabele
2010-04-20 Refactored `\analysis\Docblock`, fixed misc docblock tag parsing issu…
118 return $result;
e7f3c313 » gwoo
2009-10-12 going lithium
119 }
120 }
121
122 ?>
Something went wrong with that request. Please try again.