Codex Generator that turns functions into Codex pages

codex-generator.php

<?php
/*
Plugin Name: Codex Generator
Description: Creates ready-made wiki page content for Codex. With magic. Okay - with PHPDoc and Reflect.
Author: Rarst
Author URL: http://www.rarst.net/
Version: 0.1
License Notes: GPLv3+, includes modified Parser class from Doqumentor (GPLv3+)
*/

/*
 * @example
$function = new Codex_Generator('name');
$wiki = $function->get_wiki(); 
 */


class Codex_Generator 
{
	var $name;
	var $type;

	var $reflect;
	var $parser;

	var $return;
	var $since;

	function __construct( $name, $type = 'function' ) 
	{
		$this->name = $name;
		$this->type = $type;

		switch( $this->type ) 
		{
			case 'function' :
				$this->reflect = new ReflectionFunction( $this->name );
				break;

		}

		$this->parser = new Parser($this->get_doc());
		$this->parser->parse();
	}

	function get_wiki() 
	{
		$output = '';

		$short_desc = $this->parser->getShortDesc();
		$desc = $this->parser->getDesc();

		if( ! empty( $short_desc ) || ! empty( $desc ) )
			$output .= "== Description ==\n\n";

		if( ! empty( $short_desc ) )
			$output .= $short_desc . "\n\n";

		if( ! empty( $desc ) )
			$output .= $desc . "\n\n";

		$params = $this->get_params();

		if( ! empty( $params ) )
			$output .= "== Parameters ==\n\n";

		foreach( $params as $name => $param ) 
		{
			$type = isset( $param['type'] ) ? $param['type'] : 'unknown_type';
			$description = isset( $param['description'] ) ? $param['description'] : 'no description';
			$optional = isset( $param['optional'] ) ? $param['optional'] : '';

			if( $param['hasDefault'] )
				$optional .= '|'.$this->to_string($param['default']);

			$output .= "{{Parameter|\${$name}|{$type}|{$description}|{$optional}}}\n\n";
		}

		if( ! empty( $this->return ) ) 
		{
			$type = $this->return['type'];
			$description = $this->return['description'];
			$output .= "== Return Values ==\n\n{{Return||{$type}|{$description}}}\n\n";
		}

		if( ! empty( $this->since ) ) 
		{
			$output .= "== Change Log ==\n\nSince: [[Version {$this->since}|{$this->since}]]\n\n";
		}

		$file = $this->get_file();
		$output .= "== Source File ==\n\n<tt>{$this->name}()</tt> is located in {{Trac|{$file}}}\n\n";

		$output .= "[[Category:Functions]]\n\n[[Category:New_page_created]]";


		return '<pre>'.$output.'</pre>';
	}

	function to_string( $value ) 
	{
		if( is_null( $value ) )
			$value = 'null';

		if( is_bool( $value ) )
			$value = $value ? 'true' : 'false';

		return $value;
	}

	function get_doc() 
	{
		return $this->reflect->getDocComment();
	}

	function get_file() 
	{
		$file = $this->reflect->getFileName();
		$file = str_replace( ABSPATH, '', $file );
		$file = str_replace( trim(ABSPATH, '\/').'\\', '', $file );
		$file = str_replace( '\\', '/', $file );

		return $file;
	}

	function get_params() 
	{
		$params = $this->reflect->getParameters();
		$output = array();

		foreach( $params as $param ) 
		{
			$key = $param->getName();

			if( $output[$key]['hasDefault'] = $param->IsDefaultValueAvailable()  )
				 $output[$key]['default'] = $param->getDefaultValue();

			$output[$key]['optional'] = $param->isOptional() ? 'optional' : 'required';
		}

		$params = $this->parser->getParams();

		if( !empty( $params['return'] ) )
			$this->return = $params['return'];

		if( !empty( $params['since'] ) )
			$this->since = $params['since'];

		if ( $params['param'] ) 
		{
			foreach( $params['param'] as $param ) 
			{
				$name = $param['name'];
				unset( $param['name'] );
	
				if( isset( $output[$name] ) )
					$output[$name] = array_merge( $output[$name], $param );
			}
		}

		return $output;
	}
}

//namespace Doqumentor;
/**
	This file is part of Doqumentor.

    Doqumentor is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    Doqumentor is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with Doqumentor.  If not, see <http://www.gnu.org/licenses/>.
*/
/**
* PHPDoc parser for use in Doqumentor
*
* Simple example usage:
* $a = new Parser($string);
* $a->parse();
*
* @author Murray Picton
* @copyright 2010 Murray Picton
*/
class Parser 
{
	/**
	* The string that we want to parse
	*/
	private $string;
	/**
	* Storge for the short description
	*/
	private $shortDesc;
	/**
	* Storge for the long description
	*/
	private $longDesc;
	/**
	* Storge for all the PHPDoc parameters
	*/
	private $params;

