Kohana v3.3.0
This commit is contained in:
Deon George
398
modules/userguide/classes/Kohana/Controller/Userguide.php
Normal file
398
modules/userguide/classes/Kohana/Controller/Userguide.php
Normal file
@@ -0,0 +1,398 @@
|
||||
<?php defined('SYSPATH') or die('No direct script access.');
|
||||
/**
|
||||
* Kohana user guide and api browser.
|
||||
*
|
||||
* @package Kohana/Userguide
|
||||
* @category Controllers
|
||||
* @author Kohana Team
|
||||
*/
|
||||
abstract class Kohana_Controller_Userguide extends Controller_Template {
|
||||
|
||||
public $template = 'userguide/template';
|
||||
|
||||
// Routes
|
||||
protected $media;
|
||||
protected $api;
|
||||
protected $guide;
|
||||
|
||||
public function before()
|
||||
{
|
||||
parent::before();
|
||||
|
||||
if ($this->request->action() === 'media')
|
||||
{
|
||||
// Do not template media files
|
||||
$this->auto_render = FALSE;
|
||||
}
|
||||
else
|
||||
{
|
||||
// Grab the necessary routes
|
||||
$this->media = Route::get('docs/media');
|
||||
$this->guide = Route::get('docs/guide');
|
||||
|
||||
// Set the base URL for links and images
|
||||
Kodoc_Markdown::$base_url = URL::site($this->guide->uri()).'/';
|
||||
Kodoc_Markdown::$image_url = URL::site($this->media->uri()).'/';
|
||||
}
|
||||
|
||||
// Default show_comments to config value
|
||||
$this->template->show_comments = Kohana::$config->load('userguide.show_comments');
|
||||
}
|
||||
|
||||
// List all modules that have userguides
|
||||
public function index()
|
||||
{
|
||||
$this->template->title = "Userguide";
|
||||
$this->template->breadcrumb = array('User Guide');
|
||||
$this->template->content = View::factory('userguide/index', array('modules' => $this->_modules()));
|
||||
$this->template->menu = View::factory('userguide/menu', array('modules' => $this->_modules()));
|
||||
|
||||
// Don't show disqus on the index page
|
||||
$this->template->show_comments = FALSE;
|
||||
}
|
||||
|
||||
// Display an error if a page isn't found
|
||||
public function error($message)
|
||||
{
|
||||
$this->response->status(404);
|
||||
$this->template->title = "Userguide - Error";
|
||||
$this->template->content = View::factory('userguide/error',array('message' => $message));
|
||||
|
||||
// Don't show disqus on error pages
|
||||
$this->template->show_comments = FALSE;
|
||||
|
||||
// If we are in a module and that module has a menu, show that
|
||||
if ($module = $this->request->param('module') AND $menu = $this->file($module.'/menu') AND Kohana::$config->load('userguide.modules.'.$module.'.enabled'))
|
||||
{
|
||||
// Namespace the markdown parser
|
||||
Kodoc_Markdown::$base_url = URL::site($this->guide->uri()).'/'.$module.'/';
|
||||
Kodoc_Markdown::$image_url = URL::site($this->media->uri()).'/'.$module.'/';
|
||||
|
||||
$this->template->menu = Kodoc_Markdown::markdown($this->_get_all_menu_markdown());
|
||||
$this->template->breadcrumb = array(
|
||||
$this->guide->uri() => 'User Guide',
|
||||
$this->guide->uri(array('module' => $module)) => Kohana::$config->load('userguide.modules.'.$module.'.name'),
|
||||
'Error'
|
||||
);
|
||||
}
|
||||
// If we are in the api browser, show the menu and show the api browser in the breadcrumbs
|
||||
else if (Route::name($this->request->route()) == 'docs/api')
|
||||
{
|
||||
$this->template->menu = Kodoc::menu();
|
||||
|
||||
// Bind the breadcrumb
|
||||
$this->template->breadcrumb = array(
|
||||
$this->guide->uri(array('page' => NULL)) => 'User Guide',
|
||||
$this->request->route()->uri() => 'API Browser',
|
||||
'Error'
|
||||
);
|
||||
}
|
||||
// Otherwise, show the userguide module menu on the side
|
||||
else
|
||||
{
|
||||
$this->template->menu = View::factory('userguide/menu',array('modules' => $this->_modules()));
|
||||
$this->template->breadcrumb = array($this->request->route()->uri() => 'User Guide','Error');
|
||||
}
|
||||
}
|
||||
|
||||
public function action_docs()
|
||||
{
|
||||
$module = $this->request->param('module');
|
||||
$page = $this->request->param('page');
|
||||
|
||||
// Trim trailing slash
|
||||
$page = rtrim($page, '/');
|
||||
|
||||
// If no module provided in the url, show the user guide index page, which lists the modules.
|
||||
if ( ! $module)
|
||||
{
|
||||
return $this->index();
|
||||
}
|
||||
|
||||
// If this module's userguide pages are disabled, show the error page
|
||||
if ( ! Kohana::$config->load('userguide.modules.'.$module.'.enabled'))
|
||||
{
|
||||
return $this->error('That module doesn\'t exist, or has userguide pages disabled.');
|
||||
}
|
||||
|
||||
// Prevent "guide/module" and "guide/module/index" from having duplicate content
|
||||
if ( $page == 'index')
|
||||
{
|
||||
return $this->error('Userguide page not found');
|
||||
}
|
||||
|
||||
// If a module is set, but no page was provided in the url, show the index page
|
||||
if ( ! $page )
|
||||
{
|
||||
$page = 'index';
|
||||
}
|
||||
|
||||
// Find the markdown file for this page
|
||||
$file = $this->file($module.'/'.$page);
|
||||
|
||||
// If it's not found, show the error page
|
||||
if ( ! $file)
|
||||
{
|
||||
return $this->error('Userguide page not found');
|
||||
}
|
||||
|
||||
// Namespace the markdown parser
|
||||
Kodoc_Markdown::$base_url = URL::site($this->guide->uri()).'/'.$module.'/';
|
||||
Kodoc_Markdown::$image_url = URL::site($this->media->uri()).'/'.$module.'/';
|
||||
|
||||
// Set the page title
|
||||
$this->template->title = $page == 'index' ? Kohana::$config->load('userguide.modules.'.$module.'.name') : $this->title($page);
|
||||
|
||||
// Parse the page contents into the template
|
||||
Kodoc_Markdown::$show_toc = true;
|
||||
$this->template->content = Kodoc_Markdown::markdown(file_get_contents($file));
|
||||
Kodoc_Markdown::$show_toc = false;
|
||||
|
||||
// Attach this module's menu to the template
|
||||
$this->template->menu = Kodoc_Markdown::markdown($this->_get_all_menu_markdown());
|
||||
|
||||
// Bind the breadcrumb
|
||||
$this->template->bind('breadcrumb', $breadcrumb);
|
||||
|
||||
// Bind the copyright
|
||||
$this->template->copyright = Kohana::$config->load('userguide.modules.'.$module.'.copyright');
|
||||
|
||||
// Add the breadcrumb trail
|
||||
$breadcrumb = array();
|
||||
$breadcrumb[$this->guide->uri()] = 'User Guide';
|
||||
$breadcrumb[$this->guide->uri(array('module' => $module))] = Kohana::$config->load('userguide.modules.'.$module.'.name');
|
||||
|
||||
// TODO try and get parent category names (from menu). Regex magic or javascript dom stuff perhaps?
|
||||
|
||||
// Only add the current page title to breadcrumbs if it isn't the index, otherwise we get repeats.
|
||||
if ($page != 'index')
|
||||
{
|
||||
$breadcrumb[] = $this->template->title;
|
||||
}
|
||||
}
|
||||
|
||||
public function action_api()
|
||||
{
|
||||
// Enable the missing class autoloader. If a class cannot be found a
|
||||
// fake class will be created that extends Kodoc_Missing
|
||||
spl_autoload_register(array('Kodoc_Missing', 'create_class'));
|
||||
|
||||
// Get the class from the request
|
||||
$class = $this->request->param('class');
|
||||
|
||||
// If no class was passed to the url, display the API index page
|
||||
if ( ! $class)
|
||||
{
|
||||
$this->template->title = 'Table of Contents';
|
||||
|
||||
$this->template->content = View::factory('userguide/api/toc')
|
||||
->set('classes', Kodoc::class_methods())
|
||||
->set('route', $this->request->route());
|
||||
}
|
||||
else
|
||||
{
|
||||
// Create the Kodoc_Class version of this class.
|
||||
$_class = Kodoc_Class::factory($class);
|
||||
|
||||
// If the class requested and the actual class name are different
|
||||
// (different case, orm vs ORM, auth vs Auth) redirect
|
||||
if ($_class->class->name != $class)
|
||||
{
|
||||
$this->request->redirect($this->request->route()->uri(array('class'=>$_class->class->name)));
|
||||
}
|
||||
|
||||
// If this classes immediate parent is Kodoc_Missing, then it should 404
|
||||
if ($_class->class->getParentClass() AND $_class->class->getParentClass()->name == 'Kodoc_Missing')
|
||||
return $this->error('That class was not found. Check your url and make sure that the module with that class is enabled.');
|
||||
|
||||
// If this classes package has been disabled via the config, 404
|
||||
if ( ! Kodoc::show_class($_class))
|
||||
return $this->error('That class is in package that is hidden. Check the <code>api_packages</code> config setting.');
|
||||
|
||||
// Everything is fine, display the class.
|
||||
$this->template->title = $class;
|
||||
|
||||
$this->template->content = View::factory('userguide/api/class')
|
||||
->set('doc', $_class)
|
||||
->set('route', $this->request->route());
|
||||
}
|
||||
|
||||
// Attach the menu to the template
|
||||
$this->template->menu = Kodoc::menu();
|
||||
|
||||
// Bind the breadcrumb
|
||||
$this->template->bind('breadcrumb', $breadcrumb);
|
||||
|
||||
// Add the breadcrumb
|
||||
$breadcrumb = array();
|
||||
$breadcrumb[$this->guide->uri(array('page' => NULL))] = 'User Guide';
|
||||
$breadcrumb[$this->request->route()->uri()] = 'API Browser';
|
||||
$breadcrumb[] = $this->template->title;
|
||||
}
|
||||
|
||||
public function action_media()
|
||||
{
|
||||
// Get the file path from the request
|
||||
$file = $this->request->param('file');
|
||||
|
||||
// Find the file extension
|
||||
$ext = pathinfo($file, PATHINFO_EXTENSION);
|
||||
|
||||
// Remove the extension from the filename
|
||||
$file = substr($file, 0, -(strlen($ext) + 1));
|
||||
|
||||
if ($file = Kohana::find_file('media/guide', $file, $ext))
|
||||
{
|
||||
// Check if the browser sent an "if-none-match: <etag>" header, and tell if the file hasn't changed
|
||||
$this->check_cache(sha1($this->request->uri()).filemtime($file));
|
||||
|
||||
// Send the file content as the response
|
||||
$this->response->body(file_get_contents($file));
|
||||
|
||||
// Set the proper headers to allow caching
|
||||
$this->response->headers('content-type', File::mime_by_ext($ext));
|
||||
$this->response->headers('last-modified', date('r', filemtime($file)));
|
||||
}
|
||||
else
|
||||
{
|
||||
// Return a 404 status
|
||||
$this->response->status(404);
|
||||
}
|
||||
}
|
||||
|
||||
public function after()
|
||||
{
|
||||
if ($this->auto_render)
|
||||
{
|
||||
// Get the media route
|
||||
$media = Route::get('docs/media');
|
||||
|
||||
// Add styles
|
||||
$this->template->styles = array(
|
||||
$media->uri(array('file' => 'css/print.css')) => 'print',
|
||||
$media->uri(array('file' => 'css/screen.css')) => 'screen',
|
||||
$media->uri(array('file' => 'css/kodoc.css')) => 'screen',
|
||||
$media->uri(array('file' => 'css/shCore.css')) => 'screen',
|
||||
$media->uri(array('file' => 'css/shThemeKodoc.css')) => 'screen',
|
||||
);
|
||||
|
||||
// Add scripts
|
||||
$this->template->scripts = array(
|
||||
$media->uri(array('file' => 'js/jquery.min.js')),
|
||||
$media->uri(array('file' => 'js/jquery.cookie.js')),
|
||||
$media->uri(array('file' => 'js/kodoc.js')),
|
||||
// Syntax Highlighter
|
||||
$media->uri(array('file' => 'js/shCore.js')),
|
||||
$media->uri(array('file' => 'js/shBrushPhp.js')),
|
||||
);
|
||||
|
||||
// Add languages
|
||||
$this->template->translations = Kohana::message('userguide', 'translations');
|
||||
}
|
||||
|
||||
return parent::after();
|
||||
}
|
||||
|
||||
/**
|
||||
* Locates the appropriate markdown file for a given guide page. Page URLS
|
||||
* can be specified in one of three forms:
|
||||
*
|
||||
* * userguide/adding
|
||||
* * userguide/adding.md
|
||||
* * userguide/adding.markdown
|
||||
*
|
||||
* In every case, the userguide will search the cascading file system paths
|
||||
* for the file guide/userguide/adding.md.
|
||||
*
|
||||
* @param string $page The relative URL of the guide page
|
||||
* @return string
|
||||
*/
|
||||
public function file($page)
|
||||
{
|
||||
|
||||
// Strip optional .md or .markdown suffix from the passed filename
|
||||
$info = pathinfo($page);
|
||||
if (isset($info['extension'])
|
||||
AND (($info['extension'] === 'md') OR ($info['extension'] === 'markdown')))
|
||||
{
|
||||
$page = $info['dirname'].DIRECTORY_SEPARATOR.$info['filename'];
|
||||
}
|
||||
return Kohana::find_file('guide', $page, 'md');
|
||||
}
|
||||
|
||||
public function section($page)
|
||||
{
|
||||
$markdown = $this->_get_all_menu_markdown();
|
||||
|
||||
if (preg_match('~\*{2}(.+?)\*{2}[^*]+\[[^\]]+\]\('.preg_quote($page).'\)~mu', $markdown, $matches))
|
||||
{
|
||||
return $matches[1];
|
||||
}
|
||||
|
||||
return $page;
|
||||
}
|
||||
|
||||
public function title($page)
|
||||
{
|
||||
$markdown = $this->_get_all_menu_markdown();
|
||||
|
||||
if (preg_match('~\[([^\]]+)\]\('.preg_quote($page).'\)~mu', $markdown, $matches))
|
||||
{
|
||||
// Found a title for this link
|
||||
return $matches[1];
|
||||
}
|
||||
|
||||
return $page;
|
||||
}
|
||||
|
||||
protected function _get_all_menu_markdown()
|
||||
{
|
||||
// Only do this once per request...
|
||||
static $markdown = '';
|
||||
|
||||
if (empty($markdown))
|
||||
{
|
||||
// Get menu items
|
||||
$file = $this->file($this->request->param('module').'/menu');
|
||||
|
||||
if ($file AND $text = file_get_contents($file))
|
||||
{
|
||||
// Add spans around non-link categories. This is a terrible hack.
|
||||
//echo Debug::vars($text);
|
||||
|
||||
//$text = preg_replace('/(\s*[\-\*\+]\s*)(.*)/','$1<span>$2</span>',$text);
|
||||
$text = preg_replace('/^(\s*[\-\*\+]\s*)([^\[\]]+)$/m','$1<span>$2</span>',$text);
|
||||
//echo Debug::vars($text);
|
||||
$markdown .= $text;
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
return $markdown;
|
||||
}
|
||||
|
||||
// Get the list of modules from the config, and reverses it so it displays in the order the modules are added, but move Kohana to the top.
|
||||
protected function _modules()
|
||||
{
|
||||
$modules = array_reverse(Kohana::$config->load('userguide.modules'));
|
||||
|
||||
if (isset($modules['kohana']))
|
||||
{
|
||||
$kohana = $modules['kohana'];
|
||||
unset($modules['kohana']);
|
||||
$modules = array_merge(array('kohana' => $kohana), $modules);
|
||||
}
|
||||
|
||||
// Remove modules that have been disabled via config
|
||||
foreach ($modules as $key => $value)
|
||||
{
|
||||
if ( ! Kohana::$config->load('userguide.modules.'.$key.'.enabled'))
|
||||
{
|
||||
unset($modules[$key]);
|
||||
}
|
||||
}
|
||||
|
||||
return $modules;
|
||||
}
|
||||
|
||||
} // End Userguide
|
||||
466
modules/userguide/classes/Kohana/Kodoc.php
Normal file
466
modules/userguide/classes/Kohana/Kodoc.php
Normal file
@@ -0,0 +1,466 @@
|
||||
<?php defined('SYSPATH') or die('No direct script access.');
|
||||
/**
|
||||
* Documentation generator.
|
||||
*
|
||||
* @package Kohana/Userguide
|
||||
* @category Base
|
||||
* @author Kohana Team
|
||||
* @copyright (c) 2008-2012 Kohana Team
|
||||
* @license http://kohanaphp.com/license
|
||||
*/
|
||||
class Kohana_Kodoc {
|
||||
|
||||
/**
|
||||
* @var string PCRE fragment for matching 'Class', 'Class::method', 'Class::method()' or 'Class::$property'
|
||||
*/
|
||||
public static $regex_class_member = '((\w++)(?:::(\$?\w++))?(?:\(\))?)';
|
||||
|
||||
/**
|
||||
* Make a class#member API link using an array of matches from [Kodoc::$regex_class_member]
|
||||
*
|
||||
* @param array $matches array( 1 => link text, 2 => class name, [3 => member name] )
|
||||
* @return string
|
||||
*/
|
||||
public static function link_class_member($matches)
|
||||
{
|
||||
$link = $matches[1];
|
||||
$class = $matches[2];
|
||||
$member = NULL;
|
||||
|
||||
if (isset($matches[3]))
|
||||
{
|
||||
// If the first char is a $ it is a property, e.g. Kohana::$base_url
|
||||
if ($matches[3][0] === '$')
|
||||
{
|
||||
$member = '#property:'.substr($matches[3], 1);
|
||||
}
|
||||
else
|
||||
{
|
||||
$member = '#'.$matches[3];
|
||||
}
|
||||
}
|
||||
|
||||
return HTML::anchor(Route::get('docs/api')->uri(array('class' => $class)).$member, $link, NULL, NULL, TRUE);
|
||||
}
|
||||
|
||||
public static function factory($class)
|
||||
{
|
||||
return new Kodoc_Class($class);
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates an html list of all classes sorted by category (or package if no category)
|
||||
*
|
||||
* @return string the html for the menu
|
||||
*/
|
||||
public static function menu()
|
||||
{
|
||||
$classes = Kodoc::classes();
|
||||
|
||||
ksort($classes);
|
||||
|
||||
$menu = array();
|
||||
|
||||
$route = Route::get('docs/api');
|
||||
|
||||
foreach ($classes as $class)
|
||||
{
|
||||
if (Kodoc::is_transparent($class, $classes))
|
||||
continue;
|
||||
|
||||
$class = Kodoc_Class::factory($class);
|
||||
|
||||
// Test if we should show this class
|
||||
if ( ! Kodoc::show_class($class))
|
||||
continue;
|
||||
|
||||
$link = HTML::anchor($route->uri(array('class' => $class->class->name)), $class->class->name);
|
||||
|
||||
if (isset($class->tags['package']))
|
||||
{
|
||||
foreach ($class->tags['package'] as $package)
|
||||
{
|
||||
if (isset($class->tags['category']))
|
||||
{
|
||||
foreach ($class->tags['category'] as $category)
|
||||
{
|
||||
$menu[$package][$category][] = $link;
|
||||
}
|
||||
}
|
||||
else
|
||||
{
|
||||
$menu[$package]['Base'][] = $link;
|
||||
}
|
||||
}
|
||||
}
|
||||
else
|
||||
{
|
||||
$menu['[Unknown]']['Base'][] = $link;
|
||||
}
|
||||
}
|
||||
|
||||
// Sort the packages
|
||||
ksort($menu);
|
||||
|
||||
return View::factory('userguide/api/menu')
|
||||
->bind('menu', $menu);
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns an array of all the classes available, built by listing all files in the classes folder.
|
||||
*
|
||||
* @param array array of files, obtained using Kohana::list_files
|
||||
* @return array an array of all the class names
|
||||
*/
|
||||
public static function classes(array $list = NULL)
|
||||
{
|
||||
if ($list === NULL)
|
||||
{
|
||||
$list = Kohana::list_files('classes');
|
||||
}
|
||||
|
||||
$classes = array();
|
||||
|
||||
// This will be used a lot!
|
||||
$ext_length = strlen(EXT);
|
||||
|
||||
foreach ($list as $name => $path)
|
||||
{
|
||||
if (is_array($path))
|
||||
{
|
||||
$classes += Kodoc::classes($path);
|
||||
}
|
||||
elseif (substr($name, -$ext_length) === EXT)
|
||||
{
|
||||
// Remove "classes/" and the extension
|
||||
$class = substr($name, 8, -$ext_length);
|
||||
|
||||
// Convert slashes to underscores
|
||||
$class = str_replace(DIRECTORY_SEPARATOR, '_', $class);
|
||||
|
||||
$classes[$class] = $class;
|
||||
}
|
||||
}
|
||||
|
||||
return $classes;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all classes and methods of files in a list.
|
||||
*
|
||||
* > 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.
|
||||
* > For example: class_methods( Kohana::list_files('classes/sprig') ) could make a nice index page for the sprig package in the api browser
|
||||
* > ~bluehawk
|
||||
*
|
||||
*/
|
||||
public static function class_methods(array $list = NULL)
|
||||
{
|
||||
$list = Kodoc::classes($list);
|
||||
|
||||
$classes = array();
|
||||
|
||||
foreach ($list as $class)
|
||||
{
|
||||
// Skip transparent extension classes
|
||||
if (Kodoc::is_transparent($class))
|
||||
continue;
|
||||
|
||||
$_class = new ReflectionClass($class);
|
||||
|
||||
$methods = array();
|
||||
|
||||
foreach ($_class->getMethods() as $_method)
|
||||
{
|
||||
$declares = $_method->getDeclaringClass()->name;
|
||||
|
||||
// Remove the transparent prefix from declaring classes
|
||||
if ($child = Kodoc::is_transparent($declares))
|
||||
{
|
||||
$declares = $child;
|
||||
}
|
||||
|
||||
if ($declares === $_class->name OR $declares === "Core")
|
||||
{
|
||||
$methods[] = $_method->name;
|
||||
}
|
||||
}
|
||||
|
||||
sort($methods);
|
||||
|
||||
$classes[$_class->name] = $methods;
|
||||
}
|
||||
|
||||
return $classes;
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate HTML for the content of a tag.
|
||||
*
|
||||
* @param string $tag Name of the tag without @
|
||||
* @param string $text Content of the tag
|
||||
* @return string HTML
|
||||
*/
|
||||
public static function format_tag($tag, $text)
|
||||
{
|
||||
if ($tag === 'license')
|
||||
{
|
||||
if (strpos($text, '://') !== FALSE)
|
||||
return HTML::anchor($text);
|
||||
}
|
||||
elseif ($tag === 'link')
|
||||
{
|
||||
$split = preg_split('/\s+/', $text, 2);
|
||||
|
||||
return HTML::anchor(
|
||||
$split[0],
|
||||
isset($split[1]) ? $split[1] : $split[0]
|
||||
);
|
||||
}
|
||||
elseif ($tag === 'copyright')
|
||||
{
|
||||
// Convert the copyright symbol
|
||||
return str_replace('(c)', '©', $text);
|
||||
}
|
||||
elseif ($tag === 'throws')
|
||||
{
|
||||
$route = Route::get('docs/api');
|
||||
|
||||
if (preg_match('/^(\w+)\W(.*)$/D', $text, $matches))
|
||||
{
|
||||
return HTML::anchor(
|
||||
$route->uri(array('class' => $matches[1])),
|
||||
$matches[1]
|
||||
).' '.$matches[2];
|
||||
}
|
||||
|
||||
return HTML::anchor(
|
||||
$route->uri(array('class' => $text)),
|
||||
$text
|
||||
);
|
||||
}
|
||||
elseif ($tag === 'see' OR $tag === 'uses')
|
||||
{
|
||||
if (preg_match('/^'.Kodoc::$regex_class_member.'/', $text, $matches))
|
||||
return Kodoc::link_class_member($matches);
|
||||
}
|
||||
|
||||
return $text;
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse a comment to extract the description and the tags
|
||||
*
|
||||
* [!!] Converting the output to HTML in this method is deprecated in 3.3
|
||||
*
|
||||
* @param string $comment The DocBlock to parse
|
||||
* @param boolean $html Whether or not to convert the return values
|
||||
* to HTML (deprecated)
|
||||
* @return array array(string $description, array $tags)
|
||||
*/
|
||||
public static function parse($comment, $html = TRUE)
|
||||
{
|
||||
// Normalize all new lines to \n
|
||||
$comment = str_replace(array("\r\n", "\n"), "\n", $comment);
|
||||
|
||||
// Split into lines while capturing without leading whitespace
|
||||
preg_match_all('/^\s*\* ?(.*)\n/m', $comment, $lines);
|
||||
|
||||
// Tag content
|
||||
$tags = array();
|
||||
|
||||
/**
|
||||
* Process a tag and add it to $tags
|
||||
*
|
||||
* @param string $tag Name of the tag without @
|
||||
* @param string $text Content of the tag
|
||||
* @return void
|
||||
*/
|
||||
$add_tag = function($tag, $text) use ($html, &$tags)
|
||||
{
|
||||
// Don't show @access lines, they are shown elsewhere
|
||||
if ($tag !== 'access')
|
||||
{
|
||||
if ($html)
|
||||
{
|
||||
$text = Kodoc::format_tag($tag, $text);
|
||||
}
|
||||
|
||||
// Add the tag
|
||||
$tags[$tag][] = $text;
|
||||
}
|
||||
};
|
||||
|
||||
$comment = $tag = null;
|
||||
$end = count($lines[1]) - 1;
|
||||
|
||||
foreach ($lines[1] as $i => $line)
|
||||
{
|
||||
// Search this line for a tag
|
||||
if (preg_match('/^@(\S+)\s*(.+)?$/', $line, $matches))
|
||||
{
|
||||
if ($tag)
|
||||
{
|
||||
// Previous tag is finished
|
||||
$add_tag($tag, $text);
|
||||
}
|
||||
|
||||
$tag = $matches[1];
|
||||
$text = isset($matches[2]) ? $matches[2] : '';
|
||||
|
||||
if ($i === $end)
|
||||
{
|
||||
// No more lines
|
||||
$add_tag($tag, $text);
|
||||
}
|
||||
}
|
||||
elseif ($tag)
|
||||
{
|
||||
// This is the continuation of the previous tag
|
||||
$text .= "\n".$line;
|
||||
|
||||
if ($i === $end)
|
||||
{
|
||||
// No more lines
|
||||
$add_tag($tag, $text);
|
||||
}
|
||||
}
|
||||
else
|
||||
{
|
||||
$comment .= "\n".$line;
|
||||
}
|
||||
}
|
||||
|
||||
$comment = trim($comment, "\n");
|
||||
|
||||
if ($comment AND $html)
|
||||
{
|
||||
// Parse the comment with Markdown
|
||||
$comment = Kodoc_Markdown::markdown($comment);
|
||||
}
|
||||
|
||||
return array($comment, $tags);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the source of a function
|
||||
*
|
||||
* @param string the filename
|
||||
* @param int start line?
|
||||
* @param int end line?
|
||||
*/
|
||||
public static function source($file, $start, $end)
|
||||
{
|
||||
if ( ! $file) return FALSE;
|
||||
|
||||
$file = file($file, FILE_IGNORE_NEW_LINES);
|
||||
|
||||
$file = array_slice($file, $start - 1, $end - $start + 1);
|
||||
|
||||
if (preg_match('/^(\s+)/', $file[0], $matches))
|
||||
{
|
||||
$padding = strlen($matches[1]);
|
||||
|
||||
foreach ($file as & $line)
|
||||
{
|
||||
$line = substr($line, $padding);
|
||||
}
|
||||
}
|
||||
|
||||
return implode("\n", $file);
|
||||
}
|
||||
|
||||
/**
|
||||
* Test whether a class should be shown, based on the api_packages config option
|
||||
*
|
||||
* @param Kodoc_Class the class to test
|
||||
* @return bool whether this class should be shown
|
||||
*/
|
||||
public static function show_class(Kodoc_Class $class)
|
||||
{
|
||||
$api_packages = Kohana::$config->load('userguide.api_packages');
|
||||
|
||||
// If api_packages is true, all packages should be shown
|
||||
if ($api_packages === TRUE)
|
||||
return TRUE;
|
||||
|
||||
// Get the package tags for this class (as an array)
|
||||
$packages = Arr::get($class->tags, 'package', array('None'));
|
||||
|
||||
$show_this = FALSE;
|
||||
|
||||
// Loop through each package tag
|
||||
foreach ($packages as $package)
|
||||
{
|
||||
// If this package is in the allowed packages, set show this to true
|
||||
if (in_array($package, explode(',', $api_packages)))
|
||||
$show_this = TRUE;
|
||||
}
|
||||
|
||||
return $show_this;
|
||||
}
|
||||
|
||||
/**
|
||||
* Checks whether a class is a transparent extension class or not.
|
||||
*
|
||||
* This method takes an optional $classes parameter, a list of all defined
|
||||
* class names. If provided, the method will return false unless the extension
|
||||
* class exists. If not, the method will only check known transparent class
|
||||
* prefixes.
|
||||
*
|
||||
* Transparent prefixes are defined in the userguide.php config file:
|
||||
*
|
||||
* 'transparent_prefixes' => array(
|
||||
* 'Kohana' => TRUE,
|
||||
* );
|
||||
*
|
||||
* Module developers can therefore add their own transparent extension
|
||||
* namespaces and exclude them from the userguide.
|
||||
*
|
||||
* @param string $class The name of the class to check for transparency
|
||||
* @param array $classes An optional list of all defined classes
|
||||
* @return false If this is not a transparent extension class
|
||||
* @return string The name of the class that extends this (in the case provided)
|
||||
* @throws InvalidArgumentException If the $classes array is provided and the $class variable is not lowercase
|
||||
*/
|
||||
public static function is_transparent($class, $classes = NULL)
|
||||
{
|
||||
|
||||
static $transparent_prefixes = NULL;
|
||||
|
||||
if ( ! $transparent_prefixes)
|
||||
{
|
||||
$transparent_prefixes = Kohana::$config->load('userguide.transparent_prefixes');
|
||||
}
|
||||
|
||||
// Split the class name at the first underscore
|
||||
$segments = explode('_',$class,2);
|
||||
|
||||
if ((count($segments) == 2) AND (isset($transparent_prefixes[$segments[0]])))
|
||||
{
|
||||
if ($segments[1] === 'Core')
|
||||
{
|
||||
// Cater for Module extends Module_Core naming
|
||||
$child_class = $segments[0];
|
||||
}
|
||||
else
|
||||
{
|
||||
// Cater for Foo extends Module_Foo naming
|
||||
$child_class = $segments[1];
|
||||
}
|
||||
|
||||
// It is only a transparent class if the unprefixed class also exists
|
||||
if ($classes AND ! isset($classes[$child_class]))
|
||||
return FALSE;
|
||||
|
||||
// Return the name of the child class
|
||||
return $child_class;
|
||||
}
|
||||
else
|
||||
{
|
||||
// Not a transparent class
|
||||
return FALSE;
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
} // End Kodoc
|
||||
279
modules/userguide/classes/Kohana/Kodoc/Class.php
Normal file
279
modules/userguide/classes/Kohana/Kodoc/Class.php
Normal file
@@ -0,0 +1,279 @@
|
||||
<?php defined('SYSPATH') or die('No direct script access.');
|
||||
/**
|
||||
* Class documentation generator.
|
||||
*
|
||||
* @package Kohana/Userguide
|
||||
* @category Base
|
||||
* @author Kohana Team
|
||||
* @copyright (c) 2009-2012 Kohana Team
|
||||
* @license http://kohanaphp.com/license
|
||||
*/
|
||||
class Kohana_Kodoc_Class extends Kodoc {
|
||||
|
||||
/**
|
||||
* @var ReflectionClass The ReflectionClass for this class
|
||||
*/
|
||||
public $class;
|
||||
|
||||
/**
|
||||
* @var string modifiers like abstract, final
|
||||
*/
|
||||
public $modifiers;
|
||||
|
||||
/**
|
||||
* @var string description of the class from the comment
|
||||
*/
|
||||
public $description;
|
||||
|
||||
/**
|
||||
* @var array array of tags, retrieved from the comment
|
||||
*/
|
||||
public $tags = array();
|
||||
|
||||
/**
|
||||
* @var array array of this classes constants
|
||||
*/
|
||||
public $constants = array();
|
||||
|
||||
/**
|
||||
* @var array Parent classes/interfaces of this class/interface
|
||||
*/
|
||||
public $parents = array();
|
||||
|
||||
/**
|
||||
* Loads a class and uses [reflection](http://php.net/reflection) to parse
|
||||
* the class. Reads the class modifiers, constants and comment. Parses the
|
||||
* comment to find the description and tags.
|
||||
*
|
||||
* @param string class name
|
||||
* @return void
|
||||
*/
|
||||
public function __construct($class)
|
||||
{
|
||||
$this->class = new ReflectionClass($class);
|
||||
|
||||
if ($modifiers = $this->class->getModifiers())
|
||||
{
|
||||
$this->modifiers = '<small>'.implode(' ', Reflection::getModifierNames($modifiers)).'</small> ';
|
||||
}
|
||||
|
||||
$this->constants = $this->class->getConstants();
|
||||
|
||||
// If ReflectionClass::getParentClass() won't work if the class in
|
||||
// question is an interface
|
||||
if ($this->class->isInterface())
|
||||
{
|
||||
$this->parents = $this->class->getInterfaces();
|
||||
}
|
||||
else
|
||||
{
|
||||
$parent = $this->class;
|
||||
|
||||
while ($parent = $parent->getParentClass())
|
||||
{
|
||||
$this->parents[] = $parent;
|
||||
}
|
||||
}
|
||||
|
||||
if ( ! $comment = $this->class->getDocComment())
|
||||
{
|
||||
foreach ($this->parents as $parent)
|
||||
{
|
||||
if ($comment = $parent->getDocComment())
|
||||
{
|
||||
// Found a description for this class
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
list($this->description, $this->tags) = Kodoc::parse($comment, FALSE);
|
||||
}
|
||||
|
||||
/**
|
||||
* Gets the constants of this class as HTML.
|
||||
*
|
||||
* @return array
|
||||
*/
|
||||
public function constants()
|
||||
{
|
||||
$result = array();
|
||||
|
||||
foreach ($this->constants as $name => $value)
|
||||
{
|
||||
$result[$name] = Debug::vars($value);
|
||||
}
|
||||
|
||||
return $result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the description of this class as HTML. Includes a warning when the
|
||||
* class or one of its parents could not be found.
|
||||
*
|
||||
* @return string HTML
|
||||
*/
|
||||
public function description()
|
||||
{
|
||||
$result = $this->description;
|
||||
|
||||
// If this class extends Kodoc_Missing, add a warning about possible
|
||||
// incomplete documentation
|
||||
foreach ($this->parents as $parent)
|
||||
{
|
||||
if ($parent->name == 'Kodoc_Missing')
|
||||
{
|
||||
$result .= "[!!] **This class, or a class parent, could not be
|
||||
found or loaded. This could be caused by a missing
|
||||
module or other dependancy. The documentation for
|
||||
class may not be complete!**";
|
||||
}
|
||||
}
|
||||
|
||||
return Kodoc_Markdown::markdown($result);
|
||||
}
|
||||
|
||||
/**
|
||||
* Gets a list of the class properties as [Kodoc_Property] objects.
|
||||
*
|
||||
* @return array
|
||||
*/
|
||||
public function properties()
|
||||
{
|
||||
$props = $this->class->getProperties();
|
||||
|
||||
$defaults = $this->class->getDefaultProperties();
|
||||
|
||||
usort($props, array($this,'_prop_sort'));
|
||||
|
||||
foreach ($props as $key => $property)
|
||||
{
|
||||
// Create Kodoc Properties for each property
|
||||
$props[$key] = new Kodoc_Property($this->class->name, $property->name, Arr::get($defaults, $property->name));
|
||||
}
|
||||
|
||||
return $props;
|
||||
}
|
||||
|
||||
protected function _prop_sort($a, $b)
|
||||
{
|
||||
// If one property is public, and the other is not, it goes on top
|
||||
if ($a->isPublic() AND ( ! $b->isPublic()))
|
||||
return -1;
|
||||
if ($b->isPublic() AND ( ! $a->isPublic()))
|
||||
return 1;
|
||||
|
||||
// If one property is protected and the other is private, it goes on top
|
||||
if ($a->isProtected() AND $b->isPrivate())
|
||||
return -1;
|
||||
if ($b->isProtected() AND $a->isPrivate())
|
||||
return 1;
|
||||
|
||||
// Otherwise just do alphabetical
|
||||
return strcmp($a->name, $b->name);
|
||||
}
|
||||
|
||||
/**
|
||||
* Gets a list of the class properties as [Kodoc_Method] objects.
|
||||
*
|
||||
* @return array
|
||||
*/
|
||||
public function methods()
|
||||
{
|
||||
$methods = $this->class->getMethods();
|
||||
|
||||
usort($methods, array($this,'_method_sort'));
|
||||
|
||||
foreach ($methods as $key => $method)
|
||||
{
|
||||
$methods[$key] = new Kodoc_Method($this->class->name, $method->name);
|
||||
}
|
||||
|
||||
return $methods;
|
||||
}
|
||||
|
||||
/**
|
||||
* Sort methods based on their visibility and declaring class based on:
|
||||
* - methods will be sorted public, protected, then private.
|
||||
* - methods that are declared by an ancestor will be after classes
|
||||
* declared by the current class
|
||||
* - lastly, they will be sorted alphabetically
|
||||
*
|
||||
*/
|
||||
protected function _method_sort($a, $b)
|
||||
{
|
||||
// If one method is public, and the other is not, it goes on top
|
||||
if ($a->isPublic() AND ( ! $b->isPublic()))
|
||||
return -1;
|
||||
if ($b->isPublic() AND ( ! $a->isPublic()))
|
||||
return 1;
|
||||
|
||||
// If one method is protected and the other is private, it goes on top
|
||||
if ($a->isProtected() AND $b->isPrivate())
|
||||
return -1;
|
||||
if ($b->isProtected() AND $a->isPrivate())
|
||||
return 1;
|
||||
|
||||
// The methods have the same visibility, so check the declaring class depth:
|
||||
|
||||
|
||||
/*
|
||||
echo Debug::vars('a is '.$a->class.'::'.$a->name,'b is '.$b->class.'::'.$b->name,
|
||||
'are the classes the same?', $a->class == $b->class,'if they are, the result is:',strcmp($a->name, $b->name),
|
||||
'is a this class?', $a->name == $this->class->name,-1,
|
||||
'is b this class?', $b->name == $this->class->name,1,
|
||||
'otherwise, the result is:',strcmp($a->class, $b->class)
|
||||
);
|
||||
*/
|
||||
|
||||
// If both methods are defined in the same class, just compare the method names
|
||||
if ($a->class == $b->class)
|
||||
return strcmp($a->name, $b->name);
|
||||
|
||||
// If one of them was declared by this class, it needs to be on top
|
||||
if ($a->name == $this->class->name)
|
||||
return -1;
|
||||
if ($b->name == $this->class->name)
|
||||
return 1;
|
||||
|
||||
// Otherwise, get the parents of each methods declaring class, then compare which function has more "ancestors"
|
||||
$adepth = 0;
|
||||
$bdepth = 0;
|
||||
|
||||
$parent = $a->getDeclaringClass();
|
||||
do
|
||||
{
|
||||
$adepth++;
|
||||
}
|
||||
while ($parent = $parent->getParentClass());
|
||||
|
||||
$parent = $b->getDeclaringClass();
|
||||
do
|
||||
{
|
||||
$bdepth++;
|
||||
}
|
||||
while ($parent = $parent->getParentClass());
|
||||
|
||||
return $bdepth - $adepth;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the tags of this class as HTML.
|
||||
*
|
||||
* @return array
|
||||
*/
|
||||
public function tags()
|
||||
{
|
||||
$result = array();
|
||||
|
||||
foreach ($this->tags as $name => $set)
|
||||
{
|
||||
foreach ($set as $text)
|
||||
{
|
||||
$result[$name][] = Kodoc::format_tag($name, $text);
|
||||
}
|
||||
}
|
||||
|
||||
return $result;
|
||||
}
|
||||
}
|
||||
289
modules/userguide/classes/Kohana/Kodoc/Markdown.php
Normal file
289
modules/userguide/classes/Kohana/Kodoc/Markdown.php
Normal file
@@ -0,0 +1,289 @@
|
||||
<?php defined('SYSPATH') or die('No direct script access.');
|
||||
/**
|
||||
* Custom Markdown parser for Kohana documentation.
|
||||
*
|
||||
* @package Kohana/Userguide
|
||||
* @category Base
|
||||
* @author Kohana Team
|
||||
* @copyright (c) 2009-2012 Kohana Team
|
||||
* @license http://kohanaphp.com/license
|
||||
*/
|
||||
class Kohana_Kodoc_Markdown extends MarkdownExtra_Parser {
|
||||
|
||||
/**
|
||||
* @var string base url for links
|
||||
*/
|
||||
public static $base_url = '';
|
||||
|
||||
/**
|
||||
* @var string base url for images
|
||||
*/
|
||||
public static $image_url = '';
|
||||
|
||||
/**
|
||||
* Currently defined heading ids.
|
||||
* Used to prevent creating multiple headings with same id.
|
||||
* @var array
|
||||
*/
|
||||
protected $_heading_ids = array();
|
||||
|
||||
/**
|
||||
* @var string the generated table of contents
|
||||
*/
|
||||
protected static $_toc = "";
|
||||
|
||||
/**
|
||||
* Slightly less terrible way to make it so the TOC only shows up when we
|
||||
* want it to. set this to true to show the toc.
|
||||
*/
|
||||
public static $show_toc = false;
|
||||
|
||||
/**
|
||||
* Transform some text using [Kodoc_Markdown]
|
||||
*
|
||||
* @see Markdown()
|
||||
*
|
||||
* @param string Text to parse
|
||||
* @return string Transformed text
|
||||
*/
|
||||
public static function markdown($text)
|
||||
{
|
||||
static $instance;
|
||||
|
||||
if ($instance === NULL)
|
||||
{
|
||||
$instance = new Kodoc_Markdown;
|
||||
}
|
||||
|
||||
return $instance->transform($text);
|
||||
}
|
||||
|
||||
public function __construct()
|
||||
{
|
||||
// doImage is 10, add image url just before
|
||||
$this->span_gamut['doImageURL'] = 9;
|
||||
|
||||
// doLink is 20, add base url just before
|
||||
$this->span_gamut['doBaseURL'] = 19;
|
||||
|
||||
// Add API links
|
||||
$this->span_gamut['doAPI'] = 90;
|
||||
|
||||
// Add note spans last
|
||||
$this->span_gamut['doNotes'] = 100;
|
||||
|
||||
// Parse Kohana view inclusions at the very end
|
||||
$this->document_gamut['doIncludeViews'] = 99;
|
||||
|
||||
// Show table of contents for userguide pages
|
||||
$this->document_gamut['doTOC'] = 100;
|
||||
|
||||
// PHP4 makes me sad.
|
||||
parent::MarkdownExtra_Parser();
|
||||
}
|
||||
|
||||
/**
|
||||
* Callback for the heading setext style
|
||||
*
|
||||
* Heading 1
|
||||
* =========
|
||||
*
|
||||
* @param array Matches from regex call
|
||||
* @return string Generated html
|
||||
*/
|
||||
function _doHeaders_callback_setext($matches)
|
||||
{
|
||||
if ($matches[3] == '-' && preg_match('{^- }', $matches[1]))
|
||||
return $matches[0];
|
||||
$level = $matches[3]{0} == '=' ? 1 : 2;
|
||||
$attr = $this->_doHeaders_attr($id =& $matches[2]);
|
||||
|
||||
// Only auto-generate id if one doesn't exist
|
||||
if(empty($attr))
|
||||
$attr = ' id="'.$this->make_heading_id($matches[1]).'"';
|
||||
|
||||
// Add this header to the page toc
|
||||
$this->_add_to_toc($level,$matches[1],$this->make_heading_id($matches[1]));
|
||||
|
||||
$block = "<h$level$attr>".$this->runSpanGamut($matches[1])."</h$level>";
|
||||
return "\n" . $this->hashBlock($block) . "\n\n";
|
||||
}
|
||||
|
||||
/**
|
||||
* Callback for the heading atx style
|
||||
*
|
||||
* # Heading 1
|
||||
*
|
||||
* @param array Matches from regex call
|
||||
* @return string Generated html
|
||||
*/
|
||||
function _doHeaders_callback_atx($matches)
|
||||
{
|
||||
$level = strlen($matches[1]);
|
||||
$attr = $this->_doHeaders_attr($id =& $matches[3]);
|
||||
|
||||
// Only auto-generate id if one doesn't exist
|
||||
if(empty($attr))
|
||||
$attr = ' id="'.$this->make_heading_id($matches[2]).'"';
|
||||
|
||||
// Add this header to the page toc
|
||||
$this->_add_to_toc($level, $matches[2], $this->make_heading_id(empty($matches[3]) ? $matches[2] : $matches[3]));
|
||||
|
||||
$block = "<h$level$attr>".$this->runSpanGamut($matches[2])."</h$level>";
|
||||
return "\n" . $this->hashBlock($block) . "\n\n";
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* Makes a heading id from the heading text
|
||||
* If any heading share the same name then subsequent headings will have an integer appended
|
||||
*
|
||||
* @param string The heading text
|
||||
* @return string ID for the heading
|
||||
*/
|
||||
function make_heading_id($heading)
|
||||
{
|
||||
$id = url::title($heading, '-', TRUE);
|
||||
|
||||
if(isset($this->_heading_ids[$id]))
|
||||
{
|
||||
$id .= '-';
|
||||
|
||||
$count = 0;
|
||||
|
||||
while (isset($this->_heading_ids[$id]) AND ++$count)
|
||||
{
|
||||
$id .= $count;
|
||||
}
|
||||
}
|
||||
|
||||
return $id;
|
||||
}
|
||||
|
||||
public function doIncludeViews($text)
|
||||
{
|
||||
if (preg_match_all('/{{([^\s{}]++)}}/', $text, $matches, PREG_SET_ORDER))
|
||||
{
|
||||
$replace = array();
|
||||
|
||||
$replace = array();
|
||||
|
||||
foreach ($matches as $set)
|
||||
{
|
||||
list($search, $view) = $set;
|
||||
|
||||
if (Kohana::find_file('views', $view))
|
||||
{
|
||||
try
|
||||
{
|
||||
$replace[$search] = View::factory($view)->render();
|
||||
}
|
||||
catch (Exception $e)
|
||||
{
|
||||
/**
|
||||
* Capture the exception handler output and insert it instead.
|
||||
*
|
||||
* NOTE: Is this really the correct way to handle an exception?
|
||||
*/
|
||||
$response = Kohana_exception::_handler($e);
|
||||
|
||||
$replace[$search] = $response->body();
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
$text = strtr($text, $replace);
|
||||
}
|
||||
|
||||
return $text;
|
||||
}
|
||||
|
||||
/**
|
||||
* Add the current base url to all local links.
|
||||
*
|
||||
* [filesystem](about.filesystem "Optional title")
|
||||
*
|
||||
* @param string span text
|
||||
* @return string
|
||||
*/
|
||||
public function doBaseURL($text)
|
||||
{
|
||||
// URLs containing "://" are left untouched
|
||||
return preg_replace('~(?<!!)(\[.+?\]\()(?!\w++://)(?!#)(\S*(?:\s*+".+?")?\))~', '$1'.Kodoc_Markdown::$base_url.'$2', $text);
|
||||
}
|
||||
|
||||
/**
|
||||
* Add the current base url to all local images.
|
||||
*
|
||||
* 
|
||||
*
|
||||
* @param string span text
|
||||
* @return string
|
||||
*/
|
||||
public function doImageURL($text)
|
||||
{
|
||||
// URLs containing "://" are left untouched
|
||||
return preg_replace('~(!\[.+?\]\()(?!\w++://)(\S*(?:\s*+".+?")?\))~', '$1'.Kodoc_Markdown::$image_url.'$2', $text);
|
||||
}
|
||||
|
||||
/**
|
||||
* Parses links to the API browser.
|
||||
*
|
||||
* [Class_Name], [Class::method] or [Class::$property]
|
||||
*
|
||||
* @param string span text
|
||||
* @return string
|
||||
*/
|
||||
public function doAPI($text)
|
||||
{
|
||||
return preg_replace_callback('/\['.Kodoc::$regex_class_member.'\]/i', 'Kodoc::link_class_member', $text);
|
||||
}
|
||||
|
||||
/**
|
||||
* Wrap notes in the applicable markup. Notes can contain single newlines.
|
||||
*
|
||||
* [!!] Remember the milk!
|
||||
*
|
||||
* @param string span text
|
||||
* @return string
|
||||
*/
|
||||
public function doNotes($text)
|
||||
{
|
||||
if ( ! preg_match('/^\[!!\]\s*+(.+?)(?=\n{2,}|$)/s', $text, $match))
|
||||
{
|
||||
return $text;
|
||||
}
|
||||
|
||||
return $this->hashBlock('<p class="note">'.$match[1].'</p>');
|
||||
}
|
||||
|
||||
protected function _add_to_toc($level, $name, $id)
|
||||
{
|
||||
self::$_toc[] = array(
|
||||
'level' => $level,
|
||||
'name' => $name,
|
||||
'id' => $id);
|
||||
}
|
||||
|
||||
public function doTOC($text)
|
||||
{
|
||||
// Only add the toc do userguide pages, not api since they already have one
|
||||
if (self::$show_toc AND Route::name(Request::current()->route()) == "docs/guide")
|
||||
{
|
||||
$toc = View::factory('userguide/page-toc')
|
||||
->set('array', self::$_toc)
|
||||
->render()
|
||||
;
|
||||
|
||||
if (($offset = strpos($text, '<p>')) !== FALSE)
|
||||
{
|
||||
// Insert the page TOC just before the first <p>, which every
|
||||
// Markdown page should (will?) have.
|
||||
$text = substr_replace($text, $toc, $offset, 0);
|
||||
}
|
||||
}
|
||||
|
||||
return $text;
|
||||
}
|
||||
|
||||
} // End Kodoc_Markdown
|
||||
141
modules/userguide/classes/Kohana/Kodoc/Method.php
Normal file
141
modules/userguide/classes/Kohana/Kodoc/Method.php
Normal file
@@ -0,0 +1,141 @@
|
||||
<?php defined('SYSPATH') or die('No direct script access.');
|
||||
/**
|
||||
* Class method documentation generator.
|
||||
*
|
||||
* @package Kohana/Userguide
|
||||
* @category Base
|
||||
* @author Kohana Team
|
||||
* @copyright (c) 2009 Kohana Team
|
||||
* @license http://kohanaphp.com/license
|
||||
*/
|
||||
class Kohana_Kodoc_Method extends Kodoc {
|
||||
|
||||
/**
|
||||
* @var ReflectionMethod The ReflectionMethod for this class
|
||||
*/
|
||||
public $method;
|
||||
|
||||
/**
|
||||
* @var array array of Kodoc_Method_Param
|
||||
*/
|
||||
public $params;
|
||||
|
||||
/**
|
||||
* @var array the things this function can return
|
||||
*/
|
||||
public $return = array();
|
||||
|
||||
/**
|
||||
* @var string the source code for this function
|
||||
*/
|
||||
public $source;
|
||||
|
||||
public function __construct($class, $method)
|
||||
{
|
||||
$this->method = new ReflectionMethod($class, $method);
|
||||
|
||||
$this->class = $parent = $this->method->getDeclaringClass();
|
||||
|
||||
if ($modifiers = $this->method->getModifiers())
|
||||
{
|
||||
$this->modifiers = '<small>'.implode(' ', Reflection::getModifierNames($modifiers)).'</small> ';
|
||||
}
|
||||
|
||||
do
|
||||
{
|
||||
if ($parent->hasMethod($method) AND $comment = $parent->getMethod($method)->getDocComment())
|
||||
{
|
||||
// Found a description for this method
|
||||
break;
|
||||
}
|
||||
}
|
||||
while ($parent = $parent->getParentClass());
|
||||
|
||||
list($this->description, $tags) = Kodoc::parse($comment);
|
||||
|
||||
if ($file = $this->class->getFileName())
|
||||
{
|
||||
$this->source = Kodoc::source($file, $this->method->getStartLine(), $this->method->getEndLine());
|
||||
}
|
||||
|
||||
if (isset($tags['param']))
|
||||
{
|
||||
$params = array();
|
||||
|
||||
foreach ($this->method->getParameters() as $i => $param)
|
||||
{
|
||||
$param = new Kodoc_Method_Param(array($this->method->class, $this->method->name),$i);
|
||||
|
||||
if (isset($tags['param'][$i]))
|
||||
{
|
||||
preg_match('/^(\S+)(?:\s*(?:\$'.$param->name.'\s*)?(.+))?$/s', $tags['param'][$i], $matches);
|
||||
|
||||
$param->type = $matches[1];
|
||||
|
||||
if (isset($matches[2]))
|
||||
{
|
||||
$param->description = ucfirst($matches[2]);
|
||||
}
|
||||
}
|
||||
$params[] = $param;
|
||||
}
|
||||
|
||||
$this->params = $params;
|
||||
|
||||
unset($tags['param']);
|
||||
}
|
||||
|
||||
if (isset($tags['return']))
|
||||
{
|
||||
foreach ($tags['return'] as $return)
|
||||
{
|
||||
if (preg_match('/^(\S*)(?:\s*(.+?))?$/', $return, $matches))
|
||||
{
|
||||
$this->return[] = array($matches[1], isset($matches[2]) ? $matches[2] : '');
|
||||
}
|
||||
}
|
||||
|
||||
unset($tags['return']);
|
||||
}
|
||||
|
||||
$this->tags = $tags;
|
||||
}
|
||||
|
||||
public function params_short()
|
||||
{
|
||||
$out = '';
|
||||
$required = TRUE;
|
||||
$first = TRUE;
|
||||
foreach ($this->params as $param)
|
||||
{
|
||||
if ($required AND $param->default AND $first)
|
||||
{
|
||||
$out .= '[ '.$param;
|
||||
$required = FALSE;
|
||||
$first = FALSE;
|
||||
}
|
||||
elseif ($required AND $param->default)
|
||||
{
|
||||
$out .= '[, '.$param;
|
||||
$required = FALSE;
|
||||
}
|
||||
elseif ($first)
|
||||
{
|
||||
$out .= $param;
|
||||
$first = FALSE;
|
||||
}
|
||||
else
|
||||
{
|
||||
$out .= ', '.$param;
|
||||
}
|
||||
}
|
||||
|
||||
if ( ! $required)
|
||||
{
|
||||
$out .= '] ';
|
||||
}
|
||||
|
||||
return $out;
|
||||
}
|
||||
|
||||
} // End Kodoc_Method
|
||||
101
modules/userguide/classes/Kohana/Kodoc/Method/Param.php
Normal file
101
modules/userguide/classes/Kohana/Kodoc/Method/Param.php
Normal file
@@ -0,0 +1,101 @@
|
||||
<?php defined('SYSPATH') or die('No direct script access.');
|
||||
/**
|
||||
* Class method parameter documentation generator.
|
||||
*
|
||||
* @package Kohana/Userguide
|
||||
* @category Base
|
||||
* @author Kohana Team
|
||||
* @copyright (c) 2009 Kohana Team
|
||||
* @license http://kohanaphp.com/license
|
||||
*/
|
||||
class Kohana_Kodoc_Method_Param extends Kodoc {
|
||||
|
||||
/**
|
||||
* @var object ReflectionParameter for this property
|
||||
*/
|
||||
public $param;
|
||||
|
||||
/**
|
||||
* @var string name of this var
|
||||
*/
|
||||
public $name;
|
||||
|
||||
/**
|
||||
* @var string variable type, retrieved from the comment
|
||||
*/
|
||||
public $type;
|
||||
|
||||
/**
|
||||
* @var string default value of this param
|
||||
*/
|
||||
public $default;
|
||||
|
||||
/**
|
||||
* @var string description of this parameter
|
||||
*/
|
||||
public $description;
|
||||
|
||||
/**
|
||||
* @var boolean is the parameter passed by reference?
|
||||
*/
|
||||
public $reference = FALSE;
|
||||
|
||||
/**
|
||||
* @var boolean is the parameter optional?
|
||||
*/
|
||||
public $optional = FALSE;
|
||||
|
||||
public function __construct($method, $param)
|
||||
{
|
||||
$this->param = new ReflectionParameter($method, $param);
|
||||
|
||||
$this->name = $this->param->name;
|
||||
|
||||
if ($this->param->isDefaultValueAvailable())
|
||||
{
|
||||
$this->default = Debug::dump($this->param->getDefaultValue());
|
||||
}
|
||||
|
||||
if ($this->param->isPassedByReference())
|
||||
{
|
||||
$this->reference = TRUE;
|
||||
}
|
||||
|
||||
if ($this->param->isOptional())
|
||||
{
|
||||
$this->optional = TRUE;
|
||||
}
|
||||
}
|
||||
|
||||
public function __toString()
|
||||
{
|
||||
$display = '';
|
||||
|
||||
if ($this->type)
|
||||
{
|
||||
$display .= '<small>'.$this->type.'</small> ';
|
||||
}
|
||||
|
||||
if ($this->reference)
|
||||
{
|
||||
$display .= '<small><abbr title="passed by reference">&</abbr></small> ';
|
||||
}
|
||||
|
||||
if ($this->description)
|
||||
{
|
||||
$display .= '<span class="param" title="'.preg_replace('/\s+/', ' ', $this->description).'">$'.$this->name.'</span> ';
|
||||
}
|
||||
else
|
||||
{
|
||||
$display .= '$'.$this->name.' ';
|
||||
}
|
||||
|
||||
if ($this->default)
|
||||
{
|
||||
$display .= '<small>= '.$this->default.'</small> ';
|
||||
}
|
||||
|
||||
return $display;
|
||||
}
|
||||
|
||||
} // End Kodoc_Method_Param
|
||||
36
modules/userguide/classes/Kohana/Kodoc/Missing.php
Normal file
36
modules/userguide/classes/Kohana/Kodoc/Missing.php
Normal file
@@ -0,0 +1,36 @@
|
||||
<?php defined('SYSPATH') or die('No direct script access.');
|
||||
/**
|
||||
* Set Kodoc_Missing::create_class as an autoloading to prevent missing classes
|
||||
* from crashing the api browser. Classes that are missing a parent will
|
||||
* extend this class, and get a warning in the API browser.
|
||||
*
|
||||
* @package Kohana/Userguide
|
||||
* @category Undocumented
|
||||
* @author Kohana Team
|
||||
* @since 3.0.7
|
||||
*/
|
||||
abstract class Kohana_Kodoc_Missing {
|
||||
|
||||
/**
|
||||
* Creates classes when they are otherwise not found.
|
||||
*
|
||||
* Kodoc::create_class('ThisClassDoesNotExist');
|
||||
*
|
||||
* [!!] All classes created will extend [Kodoc_Missing].
|
||||
*
|
||||
* @param string class name
|
||||
* @return boolean
|
||||
* @since 3.0.7
|
||||
*/
|
||||
public static function create_class($class)
|
||||
{
|
||||
if ( ! class_exists($class))
|
||||
{
|
||||
// Create a new missing class
|
||||
eval("class {$class} extends Kodoc_Missing {}");
|
||||
}
|
||||
|
||||
return TRUE;
|
||||
}
|
||||
|
||||
} // End Kohana_Kodoc_Missing
|
||||
90
modules/userguide/classes/Kohana/Kodoc/Property.php
Normal file
90
modules/userguide/classes/Kohana/Kodoc/Property.php
Normal file
@@ -0,0 +1,90 @@
|
||||
<?php defined('SYSPATH') or die('No direct script access.');
|
||||
/**
|
||||
* Class property documentation generator.
|
||||
*
|
||||
* @package Kohana/Userguide
|
||||
* @category Base
|
||||
* @author Kohana Team
|
||||
* @copyright (c) 2009-2012 Kohana Team
|
||||
* @license http://kohanaphp.com/license
|
||||
*/
|
||||
class Kohana_Kodoc_Property extends Kodoc {
|
||||
|
||||
/**
|
||||
* @var object ReflectionProperty
|
||||
*/
|
||||
public $property;
|
||||
|
||||
/**
|
||||
* @var string modifiers: public, private, static, etc
|
||||
*/
|
||||
public $modifiers = 'public';
|
||||
|
||||
/**
|
||||
* @var string variable type, retrieved from the comment
|
||||
*/
|
||||
public $type;
|
||||
|
||||
/**
|
||||
* @var string value of the property
|
||||
*/
|
||||
public $value;
|
||||
|
||||
/**
|
||||
* @var string default value of the property
|
||||
*/
|
||||
public $default;
|
||||
|
||||
public function __construct($class, $property, $default = NULL)
|
||||
{
|
||||
$property = new ReflectionProperty($class, $property);
|
||||
|
||||
list($description, $tags) = Kodoc::parse($property->getDocComment());
|
||||
|
||||
$this->description = $description;
|
||||
|
||||
if ($modifiers = $property->getModifiers())
|
||||
{
|
||||
$this->modifiers = '<small>'.implode(' ', Reflection::getModifierNames($modifiers)).'</small> ';
|
||||
}
|
||||
|
||||
if (isset($tags['var']))
|
||||
{
|
||||
if (preg_match('/^(\S*)(?:\s*(.+?))?$/s', $tags['var'][0], $matches))
|
||||
{
|
||||
$this->type = $matches[1];
|
||||
|
||||
if (isset($matches[2]))
|
||||
{
|
||||
$this->description = Kodoc_Markdown::markdown($matches[2]);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
$this->property = $property;
|
||||
|
||||
// Show the value of static properties, but only if they are public or we are php 5.3 or higher and can force them to be accessible
|
||||
if ($property->isStatic() AND ($property->isPublic() OR version_compare(PHP_VERSION, '5.3', '>=')))
|
||||
{
|
||||
// Force the property to be accessible
|
||||
if (version_compare(PHP_VERSION, '5.3', '>='))
|
||||
{
|
||||
$property->setAccessible(TRUE);
|
||||
}
|
||||
|
||||
// Don't debug the entire object, just say what kind of object it is
|
||||
if (is_object($property->getValue($class)))
|
||||
{
|
||||
$this->value = '<pre>object '.get_class($property->getValue($class)).'()</pre>';
|
||||
}
|
||||
else
|
||||
{
|
||||
$this->value = Debug::vars($property->getValue($class));
|
||||
}
|
||||
}
|
||||
|
||||
// Store the defult property
|
||||
$this->default = Debug::vars($default);;
|
||||
}
|
||||
|
||||
} // End Kodoc_Property
|
||||
Reference in New Issue
Block a user