PageRenderTime 51ms CodeModel.GetById 15ms RepoModel.GetById 0ms app.codeStats 1ms

/modules/userguide/classes/kohana/kodoc.php

https://bitbucket.org/thomasfortier/kohana_base
PHP | 354 lines | 214 code | 57 blank | 83 comment | 22 complexity | 06290f34cdd32d73cc0a5f54703fb124 MD5 | raw file
Possible License(s): BSD-3-Clause
  1. <?php defined('SYSPATH') or die('No direct script access.');
  2. /**
  3. * Documentation generator.
  4. *
  5. * @package Kohana/Userguide
  6. * @category Base
  7. * @author Kohana Team
  8. * @copyright (c) 2008-2009 Kohana Team
  9. * @license http://kohanaphp.com/license
  10. */
  11. class Kohana_Kodoc {
  12. /**
  13. * @var string PCRE fragment for matching 'Class', 'Class::method', 'Class::method()' or 'Class::$property'
  14. */
  15. public static $regex_class_member = '((\w++)(?:::(\$?\w++))?(?:\(\))?)';
  16. /**
  17. * Make a class#member API link using an array of matches from [Kodoc::$regex_class_member]
  18. *
  19. * @param array $matches array( 1 => link text, 2 => class name, [3 => member name] )
  20. * @return string
  21. */
  22. public static function link_class_member($matches)
  23. {
  24. $link = $matches[1];
  25. $class = $matches[2];
  26. $member = NULL;
  27. if (isset($matches[3]))
  28. {
  29. // If the first char is a $ it is a property, e.g. Kohana::$base_url
  30. if ($matches[3][0] === '$')
  31. {
  32. $member = '#property:'.substr($matches[3], 1);
  33. }
  34. else
  35. {
  36. $member = '#'.$matches[3];
  37. }
  38. }
  39. return HTML::anchor(Route::get('docs/api')->uri(array('class' => $class)).$member, $link, NULL, NULL, TRUE);
  40. }
  41. public static function factory($class)
  42. {
  43. return new Kodoc_Class($class);
  44. }
  45. /**
  46. * Creates an html list of all classes sorted by category (or package if no category)
  47. *
  48. * @return string the html for the menu
  49. */
  50. public static function menu()
  51. {
  52. $classes = Kodoc::classes();
  53. foreach ($classes as $class)
  54. {
  55. if (isset($classes['kohana_'.$class]))
  56. {
  57. // Remove extended classes
  58. unset($classes['kohana_'.$class]);
  59. }
  60. }
  61. ksort($classes);
  62. $menu = array();
  63. $route = Route::get('docs/api');
  64. foreach ($classes as $class)
  65. {
  66. $class = Kodoc_Class::factory($class);
  67. // Test if we should show this class
  68. if ( ! Kodoc::show_class($class))
  69. continue;
  70. $link = HTML::anchor($route->uri(array('class' => $class->class->name)), $class->class->name);
  71. if (isset($class->tags['package']))
  72. {
  73. foreach ($class->tags['package'] as $package)
  74. {
  75. if (isset($class->tags['category']))
  76. {
  77. foreach ($class->tags['category'] as $category)
  78. {
  79. $menu[$package][$category][] = $link;
  80. }
  81. }
  82. else
  83. {
  84. $menu[$package]['Base'][] = $link;
  85. }
  86. }
  87. }
  88. else
  89. {
  90. $menu['[Unknown]']['Base'][] = $link;
  91. }
  92. }
  93. // Sort the packages
  94. ksort($menu);
  95. return View::factory('userguide/api/menu')
  96. ->bind('menu', $menu);
  97. }
  98. /**
  99. * Returns an array of all the classes available, built by listing all files in the classes folder and then trying to create that class.
  100. *
  101. * This means any empty class files (as in complety empty) will cause an exception
  102. *
  103. * @param array array of files, obtained using Kohana::list_files
  104. * @return array an array of all the class names
  105. */
  106. public static function classes(array $list = NULL)
  107. {
  108. if ($list === NULL)
  109. {
  110. $list = Kohana::list_files('classes');
  111. }
  112. $classes = array();
  113. foreach ($list as $name => $path)
  114. {
  115. if (is_array($path))
  116. {
  117. $classes += Kodoc::classes($path);
  118. }
  119. else
  120. {
  121. // Remove "classes/" and the extension
  122. $class = substr($name, 8, -(strlen(EXT)));
  123. // Convert slashes to underscores
  124. $class = str_replace(DIRECTORY_SEPARATOR, '_', strtolower($class));
  125. $classes[$class] = $class;
  126. }
  127. }
  128. return $classes;
  129. }
  130. /**
  131. * Get all classes and methods of files in a list.
  132. *
  133. * > I personally don't like this as it was used on the index page. Way too much stuff on one page. It has potential for a package index page though.
  134. * > For example: class_methods( Kohana::list_files('classes/sprig') ) could make a nice index page for the sprig package in the api browser
  135. * > ~bluehawk
  136. *
  137. */
  138. public static function class_methods(array $list = NULL)
  139. {
  140. $list = Kodoc::classes($list);
  141. $classes = array();
  142. foreach ($list as $class)
  143. {
  144. $_class = new ReflectionClass($class);
  145. if (stripos($_class->name, 'Kohana_') === 0)
  146. {
  147. // Skip transparent extension classes
  148. continue;
  149. }
  150. $methods = array();
  151. foreach ($_class->getMethods() as $_method)
  152. {
  153. $declares = $_method->getDeclaringClass()->name;
  154. if (stripos($declares, 'Kohana_') === 0)
  155. {
  156. // Remove "Kohana_"
  157. $declares = substr($declares, 7);
  158. }
  159. if ($declares === $_class->name OR $declares === "Core")
  160. {
  161. $methods[] = $_method->name;
  162. }
  163. }
  164. sort($methods);
  165. $classes[$_class->name] = $methods;
  166. }
  167. return $classes;
  168. }
  169. /**
  170. * Parse a comment to extract the description and the tags
  171. *
  172. * @param string the comment retreived using ReflectionClass->getDocComment()
  173. * @return array array(string $description, array $tags)
  174. */
  175. public static function parse($comment)
  176. {
  177. // Normalize all new lines to \n
  178. $comment = str_replace(array("\r\n", "\n"), "\n", $comment);
  179. // Remove the phpdoc open/close tags and split
  180. $comment = array_slice(explode("\n", $comment), 1, -1);
  181. // Tag content
  182. $tags = array();
  183. foreach ($comment as $i => $line)
  184. {
  185. // Remove all leading whitespace
  186. $line = preg_replace('/^\s*\* ?/m', '', $line);
  187. // Search this line for a tag
  188. if (preg_match('/^@(\S+)(?:\s*(.+))?$/', $line, $matches))
  189. {
  190. // This is a tag line
  191. unset($comment[$i]);
  192. $name = $matches[1];
  193. $text = isset($matches[2]) ? $matches[2] : '';
  194. switch ($name)
  195. {
  196. case 'license':
  197. if (strpos($text, '://') !== FALSE)
  198. {
  199. // Convert the lincense into a link
  200. $text = HTML::anchor($text);
  201. }
  202. break;
  203. case 'link':
  204. $text = preg_split('/\s+/', $text, 2);
  205. $text = HTML::anchor($text[0], isset($text[1]) ? $text[1] : $text[0]);
  206. break;
  207. case 'copyright':
  208. if (strpos($text, '(c)') !== FALSE)
  209. {
  210. // Convert the copyright sign
  211. $text = str_replace('(c)', '&copy;', $text);
  212. }
  213. break;
  214. case 'throws':
  215. if (preg_match('/^(\w+)\W(.*)$/', $text, $matches))
  216. {
  217. $text = HTML::anchor(Route::get('docs/api')->uri(array('class' => $matches[1])), $matches[1]).' '.$matches[2];
  218. }
  219. else
  220. {
  221. $text = HTML::anchor(Route::get('docs/api')->uri(array('class' => $text)), $text);
  222. }
  223. break;
  224. case 'uses':
  225. if (preg_match('/^'.Kodoc::$regex_class_member.'$/i', $text, $matches))
  226. {
  227. $text = Kodoc::link_class_member($matches);
  228. }
  229. break;
  230. // Don't show @access lines, they are shown elsewhere
  231. case 'access':
  232. continue 2;
  233. }
  234. // Add the tag
  235. $tags[$name][] = $text;
  236. }
  237. else
  238. {
  239. // Overwrite the comment line
  240. $comment[$i] = (string) $line;
  241. }
  242. }
  243. // Concat the comment lines back to a block of text
  244. if ($comment = trim(implode("\n", $comment)))
  245. {
  246. // Parse the comment with Markdown
  247. $comment = Markdown($comment);
  248. }
  249. return array($comment, $tags);
  250. }
  251. /**
  252. * Get the source of a function
  253. *
  254. * @param string the filename
  255. * @param int start line?
  256. * @param int end line?
  257. */
  258. public static function source($file, $start, $end)
  259. {
  260. if ( ! $file) return FALSE;
  261. $file = file($file, FILE_IGNORE_NEW_LINES);
  262. $file = array_slice($file, $start - 1, $end - $start + 1);
  263. if (preg_match('/^(\s+)/', $file[0], $matches))
  264. {
  265. $padding = strlen($matches[1]);
  266. foreach ($file as & $line)
  267. {
  268. $line = substr($line, $padding);
  269. }
  270. }
  271. return implode("\n", $file);
  272. }
  273. /**
  274. * Test whether a class should be shown, based on the api_packages config option
  275. *
  276. * @param Kodoc_Class the class to test
  277. * @return bool whether this class should be shown
  278. */
  279. public static function show_class(Kodoc_Class $class)
  280. {
  281. $api_packages = Kohana::$config->load('userguide.api_packages');
  282. // If api_packages is true, all packages should be shown
  283. if ($api_packages === TRUE)
  284. return TRUE;
  285. // Get the package tags for this class (as an array)
  286. $packages = Arr::get($class->tags, 'package', array('None'));
  287. $show_this = FALSE;
  288. // Loop through each package tag
  289. foreach ($packages as $package)
  290. {
  291. // If this package is in the allowed packages, set show this to true
  292. if (in_array($package, explode(',', $api_packages)))
  293. $show_this = TRUE;
  294. }
  295. return $show_this;
  296. }
  297. } // End Kodoc