	/**
	* Parse each line
	*
	* Takes an array containing all the lines in the string and stores
	* the parsed information in the object properties
	*
	* @param array $lines An array of strings to be parsed
	*/
	private function parseLines( $lines ) 
	{
		foreach( $lines as $line ) 
		{
			$parsedLine = $this->parseLine( $line ); //Parse the line

			if( $parsedLine === false && empty( $this->shortDesc ) ) 
			{
				// Store the first line in the short description
				$this->shortDesc = implode( PHP_EOL, $desc );
				$desc = array();
			} 
			elseif( $parsedLine !== false ) 
			{
				// Store the line in the long description
				$desc[] = $parsedLine; 
			}
		}
		$this->longDesc = implode( PHP_EOL, $desc );
	}
	/**
	* Parse the line
	*
	* Takes a string and parses it as a PHPDoc comment
	*
	* @param string $line The line to be parsed
	* @return mixed False if the line contains no parameters or paramaters
	* that aren't valid otherwise, the line that was passed in.
	*/
	private function parseLine( $line ) 
	{
		// Trim the whitespace from the line
		$line = trim( $line );

		// Empty line
		if( empty( $line ) ) 
			return false;

		if( strpos( $line, '@' ) === 0 ) 
		{
			// Get the parameter name
			$param = substr( $line, 1, strpos( $line, ' ' ) - 1 );
			// Get the value
			$value = substr( $line, strlen( $param ) + 2 );
			// Parse the line and return false if the parameter is valid
			if( $this->setParam( $param, $value ) )
				return false;
		}

		return $line;
	}
	/**
	* Setup the valid parameters
	*
	* @param string $type NOT USED
	*/
	private function setupParams( $type = "" ) 
	{
		$params = array(
			"access"	=>	'',
			"author"	=>	'',
			"copyright"	=>	'',
			"deprecated"=>	'',
			"example"	=>	'',
			"ignore"	=>	'',
			"internal"	=>	'',
			"link"		=>	'',
			"param"		=>	'',
			"return"	=> 	'',
			"see"		=>	'',
			"since"		=>	'',
			"tutorial"	=>	'',
			"version"	=>	''
		);

		$this->params = $params;
	}

	/**
	* Parse a parameter or string to display in simple typecast display
	*
	* @param string $string The string to parse
	* @return string Formatted string wiht typecast
	*/
	private function formatParamOrReturn( $string, $param ) 
	{
		if( 'param' == $param ) 
		{
			list( $type, $name, $description ) = explode( ' ', $string, 3 );
			$name = trim( $name,'$' );
		}
		else 
		{
			list( $type, $description ) = explode( ' ', $string, 2 );
		}

		if( 'bool' == $type )
			$type = 'boolean';

		if( 'int' == $type )
			$type = 'integer';

		return compact( 'type', 'name', 'description' );
	}

	/**
	* Set a parameter
	*
	* @param string $param The parameter name to store
	* @param string $value The value to set
	* @return bool True = the parameter has been set, false = the parameter was invalid
	*/
	private function setParam( $param, $value ) 
	{
		if( ! array_key_exists( $param, $this->params ) ) 
			return false;

		if( $param == 'param' || $param == 'return' ) 
			$value = $this->formatParamOrReturn( $value, $param );

		if( empty( $this->params[ $param ] ) ) 
		{
			if( 'param' == $param ) 
			{
				$this->params[ $param ] = array();
				$this->params[ $param ][] = $value;
			}
			else 
			{
				$this->params[ $param ] = $value;
			}
		} 
		else 
		{
			$this->params[ $param ][] = $value;
		}
		return true;
	}
	/**
	* Setup the initial object
	*
	* @param string $string The string we want to parse
	*/
	public function __construct( $string ) 
	{
		$this->string = $string;
		$this->setupParams();
	}
	/**
	* Parse the string
	*/
	public function parse() 
	{
		//Get the comment
		if( preg_match('#^/\*\*(.*)\*/#s', $this->string, $comment ) === false )
			die( "Error" );

		$comment = trim( $comment[1] );

		//Get all the lines and strip the * from the first character
		if( preg_match_all('#^\s*\*(.*)#m', $comment, $lines ) === false )
			die( 'Error' );

		$this->parseLines( $lines[1] );
	}
	/**
	* Get the short description
	*
	* @return string The short description
	*/
	public function getShortDesc() 
	{
		return $this->shortDesc;
	}
	/**
	* Get the long description
	*
	* @return string The long description
	*/
	public function getDesc() 
	{
		return $this->longDesc;
	}
	/**
	* Get the parameters
	*
	* @return array The parameters
	*/
	public function getParams() 
	{
		return $this->params;
	}
}
?>