Inside Language Parser

Lang module

Lang module

This module contains the API to language processing. It is responsible for creating the parser and handling the specific categories editing.

A language parser is an object with associated methods. Lang.pm creates the base object, to be augmented/overriden by specific parsers in directory Lang. The methods described below are generally only dummy declarations to capture missing specific implementations.

`new ($writeDB, $pathname, $releaseid, @itag)`

Method new creates a new language object.

$writeDB

a boolean integer requesting to write language properties into the tree database, passed unaltered to the specific parser initialisation method (set to 1 only by genxref)
$pathname

a string containing the name of the file to parse
$releaseid

a string containing the release (version) of the file to parse

Note:
- Considering all call locations, this argument is not really necessary and we could as well use the global variable.
@itag

an array of 3 elements used to generate an < A > link for the identifiers found in the file (just insert the identifier name between the array elements)

Creation of a specific parser is attempted first based on the file name and information from configuration parameter 'filetype'. If the file type is unknown, the first line of the file is read to tentatively extract a shebang processed through configuration parameter 'interpreters'. In case there is no shebang, an emacs-style mode: is looked for.

If all fail, undef is returned.

The LXR language name and argument @itag are recorded in the created parser which is then returned.

`parseable ($pathname, $releaseid)`

Function parseable returns 1 if the designated file can be parsed some way or other.

$pathname

a string containing the name of the file to parse
$releaseid

the release (or version) in which $pathname is expected to be found

This a streamlined version of method new where the filename argument is checked against the patterns from filetype.conf or the first line of the file against the interpreters list.

`multilinetwist ($frag, $css)`

Internal function multilinetwist marks the fragment with a CSS class.

$frag

a string to mark
$css

a string containing the CSS class

The fragment is surrounded with < SPAN > and < /SPAN > tags. Special care is taken to repeat these tags at end of lines, so that the fragment can be correctly displayed on several lines without disturbing other highlighting (such as line numbers or difference marks).

`processcomment ($frag)`

Method processcomment marks the fragment as a comment.

$frag

a string to mark

Uses function multilinetwist.

`processstring ($frag)`

Method processstring marks the fragment as a string.

$frag

a string to mark

Uses function multilinetwist.

`processextra ($frag, $kind)`

Method processextra marks the fragment as language specific.

$frag

a string to mark
$kind

a string containing the CSS class

Uses function multilinetwist.

`processinclude ($frag, $dir)`

Method processinclude is invoked to process an include directive.

$frag

a string containing the directive
$dir

an optional string containing a preferred directory for the include'd file

Usually, the link to the include'd file is built with 'incref'. Consequently, the directories in 'incprefix' are also searched.

`_linkincludedirs ($link, $file, $path, $dir)`

Internal function _linkincludedirs builds links for partial paths in $link.

$link

a string containing an already processed link, i.e. the result of an invocation of incref or incdirref.
$file

a string containing the target file name in the language-specific dialect (without language-specific separator replacement),
$sep

a string containing the language-specific path separator,
$path

a string containing the target file name as an OS file name (path separator is /),
$dir

a string containing the last directory argument for incdirref.

This function is a utility function reserved for the language parsers.

`_incfindfile ($filewanted, $file, @paths)`

Function _incfindfile returns the "full" path corresponding to argument $file.

$filewanted

a flag indicating if a directory (0) or file (1) is desired
$file

a string containing a file name to resolve
@paths

an array containing a list of directories to search

The list of directories from configuration parameter 'incprefix' is appended to @paths. Every directory from this array is then preprended to the file name . The resulting string is transformed by the mapping rules of configuration parameter 'maps' (See Config.pm sub mappath).

If there is a match in the file database (file or directory according to the first argument), the "physical" path is returned. Otherwise, an undef is returned to signal an unknown file.

This is a "private" or "internal" sub for include path resolution only.

`incdirref ($name, $css, $file, @paths)`

Function incdirref returns an < A > link to a directory of an included file or the directory name if it is unknown.

$name

a string for the user-visible part of the link, usually the directory name
$css

a string containing the CSS class for the link
$file

a string containing the HTML path to the directory
@paths

an array containing a list of base directories to search

This function is supposed to be called AFTER sub incref on every subpath of the include'd file, removing successively the tail directory. It thus allows to compose a path where each directory is separately clickable.

If the include'd directory does not exist (as determined by sub incfindfile), the function returns the directory name. This acts as a "no-op" in the HTML sequence representing the full path of the include'd file.

If the directory exists, the function returns the < A > link as computed by sub fileref for the directory.

`processcode ($code)`

Method processcode processes the fragment as code.

$code

a string to mark

`processreserved ($frag)`

Method processreserved marks the fragment as a reserved word.

$code

a string to mark

Note:

This method is nowhere invoked because keywords are processed in processcode simultaneouly with identifiers. It corresponds to no category. It is thus candidate for removal.

`indexfile ($name, $path, $fileid, $index, $config)`

Method indexfile is invoked during genxref to parse and collect the definitions in a file.

$name

a string containing the LXR file name
$path

a string containing the OS file name

When files are stored in VCSes, $path is the name of a temporary file.
$fileid

an integer containing the internal DB id for the file/revision
$index

a reference to the index (DB) object
$config

a reference to the configuration objet

`referencefile ($name, $path, $fileid, $index, $config)`

Method referencefile is invoked during genxref to parse and collect the references in a file.

$name

a string containing the LXR file name
$path

a string containing the OS file name

When files are stored in VCSes, $path is the name of a temporary file.
$fileid

an integer containing the internal DB id for the file/revision
$index

a reference to the index (DB) object
$config

a reference to the configuration objet

`language ()`

Method language is usually a shorthand notation for $lang->{'language'}.