Source for file DocBlockTags.inc
Documentation is available at
DocBlockTags.inc
<?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 <
[email protected]
>
*
@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 <
[email protected]
>
*
@copyright
2002-2008 Gregory Beaver
*
@license
http://www.opensource.org/licenses/lgpl-license.php LGPL
*
@version
Release: @VER@
*
@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 <
[email protected]
>
*
@copyright
2002-2008 Gregory Beaver
*
@license
http://www.opensource.org/licenses/lgpl-license.php LGPL
*
@version
Release: @VER@
*
@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 <
[email protected]
>
*
@copyright
2002-2008 Gregory Beaver
*
@license
http://www.opensource.org/licenses/lgpl-license.php LGPL
*
@version
Release: @VER@
*
@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 <
[email protected]
>
*
@copyright
2002-2008 Gregory Beaver
*
@license
http://www.opensource.org/licenses/lgpl-license.php LGPL
*
@version
Release: @VER@
*
@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 <
[email protected]
>
*
@copyright
2002-2008 Gregory Beaver
*
@license
http://www.opensource.org/licenses/lgpl-license.php LGPL
*
@version
Release: @VER@
*
@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 <
[email protected]
>
*
@copyright
2002-2008 Gregory Beaver
*
@license
http://www.opensource.org/licenses/lgpl-license.php LGPL
*
@version
Release: @VER@
*
@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 <
[email protected]
>
*
@copyright
2002-2008 Gregory Beaver
*
@license
http://www.opensource.org/licenses/lgpl-license.php LGPL
*
@version
Release: @VER@
*
@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 <
[email protected]
>
*
@copyright
2002-2008 Gregory Beaver
*
@license
http://www.opensource.org/licenses/lgpl-license.php LGPL
*
@version
Release: @VER@
*
@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 <
[email protected]
>
*
@copyright
2002-2008 Gregory Beaver
*
@license
http://www.opensource.org/licenses/lgpl-license.php LGPL
*
@version
Release: @VER@
*
@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 <
[email protected]
>
*
@copyright
2002-2008 Gregory Beaver
*
@license
http://www.opensource.org/licenses/lgpl-license.php LGPL
*
@version
Release: @VER@
*
@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 <
[email protected]
>
*
@copyright
2002-2008 Gregory Beaver
*
@license
http://www.opensource.org/licenses/lgpl-license.php LGPL
*
@version
Release: @VER@
*
@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 <
[email protected]
>
*
@copyright
2002-2008 Gregory Beaver
*
@license
http://www.opensource.org/licenses/lgpl-license.php LGPL
*
@version
Release: @VER@
*
@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 <
[email protected]
>
*
@copyright
2002-2008 Gregory Beaver
*
@license
http://www.opensource.org/licenses/lgpl-license.php LGPL
*
@version
Release: @VER@
*
@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 <
[email protected]
>
*
@copyright
2002-2008 Gregory Beaver
*
@license
http://www.opensource.org/licenses/lgpl-license.php LGPL
*
@version
Release: @VER@
*
@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 <
[email protected]
>
*
@copyright
2002-2008 Gregory Beaver
*
@license
http://www.opensource.org/licenses/lgpl-license.php LGPL
*
@version
Release: @VER@
*
@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 <
[email protected]
>
*
@copyright
2002-2008 Gregory Beaver
*
@license
http://www.opensource.org/licenses/lgpl-license.php LGPL
*
@version
Release: @VER@
*
@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 <
[email protected]
>
*
@copyright
2002-2008 Gregory Beaver
*
@license
http://www.opensource.org/licenses/lgpl-license.php LGPL
*
@version
Release: @VER@
*
@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 <
[email protected]
>
*
@copyright
2002-2008 Gregory Beaver
*
@license
http://www.opensource.org/licenses/lgpl-license.php LGPL
*
@version
Release: @VER@
*
@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 <
[email protected]
>
*
@copyright
2002-2008 Gregory Beaver
*
@license
http://www.opensource.org/licenses/lgpl-license.php LGPL
*
@version
Release: @VER@
*
@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
)
;
}
}
?>
Documentation generated on Mon, 05 Dec 2011 21:26:15 -0600 by
phpDocumentor 1.4.4