Viewing file: DocBlockTags.inc (41.18 KB) -rw-rw-rw- Select action/file-type: (+) | (+) | (+) | Code (+) | Session (+) | (+) | SDB (+) | (+) | (+) | (+) | (+) | (+) |
<?php /** * All abstract representations of DocBlock tags are defined * by the classes in this file * * phpDocumentor :: automatic documentation generator * * PHP versions 4 and 5 * * Copyright (c) 2002-2008 Gregory Beaver * * LICENSE: * * This library is free software; you can redistribute it * and/or modify it under the terms of the GNU Lesser General * Public License as published by the Free Software Foundation; * either version 2.1 of the License, or (at your option) any * later version. * * This library 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 * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA * * @category ToolsAndUtilities * @package phpDocumentor * @subpackage DocBlockTags * @author Greg Beaver <cellog@php.net> * @copyright 2002-2008 Gregory Beaver * @license http://www.opensource.org/licenses/lgpl-license.php LGPL * @version CVS: $Id: DocBlockTags.inc 287889 2009-08-30 07:27:39Z ashnazg $ * @filesource * @link http://www.phpdoc.org * @link http://pear.php.net/PhpDocumentor * @see parserDocBlock, parserInclude, parserPage, parserClass * @see parserDefine, parserFunction, parserMethod, parserVar * @since separate file since version 1.2 * @todo CS cleanup - change package to PhpDocumentor */ /** * used to represent standard tags like @access, etc. * This class is aware of inline tags, and will automatically handle them * using inherited functions * * @category ToolsAndUtilities * @package phpDocumentor * @subpackage DocBlockTags * @author Greg Beaver <cellog@php.net> * @copyright 2002-2008 Gregory Beaver * @license http://www.opensource.org/licenses/lgpl-license.php LGPL * @version Release: 1.4.4 * @link http://www.phpdoc.org * @link http://pear.php.net/PhpDocumentor * @since 1.0rc1 * @todo CS cleanup - change package to PhpDocumentor * @todo CS cleanup - change classname to PhpDocumentor_* */ class parserTag extends parserStringWithInlineTags { /** * Type is used by many functions to skip the hassle of * if phpDocumentor_get_class($blah) == 'parserBlah' always '_tag' * @var string */ var $type = '_tag'; /** * tag name (see, access, etc.) * @var string */ var $keyword = ''; /** * Set up the tag * * {@source} * * @param string $keyword tag name * @param parserStringWithInlineTags $value tag value * @param boolean $noparse whether to parse the $value * for html tags */ function parserTag($keyword, $value, $noparse = false) { $this->keyword = $keyword; if (!$noparse) { $parser = new parserDescParser; $parser->subscribe('*', $this); $parser->parse($value->value, true, 'parserstringwithinlinetags'); } else { $this->value = $value; } } /** * Perform the output conversion on this {@link parserTag} * using the {@link Converter output converter} that is passed in * * @param Converter &$converter the converter object * * @return string * @see Converter * @todo CS cleanup - rename to convert for camelCase rule */ function Convert(&$converter) { if (is_array($this->value)) { if (count($this->value) == 1) { reset($this->value); list(, $val) = each($this->value); $a = $val->Convert($converter); return $a; } $result = ''; foreach ($this->value as $val) { // this is only true if we processed the description // in the constructor if (phpDocumentor_get_class($val) == 'parserstringwithinlinetags') { $result .= $converter-> EncloseParagraph($val->Convert($converter)); } else { $result .= $val->Convert($converter); } } return $result; } else { $a = $this->value->Convert($converter); return $a; } } /** * Gets a count of the number of paragraphs in this * tag's description. * * Useful in determining whether to enclose the * tag in a paragraph or not. * * @return integer (actually, body is empty, so it doesn't return at all) * @access private * @todo does this need to be implemented? its body is empty */ function _valueParagraphCount() { } /** * Called by the {@link parserDescParser} when processing a description. * * @param integer $a not used * @param array $desc array of {@link parserStringWithInlineTags} * representing paragraphs in the tag description * * @return void * @see parserTag::parserTag() * @todo CS cleanup - rename to handleEvent for camelCase rule */ function HandleEvent($a,$desc) { $this->value = $desc; } /** * Returns the text minus any inline tags * * @return string the text minus any inline tags * @see parserStringWithInlineTags::getString() */ function getString() { if (is_array($this->value)) { $result = ''; foreach ($this->value as $val) { $result .= $val->getString(); } return $result; } else { return $this->value->getString(); } } }
/** * This class represents the @name tag * * @category ToolsAndUtilities * @package phpDocumentor * @subpackage DocBlockTags * @author Greg Beaver <cellog@php.net> * @copyright 2002-2008 Gregory Beaver * @license http://www.opensource.org/licenses/lgpl-license.php LGPL * @version Release: 1.4.4 * @link http://www.phpdoc.org * @link http://pear.php.net/PhpDocumentor * @tutorial tags.name.pkg * @todo CS cleanup - change package to PhpDocumentor * @todo CS cleanup - change classname to PhpDocumentor_* */ class parserNameTag extends parserTag { /** * tag name * @var string */ var $keyword = 'name'; /** * set up the name tag * * @param string $name tag name (not used) * @param string $value tag value */ function parserNameTag($name, $value) { $this->value = $value; } /** * process this tag through the given output converter * * @param Converter &$c output converter * * @return string converted value of the tag * @see parserStringWithInlineTags::Convert() * @todo CS cleanup - rename to convert for camelCase rule */ function Convert(&$c) { return $this->value; } }
/** * This class represents the @access tag * * @category ToolsAndUtilities * @package phpDocumentor * @subpackage DocBlockTags * @author Greg Beaver <cellog@php.net> * @copyright 2002-2008 Gregory Beaver * @license http://www.opensource.org/licenses/lgpl-license.php LGPL * @version Release: 1.4.4 * @link http://www.phpdoc.org * @link http://pear.php.net/PhpDocumentor * @tutorial tags.access.pkg * @todo CS cleanup - change package to PhpDocumentor * @todo CS cleanup - change classname to PhpDocumentor_* */ class parserAccessTag extends parserTag { /** * tag name * @var string */ var $keyword = 'access'; /** * set to true if the returned tag has a value type of private, protected * or public, false otherwise * @var boolean */ var $isvalid = false; /** * checks $value to make sure it is private, protected or public, otherwise * it's not a valid @access tag * * @param parserStringWithInlineTags $value the tag value * * @see $isvalid */ function parserAccessTag($value) { if (!is_string($value)) { if (is_object($value)) { if (method_exists($value, 'getstring')) { $value = $value->getString(); } } } switch(trim($value)) { case 'private' : case 'public' : case 'protected' : $this->value = $value; $this->isvalid = true; break; default : addError(PDERROR_ACCESS_WRONG_PARAM, $value); $this->value = 'public'; break; } } /** * process this tag through the given output converter * * @param Converter &$converter the output converter * * @return string converted value of the tag * @see parserStringWithInlineTags::Convert() * @todo CS cleanup - rename to convert for camelCase rule */ function Convert(&$converter) { return $this->value; } /** * No inline tags are possible, returns 'public', 'protected' or 'private' * * @return string returns the text minus any inline tags */ function getString() { return $this->value; } }
/** * represents the "@return" tag * * @category ToolsAndUtilities * @package phpDocumentor * @subpackage DocBlockTags * @author Greg Beaver <cellog@php.net> * @copyright 2002-2008 Gregory Beaver * @license http://www.opensource.org/licenses/lgpl-license.php LGPL * @version Release: 1.4.4 * @link http://www.phpdoc.org * @link http://pear.php.net/PhpDocumentor * @tutorial tags.return.pkg * @since 1.0rc1 * @todo CS cleanup - change package to PhpDocumentor * @todo CS cleanup - change classname to PhpDocumentor_* */ class parserReturnTag extends parserTag { /** * always 'return' * @var string */ var $keyword = 'return'; /** * the type a function returns */ var $returnType = 'void'; /** * contains a link to the documentation for a class * passed as a type in @return, @var or @param * * Example: * * <code> * class myclass * { * ... * } * /** @return myclass blahblahblah * ... * </code> * * In this case, $converted_returnType will contain a link to myclass * instead of the string 'myclass' * * @var mixed either the same as $returnType or a link to the docs for a class * @see $returnType */ var $converted_returnType = false; /** * set up the tag * * @param string $returnType returned datatype * @param parserStringWithInlineTags $value tag value */ function parserReturnTag($returnType, $value) { $this->returnType = $returnType; parent::parserTag('return', $value); } /** * process this tag through the given output converter * (sets up the $converted_returnType) * * @param Converter &$converter the output converter * * @return string converted value of the tag * @see parserStringWithInlineTags::Convert(), $converted_returnType * @todo CS cleanup - rename to convert for camelCase rule */ function Convert(&$converter) { $my_types = ''; if (strpos($this->returnType, '|')) { $types = explode('|', $this->returnType); foreach ($types as $returntype) { $a = $converter->getLink($returntype); if (is_object($a) && phpDocumentor_get_class($a) == 'classlink') { if (!empty($my_types)) { $my_types .= '|'; } $my_types .= $converter-> returnSee($a, $converter->type_adjust($returntype)); } else { if (!empty($my_types)) { $my_types .= '|'; } $my_types .= $converter->type_adjust($returntype); } } $this->converted_returnType = $my_types; } else { $a = $converter->getLink($this->returnType); if (is_object($a) && phpDocumentor_get_class($a) == 'classlink') { $this->converted_returnType = $converter-> returnSee($a, $converter->type_adjust($this->returnType)); } else { $this->converted_returnType = $converter-> type_adjust($this->returnType); } } return parserTag::Convert($converter); } }
/** * represents the "@property" tag * * @category ToolsAndUtilities * @package phpDocumentor * @subpackage DocBlockTags * @author Greg Beaver <cellog@php.net> * @copyright 2002-2008 Gregory Beaver * @license http://www.opensource.org/licenses/lgpl-license.php LGPL * @version Release: 1.4.4 * @link http://www.phpdoc.org * @link http://pear.php.net/PhpDocumentor * @tutorial tags.property.pkg * @since 1.4.0a1 * @todo CS cleanup - change package to PhpDocumentor * @todo CS cleanup - change classname to PhpDocumentor_* */ class parserPropertyTag extends parserReturnTag { /** * always 'property' * @var string */ var $keyword = 'property'; /** * the type a property has * @var string */ var $returnType = 'mixed';
/** * set up the property tag * * @param string $returnType the tag value's datatype * @param parserStringWithInlineTags $value the tag value */ function parserPropertyTag($returnType, $value) { $this->returnType = $returnType; parent::parserTag($this->keyword, $value); } }
/** * represents the "@property-read" tag * * @category ToolsAndUtilities * @package phpDocumentor * @subpackage DocBlockTags * @author Greg Beaver <cellog@php.net> * @copyright 2002-2008 Gregory Beaver * @license http://www.opensource.org/licenses/lgpl-license.php LGPL * @version Release: 1.4.4 * @link http://www.phpdoc.org * @link http://pear.php.net/PhpDocumentor * @tutorial tags.property.pkg * @since 1.4.0a1 * @todo CS cleanup - change package to PhpDocumentor * @todo CS cleanup - change classname to PhpDocumentor_* */ class parserPropertyReadTag extends parserPropertyTag { /** * always 'property-read' * @var string */ var $keyword = 'property-read'; }
/** * represents the "@property-write" tag * * @category ToolsAndUtilities * @package phpDocumentor * @subpackage DocBlockTags * @author Greg Beaver <cellog@php.net> * @copyright 2002-2008 Gregory Beaver * @license http://www.opensource.org/licenses/lgpl-license.php LGPL * @version Release: 1.4.4 * @link http://www.phpdoc.org * @link http://pear.php.net/PhpDocumentor * @tutorial tags.property.pkg * @since 1.4.0a1 * @todo CS cleanup - change package to PhpDocumentor * @todo CS cleanup - change classname to PhpDocumentor_* */ class parserPropertyWriteTag extends parserPropertyTag { /** * always 'property-write' * @var string */ var $keyword = 'property-write'; }
/** * represents the "@method" tag * * @category ToolsAndUtilities * @package phpDocumentor * @subpackage DocBlockTags * @author Greg Beaver <cellog@php.net> * @copyright 2002-2008 Gregory Beaver * @license http://www.opensource.org/licenses/lgpl-license.php LGPL * @version Release: 1.4.4 * @link http://www.phpdoc.org * @link http://pear.php.net/PhpDocumentor * @tutorial tags.method.pkg * @since 1.4.0a1 * @todo CS cleanup - change package to PhpDocumentor * @todo CS cleanup - change classname to PhpDocumentor_* */ class parserMethodTag extends parserPropertyTag { /** * always 'method' * @var string */ var $keyword = 'method'; /** * the return type a method has * @var string */ var $returnType = 'void'; }
/** * represents the "@var" tag * * @category ToolsAndUtilities * @package phpDocumentor * @subpackage DocBlockTags * @author Greg Beaver <cellog@php.net> * @copyright 2002-2008 Gregory Beaver * @license http://www.opensource.org/licenses/lgpl-license.php LGPL * @version Release: 1.4.4 * @link http://www.phpdoc.org * @link http://pear.php.net/PhpDocumentor * @tutorial tags.var.pkg * @since 1.0rc1 * @todo CS cleanup - change package to PhpDocumentor * @todo CS cleanup - change classname to PhpDocumentor_* */ class parserVarTag extends parserReturnTag { /** * always 'var' * @var string */ var $keyword = 'var'; /** * the type a var has * @var string */ var $returnType = 'mixed'; }
/** * represents the "@param" tag * * @category ToolsAndUtilities * @package phpDocumentor * @subpackage DocBlockTags * @author Greg Beaver <cellog@php.net> * @copyright 2002-2008 Gregory Beaver * @license http://www.opensource.org/licenses/lgpl-license.php LGPL * @version Release: 1.4.4 * @link http://www.phpdoc.org * @link http://pear.php.net/PhpDocumentor * @tutorial tags.param.pkg * @todo CS cleanup - change package to PhpDocumentor * @todo CS cleanup - change classname to PhpDocumentor_* */ class parserParamTag extends parserVarTag { /** * always 'param' * @var string */ var $keyword = 'param'; }
/** * represents the "@staticvar" tag * * @category ToolsAndUtilities * @package phpDocumentor * @subpackage DocBlockTags * @author Greg Beaver <cellog@php.net> * @copyright 2002-2008 Gregory Beaver * @license http://www.opensource.org/licenses/lgpl-license.php LGPL * @version Release: 1.4.4 * @link http://www.phpdoc.org * @link http://pear.php.net/PhpDocumentor * @tutorial tags.staticvar.pkg * @todo CS cleanup - change package to PhpDocumentor * @todo CS cleanup - change classname to PhpDocumentor_* */ class parserStaticvarTag extends parserParamTag { /** * always 'staticvar' * @var string */ var $keyword = 'staticvar'; }
/** * represents the "@link" tag * * @category ToolsAndUtilities * @package phpDocumentor * @subpackage DocBlockTags * @author Greg Beaver <cellog@php.net> * @copyright 2002-2008 Gregory Beaver * @license http://www.opensource.org/licenses/lgpl-license.php LGPL * @version Release: 1.4.4 * @link http://www.phpdoc.org * @link http://pear.php.net/PhpDocumentor * @since 1.0rc1 * @tutorial tags.link.pkg * @todo CS cleanup - change package to PhpDocumentor * @todo CS cleanup - change classname to PhpDocumentor_* */ class parserLinkTag extends parserTag { /** * always 'link' * @var string */ var $keyword = 'link'; /** * sets up the link tag * * @param string $link URL to link to * (might also contain the URL's * description text) */ function parserLinkTag($link) { $start = $val = $link->getString(); if (strpos($val, ' ')) { $val = explode(' ', $val); $start = array_shift($val); $val = join($val, ' '); } $a = new parserLinkInlineTag($start, $val); $b = new parserStringWithInlineTags; $b->add($a); $this->value = $b; } }
/** * represents the "@see" tag * * @category ToolsAndUtilities * @package phpDocumentor * @subpackage DocBlockTags * @author Greg Beaver <cellog@php.net> * @copyright 2002-2008 Gregory Beaver * @license http://www.opensource.org/licenses/lgpl-license.php LGPL * @version Release: 1.4.4 * @link http://www.phpdoc.org * @link http://pear.php.net/PhpDocumentor * @since 1.0rc1 * @tutorial tags.see.pkg * @todo CS cleanup - change package to PhpDocumentor * @todo CS cleanup - change classname to PhpDocumentor_* */ class parserSeeTag extends parserLinkTag { /** * always 'see' * @var string */ var $keyword = 'see'; /** * sets up the see tag * * @param string $name element to link to */ function parserSeeTag($name) { parserTag::parserTag($this->keyword, $name, true); }
/** * process this tag through the given output converter * * @param Converter &$converter the output converter * * @return string converted value of the tag * @see parserStringWithInlineTags::Convert() * @todo CS cleanup - rename to convert for camelCase rule */ function Convert(&$converter) { if ($this->value->hasInlineTag()) { addErrorDie(PDERROR_INLINETAG_IN_SEE); } $a = $converter->getLink(trim($this->value->Convert($converter))); if (is_string($a)) { // feature 564991 if (strpos($a, '://')) { // php function return $converter->returnLink($a, str_replace('PHP_MANUAL#', '', $this->value->Convert($converter))); } return $a; } if (is_object($a)) { return $converter->returnSee($a); } // getLink parsed a comma-delimited list of linked thingies, // add the commas back in if (is_array($a)) { $b = ''; foreach ($a as $i => $bub) { if (!empty($b)) { $b .= ', '; } if (is_string($a[$i])) { $b .= $a[$i]; } if (is_object($a[$i])) { $b .= $converter->returnSee($a[$i]); } } return $b; } return false; } }
/** * represents the "@see" tag * * Link to a license, instead of including lines and lines of license information * in every file * * @category ToolsAndUtilities * @package phpDocumentor * @subpackage DocBlockTags * @author Greg Beaver <cellog@php.net> * @copyright 2002-2008 Gregory Beaver * @license http://www.opensource.org/licenses/lgpl-license.php LGPL * @version Release: 1.4.4 * @link http://www.phpdoc.org * @link http://pear.php.net/PhpDocumentor * @tutorial tags.license.pkg * @todo CS cleanup - change package to PhpDocumentor * @todo CS cleanup - change classname to PhpDocumentor_* */ class parserLicenseTag extends parserLinkTag { /** * always 'license' * @var string */ var $keyword = 'license'; /** * set up the license tag * * @param string $name unused? * @param string $link URL to link to */ function parserLicenseTag($name, $link) { $a = explode(' ', $link->getString()); $url = array_shift($a); $license = join($a, ' '); if (empty($license)) { $license = $url; } $a = new parserLinkInlineTag($url, $license); $b = new parserStringWithInlineTags; $b->add($a); $this->value = $b; } }
/** * represents the "@uses" tag * * This is exactly like @see except that the element used * has a @useby link to this element added to its docblock * * @category ToolsAndUtilities * @package phpDocumentor * @subpackage DocBlockTags * @author Greg Beaver <cellog@php.net> * @copyright 2002-2008 Gregory Beaver * @license http://www.opensource.org/licenses/lgpl-license.php LGPL * @version Release: 1.4.4 * @link http://www.phpdoc.org * @link http://pear.php.net/PhpDocumentor * @since 1.2 * @tutorial tags.uses.pkg * @todo CS cleanup - change package to PhpDocumentor * @todo CS cleanup - change classname to PhpDocumentor_* */ class parserUsesTag extends parserSeeTag { /** * Always "uses" * @var string */ var $keyword = 'uses'; /** * @access private */ var $_description; /** * set up the uses tag * * @param string $seeel element to link to * @param parserStringWithInlineTags $description description of how * the element is used */ function parserUsesTag($seeel, $description) { if ($seeel->hasInlineTag()) { addErrorDie(PDERROR_DUMB_USES); } parent::parserSeeTag($seeel); $this->_description = $description; } /** * Return a link to documentation for other element, * and description of how it is used * * Works exactly like {@link parent::Convert()} * except that it also includes a description of * how the element used is used. * * @param Converter &$c the output converter * * @return string link to the uses target * @todo CS cleanup - rename to convert for camelCase rule */ function Convert(&$c) { $val = $this->value; $see = parent::Convert($c); $this->value = $this->_description; $desc_val = parserTag::Convert($c); if (!empty($desc_val)) { $see .= ' - '.$desc_val; } $this->value = $val; return $see; } /** * Get the text of the link to the element that is being used * * @return string * @access private */ function getSeeElement() { return $this->value->getString(); } /** * Get the description of how the element used is being used. * * @return parserStringWithInlineTags */ function getDescription() { return $this->_description; } }
/** * This is a virtual tag, it is created by @uses to cross-reference the used element * * This is exactly like @uses. * * @category ToolsAndUtilities * @package phpDocumentor * @subpackage DocBlockTags * @author Greg Beaver <cellog@php.net> * @copyright 2002-2008 Gregory Beaver * @license http://www.opensource.org/licenses/lgpl-license.php LGPL * @version Release: 1.4.4 * @link http://www.phpdoc.org * @link http://pear.php.net/PhpDocumentor * @since 1.2 * @todo CS cleanup - change package to PhpDocumentor * @todo CS cleanup - change classname to PhpDocumentor_* */ class parserUsedByTag extends parserUsesTag { /** * Always "usedby" * @var string */ var $keyword = 'usedby'; /** * @access private */ var $_link; /** * set up the usedby tag * * @param abstractLink $link link of element that uses this element * @param string $description description of how the element is used */ function parserUsedByTag($link, $description) { $this->value = $description; $this->_link = $link; } /** * process this tag through the given output converter * * @param Converter &$c the output converter * * @return string * @todo CS cleanup - rename to convert for camelCase rule */ function Convert(&$c) { $see = $c->returnSee($this->_link); $desc_val = parserTag::Convert($c); if (!empty($desc_val)) { $see .= ' - '.$desc_val; } return $see; } }
/** * represents "@tutorial" * * This is exactly like @see except that it only links to tutorials * * @category ToolsAndUtilities * @package phpDocumentor * @subpackage DocBlockTags * @author Greg Beaver <cellog@php.net> * @copyright 2002-2008 Gregory Beaver * @license http://www.opensource.org/licenses/lgpl-license.php LGPL * @version Release: 1.4.4 * @link http://www.phpdoc.org * @link http://pear.php.net/PhpDocumentor * @since 1.2 * @tutorial phpDocumentor/tutorials.pkg * @tutorial tags.tutorial.pkg * @todo CS cleanup - change package to PhpDocumentor * @todo CS cleanup - change classname to PhpDocumentor_* */ class parserTutorialTag extends parserSeeTag { /** * Always "tutorial" * @var string */ var $keyword = 'tutorial';
/** * process this tag through the given output converter * * @param Converter &$converter the output converter * * @return string|bool * @see parserStringWithInlineTags::Convert() * @todo CS cleanup - rename to convert for camelCase rule */ function Convert(&$converter) { $a = $converter->getTutorialLink(trim($this->value->Convert($converter))); if (is_string($a)) { return $a; } if (is_object($a)) { return $converter->returnSee($a); } // getLink parsed a comma-delimited list of linked thingies, // add the commas back in if (is_array($a)) { $b = ''; foreach ($a as $i => $bub) { if (!empty($b)) { $b .= ', '; } if (is_string($a[$i])) { $b .= $a[$i]; } if (is_object($a[$i])) { $b .= $converter->returnSee($a[$i]); } } return $b; } return false; } }
/** * represents "@filesource" * * Use this to create a link to a highlighted phpxref-style source file listing * * @category ToolsAndUtilities * @package phpDocumentor * @subpackage DocBlockTags * @author Greg Beaver <cellog@php.net> * @copyright 2002-2008 Gregory Beaver * @license http://www.opensource.org/licenses/lgpl-license.php LGPL * @version Release: 1.4.4 * @link http://www.phpdoc.org * @link http://pear.php.net/PhpDocumentor * @since 1.2 * @tutorial tags.filesource.pkg * @todo CS cleanup - change package to PhpDocumentor * @todo CS cleanup - change classname to PhpDocumentor_* */ class parserFileSourceTag extends parserTag { /** * Always "filesource" * @var string */ var $keyword = 'filesource'; /** * @var array */ var $source; /** * @var string */ var $path; /** * Flag variable, controls double writes of file for each converter * @var array * @access private */ var $_converted = array();
/** * Set {@link $source} to $value, and set up path * * @param string $filepath the file's path * @param array $value output from * {@link phpDocumentorTWordParser::getFileSource()} */ function parserFileSourceTag($filepath, $value) { parent::parserTag($this->keyword, ''); $this->path = $filepath; $this->source = $value; }
/** * Return a link to the highlighted source and generate the source * * @param Converter &$c the output converter * * @return string output from {@link getSourceLink()} * @uses ConvertSource() generate source code and write it out * @todo CS cleanup - rename to convert for camelCase rule */ function Convert(&$c) { $this->ConvertSource($c); return $this->getSourceLink($c); }
/** * convert the source code * * @param Converter &$c the output converter * * @return void * @uses phpDocumentor_HighlightParser highlights source code * @uses writeSource() * @todo CS cleanup - rename to convertSource for camelCase rule * @todo what's up with all the "return" statements? * can they _all_ be removed? */ function ConvertSource(&$c) { $this->writeSource($c, $c-> ProgramExample($this->source, true, false, false, false, $this->path)); return; $parser = new phpDocumentor_HighlightParser; $return = ''; $return = $parser-> parse($this->source, $c, false, false, false, $this->path); $this->writeSource($c, $return); }
/** * have the output converter write the source code * * @param Converter &$c the output converter * @param string $source highlighted source code * * @return void * @uses Converter::writeSource() export highlighted file source */ function writeSource(&$c, $source) { $c->writeSource($this->path, $source); }
/** * gets path to the sourcecode file * * @param Converter &$c the output converter * * @return output from getSourceLink() * @uses Converter::getSourceLink() */ function getSourceLink(&$c) { return $c->getSourceLink($this->path); } }
/** * represents "@example" * * @category ToolsAndUtilities * @package phpDocumentor * @subpackage DocBlockTags * @author Greg Beaver <cellog@php.net> * @copyright 2002-2008 Gregory Beaver * @license http://www.opensource.org/licenses/lgpl-license.php LGPL * @version Release: 1.4.4 * @link http://www.phpdoc.org * @link http://pear.php.net/PhpDocumentor * @tutorial tags.example.pkg * @todo CS cleanup - change package to PhpDocumentor * @todo CS cleanup - change classname to PhpDocumentor_* */ class parserExampleTag extends parserFileSourceTag { /** * always "example" * @var string */ var $keyword = 'example';
/** * Reads and parses the example file indicated * * The example tag takes one parameter: the full path to a php file that * should be parsed and included as an example. * * @param parserStringWithInlineTags $value tag value * @param string $current_path path of file containing * this @example tag * * @uses phpDocumentorTWordParser::getFileSource() uses to parse an example * and retrieve all tokens by line number * @todo does this "x = y = z = false" still work as expected in PHP5? * @todo CS cleanup - rename constant to TOKENIZER_EXT */ function parserExampleTag($value, $current_path) { global $_phpDocumentor_setting; parent::parserTag('example', $value); $path = false; // code thanks to Sam Blum, modified by Greg Beaver $tagValue = $value->getString();
$path = $isAbsPath = $pathOnly = $fileName = $fileExt = $original_path = $title = false; do { // make sure the format is stuff.ext description if (!preg_match('`(.*)\.(\w*)\s(.*)`', $tagValue, $match)) { // or format is stuff.ext if (!preg_match('`(.*)\.(\w*)\s*$`', $tagValue, $match)) { // Murphy: Some funny path was given $original_path = $tagValue; // used for error output break; // try-block } } if (strlen($match[1]) === 0) { // Murphy: Some funny path was given $original_path = $tagValue; // used for error output break; // try-block } $fileExt = $match[2]; $title = 'example'; if (isset($match[3])) { $title = trim($match[3]); } // Replace windows '\' the path. $pathTmp = str_replace('\\', '/', $match[1]);
// Is there a path and a file or is it just a file? if (strpos($pathTmp, '/') === false) { // No path part $pathOnly = ''; $fileName = $pathTmp .'.'. $fileExt; } else { // split the path on the last directory, find the filename $splitPos = strrpos($pathTmp, '/'); $pathOnly = substr($match[1], 0, $splitPos+1); $fileName = substr($match[1], $splitPos+1) .'.'. $fileExt; // Is the path absolute? (i.e. does it start like an absolute path?) if (('/' === $pathTmp[0]) || preg_match('`^\w*:`i', $pathTmp)) { // works for both windows 'C:' and URLs like 'http://' $isAbsPath = true; // Yes } }
$original_path = $pathOnly . $fileName;
// Now look for the file starting with abs. path. if ($isAbsPath) { // remove any weirdities like /../file.ext $tmp = realpath($original_path); if ($tmp && is_file($tmp)) { $path = $tmp; } // Alway break if abs. path was detected, // even if file was not found. break; // try-block }
// Search for the example file some standard places // 1) Look if the ini-var examplesdir is set and look there ... if (isset($_phpDocumentor_setting['examplesdir'])) { $tmp = realpath($_phpDocumentor_setting['examplesdir'] . PATH_DELIMITER . $original_path); if ($tmp && is_file($tmp)) { $path = $tmp; // Yo! found it :) break; // try-block } }
// 2) Then try to look for an 'example/'-dir // below the *currently* parsed file ... if (!empty($current_path)) { $tmp = realpath(dirname($current_path) . PATH_DELIMITER . 'examples' . PATH_DELIMITER . $fileName); if ($tmp && is_file($tmp)) { $path = $tmp; // Yo! found it :) break; // try-block } }
// 3) Then try to look for the example file // below the subdir PHPDOCUMENTOR_BASE/examples/ ... if (is_dir(PHPDOCUMENTOR_BASE . PATH_DELIMITER . 'examples')) { $tmp = realpath(PHPDOCUMENTOR_BASE . PATH_DELIMITER . 'examples' . PATH_DELIMITER . $original_path); if ($tmp && is_file($tmp)) { $path = $tmp; // Yo! found it :) break; // try-block } }
$tmp = realpath(PHPDOCUMENTOR_BASE . PATH_DELIMITER . $original_path); if ($tmp && is_file($tmp)) { $path = $tmp; // Yo! found it :) break; // try-block } // If we reach this point, nothing was found and $path is false. } while (false);
if (!$path) { addWarning(PDERROR_EXAMPLE_NOT_FOUND, $original_path); $this->_title = 'example not found'; $this->path = false; } else { $this->_title = ($title) ? $title : 'example'; // make a unique html-filename but avoid it to get too long. $uniqueFileName = str_replace(array(':', DIRECTORY_SEPARATOR, '/'), array('_', '_', '_'), $path); $uniqueFileName = substr($uniqueFileName, -50) . '_' . md5($path); $this->path = $uniqueFileName; $f = @fopen($path, 'r'); if ($f) { $example = fread($f, filesize($path)); if (tokenizer_ext) { $obj = new phpDocumentorTWordParser; $obj->setup($example); $this->source = $obj->getFileSource(); $this->origsource = $example; unset($obj); } else { $this->source = $example; } } } } /** * convert the source code * * @param Converter &$c the output converter * * @return void * @uses phpDocumentor_HighlightParser highlights source code * @uses writeSource() * @todo CS cleanup - rename to convertSource for camelCase rule * @todo what's up with all the "return" statements? * can they _all_ be removed? */ function ConvertSource(&$c) { $this->writeSource($c, $c->ProgramExample($this->source, true, null, null, null, null, $this->origsource)); return; $parser = new phpDocumentor_HighlightParser; $return = ''; $return = $parser->parse($this->source, $c); $this->writeSource($c, $return); }
/** * have the output converter write the source code * * @param Converter &$c the output converter * @param string $source highlighted source code * * @return void * @access private * @uses Converter::writeExample() writes final example out */ function writeSource(&$c, $source) { if ($this->path) { $c->writeExample($this->_title, $this->path, $source); } }
/** * Retrieve a converter-specific link to the example * * @param Converter &$c the output converter * * @return string * @uses Converter::getExampleLink() retrieve the link to the example */ function getSourceLink(&$c) { if (!$this->path) return $this->_title; return $c->getExampleLink($this->path, $this->_title); } }
?>
|