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