ePages 6.11.0 - DE_EPAGES/SourceDoc/API/BaseLanguage.pm

Package DE_EPAGES::SourceDoc::API::BaseLanguage

This an abstract parser class that can be used to parse source code in multiple languages. Derived classes implement the specifics for a particular language.

Functions

SavePreText
SaveSkip
SaveText
defaultState
new
parseCode
project
replaceTag
replaceTagLinks
sourceDir
targetDir

SavePreText

Saves a plain text key and preserves whitespace

Syntax
$self->SavePreText( $hBlock, $hResult )
Input
$hBlock
block to save
$Flags
flags
Output
$hResult
will be filled with the content of the tag

all unused charakters are removed from the content
$hMessage
hash reference; must be filled with errors and warnings while
parsing the data
Return
0 for do not save this element and all childs, else 1

SaveSkip

Prevents from saving unused information

Syntax
$self->SaveSkip( $hBlock, $hResult )
Input
$hBlock
block to save
$Flags
flags
Output
$hResult
will be filled with the content of the tag

all unused charakters are removed from the content
$hMessage
hash reference; must be filled with errors and warnings while
parsing the data
Return
(0 for do not save this element and all childs, else 1)
$ret

SaveText

Saves a plain text key

Syntax
$self->SaveText( $hBlock, $hResult )
Input
$hBlock
block to save
$Flags
flags
Output
$hResult
will be filled with the content of the tag

all unused charakters are removed from the content
$hMessage
hash reference; must be filled with errors and warnings while
parsing the data
Return
0 for do not save this element and all childs, else 1

defaultState

Returns or sets the default state for any documantation item that has not specified whether it is public or private.

Syntax
$DefaultState = $self->defaultState;
$self->defaultState( $DefaultState );
Input
$DefaultState (string)
default state (public|private)
Return
$DefaultState (string)
default state (public|private)

new

Creates a new parser object.

Syntax
$Parser = DE_EPAGES::SourceDoc::API::BaseLanguage->new(%Options);
Input
%Options (hash.string)
options
Return
$Parser (object)
parser object

parseCode

builds the recurse hash-array-structur

Syntax
$ret = $self->parseCode( $Parent, $ToParse, $Code, $hResult );
Input
$Parent (hash-reference)
parent hash for current tags to parse

use undef for empty elements


{
'Name' => <name of the tag, usefull for output>,
'ID' => <ID of the tag, usefull to compare with other tags>,
'ReplaceContent' => will be processed first for the whole text with
the options sge
[
{
'Expression' => <expression to search for>,
'Data' => <data to replace the found text>,
},
...
],
'ReplaceContentLine' => will be processed first for the lines of text to parse
[
{
'Expression' => <expression to search for>,
'Data' => <data to replace the found text>,
},
...
],
'Tags' => all tags belonging to the current topic
[
{
'Expression' => <expression that identifies a tag>,
'Type' => <reference to the type data of the tag>,
},
...
],
'Childs' => all tags that are childs from the currect topic
[
{
'Filter' => expression that returns 0 as long as the text must be processed

the info to skip text of this topic type
is stored so parsing for e.g. globals after functions can be prevent
'Expression' => <expression that identifies a child tag>,
'Type' => <reference to the type data of the child tag>,
},
...
],
'Save' => saves the current tag (but not the childs)
{
'Module' => <Module that contains the save function>,
'Function' => <the save function>,
},
}

$ToParse
'Childs' or 'Tags'
$Code
content to parse, can contains code and comments
Output
$hResult (hash-reference)
hash with help data

{
'Pathes' => points to a hash with all sub pathes of this path
{
<Path-Name> => <Name of the sub path>
{
'Files' => points to an array reference of files contained
in the sub path
[
{
'Language' => Language (Perl, SQL, Java, ...)
'Type' => <type of the entry (file)>
'FileType' => <type of the file: Perl Module or Perl Script)>
<farther data> => <farther language-dependent data>
this must point to an array of hashes;
each hash must contain the keys
Type (package, function), ParentResult
(points to the parent result set) and Index
(the index of the array element); some keys
can contains again <farther data>;
to allow displaying data as link an
element 'Name' must exist
}
]
}
}
}

Return
(0 to skip storing the result, else 1)
$ret

project

Returns or sets the project. If a project is specified, then the parser will only extract documentation that belongs to this project.

Syntax
$Project = $self->project;
$self->project( $Project );
Input
$Project (string)
project name
Return
$Project (string)
project name, undef if no project is set

replaceTag

replaces a tag like '
' or 'function'

Syntax
$NewContent = $self->replaceTag( $TagContent, $Node, $LinkTemplate );
Input
$TagContent (string)
original text
$Node
$LinkTemplate (string)
link template
Return
$NewContent (string)
replacement text

replaceTagLinks

Replaces all links in help tags of a result set
The links are searched recursively in all tags of a file. For each found link the link parts are changed into a valid entry in the links array (with path, file name, package name a.s.o.). To do this the passed flags for building directories are used. After creating the entry it is searched in the link entries. If found the link is converted using the links template stored in $TemplDir/Links.html. While this is done the TLE's

are replaced. The result replaces all occureces of this link in the help tag content.
All invalid occurences of '' are replaced with the according html text.

Syntax
$self->replaceTagLinks( $hResult, $LinkTemplate )
Input
$LinkTemplate (string)
link template content
$hResult
hash reference with the parse result of one module

sourceDir

Returns the source directory.

Syntax
$SourceDir = $self->sourceDir;
Return
$SourceDir (string)
source directory

targetDir

Returns the target directory.

Syntax
$TargetDir = $self->targetDir;
Return
$TargetDir (string)
target directory