Inside File Access

Files module

Files module

This module defines the abstract access methods to the files of the source-tree, independent of the repository format.

`new ($config)`

new is Files object constructor. It dispatches to the specific constructor based on its first argument.

$config

a reference to the hash containing configuration parameters for this tree

`getdir ($pathname, $releaseid)`

getdir returns a directory content in an array.

$pathname

a string containing the path relative to 'sourceroot'
$releaseid

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

Function result is undef if directory does not exist in this version.

`getfile ($pathname, $releaseid)`

getfile returns a file content in a string.

$pathname

a string containing the path relative to 'sourceroot'
$releaseid

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

Function result is undef if file does not exist in this version.

`getannotations ($pathname, $releaseid)`

getannotations returns the annotations for the designated file.

$pathname

a string containing the path relative to 'sourceroot'
$releaseid

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

An annotation is whatever auxiliary line information kept in the repository. There is none in plain files. It is the revision number the line was entered in CVS. It is the commit-id in GIT.

Function result is an empty list if there is no annotation or annotation retrieval is barred by lxr.conf.

IMPORTANT NOTICE:

Starting with release 1.1, this method should only be used for internal needs of the derived classes because annotation editing has been drastically changed in script source.

The externally visible method is getnextannotation.

`getnextannotation ($pathname, $releaseid)`

getnextannotation returns the annotation for the next line in the designated file.

$pathname

a string containing the path relative to 'sourceroot'
$releaseid

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

An annotation is whatever auxiliary line information kept in the repository. There is none in plain files. It is the revision number the line was entered in CVS. It is the commit-id in GIT.

Function result is undefined if there is no more annotation or annotation retrieval is barred by lxr.conf.

`truncateannotation ($string, $len)`

truncateannotation truncate the annotation and returns the new length.

$string

a reference to a string containing the annotation
$len

an integer containing the desired length

The caller must leave room in his layout for an extra character to be inserted where truncation takes place. The returned string contains $len + 1 "characters" . Here, character means a display position on the screen but may need several bytes to be defined.

This default implementation truncates on left. It can be overriden in specific classes to truncate on right or use a different flag character or style.

`getauthor ($pathname, $releaseid, $annotation)`

getauthor returns the author of the designated revision.

$pathname

a string containing the path relative to 'sourceroot'
$releaseid

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

the annotation (see sub getannotations) whose author is looked for

Caveat:
- Since VCSs have different ways of identifying file versions, $releaseid cannot be used. A prior call to getannotations is needed to associate first the file and its version. Next the annotation for the current line is used to get the author.

`filerev ($pathname, $releaseid)`

filerev returns the latest revision for the file.

$pathname

a string containing the path relative to 'sourceroot'
$releaseid

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

For repositories that do not manage versions (i.e. plain files), return something making sense, but it does not need to be real.

`getfilehandle ($pathname, $releaseid, $withannot)`

getfilehandle returns a handle to the designated file for further access to the content.

getrawfilehandle is identical, except the file will be accessed in binary mode. By default, it is an alias for getfilehandle with third argument undefined. This method must be overridden if the specific object has requested the :utf8 layer to become a true "binary" access.

$pathname

a string containing the path relative to 'sourceroot'
$releaseid

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

"true" if annotations are also collected

Returning a file handle may require specific operations with the repository (check out, file extraction, …).

`getfilesize ($pathname, $releaseid)`

getfilesize returns the file size in bytes.

$pathname

a string containing the path relative to 'sourceroot'
$releaseid

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

For some repositories, this may require extracting the file.

`getfiletime ($pathname, $releaseid)`

getfiletime returns the file last modification time.

$pathname

a string containing the path relative to 'sourceroot'
$releaseid

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

For some repositories, this may require extracting the file.

`isdir ($pathname, $releaseid)`

isdir returns "true" if the designated path exists and is a directory.

$pathname

a string containing the path relative to 'sourceroot'
$releaseid

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

Since testing for a directory is rather time-consuming, arrange to "canonise" paths at the end of httpinit so that directories always end with /. Test will be done only once, eventually adding / suffix. Afterwards, all is needed is test for the trailing slash.

This method is used when the existence must be confirmed, such as when processing an include link since it is independent from the currently displayed file.

`isfile ($pathname, $releaseid)`

isfile returns "true" if the designated path exists and is a file.

$pathname

a string containing the path relative to 'sourceroot'
$releaseid

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

This method is used when the existence must be confirmed, such as when processing an include link since it is independent from the currently displayed file.

Note:

When the file is subsequently accessed, it is much simpler and efficient to use getfilehandle, since a handle will be required anyway.

`realfilename ($pathname, $releaseid)`

realfilename returns a real filename with the same content as the designated path (or undef).

$pathname

a string containing the path relative to 'sourceroot'
$releaseid

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

Extract content of the path from repository and stuff it into a temporary file whose name is returned.

Note:

Override this method if repository is made of plain files which can be accessed without the copy operation.

`releaserealfilename ($filename)`

releaserealfilename erases the file created by realfilename.

$filename

a string containing the filename

Although some care is exercised to check $filename was created by realfilename, this test is not fool-proof. Use this method ONLY against files returned by realfilename.

Caveat:

If you have overridden realfilename, be sure to override also this method to revert accurately what you have done, otherwise you risk destroying a valid source-tree file.

`_ignoredirs ($path, $node)`

_ignoredirs is an internal (as indicated by _ prefix) filter utility to exclude directories containing any partial path defined in configuration parameters 'ignoredirs' and 'filterdirs'.

$path

a string containing the LXR full path for the parent directory
$node

a string containing the last directory element

Only the last part is tested for 'ignoredirs' since the parent is supposed to have been scanned by a previous step of the recursive directory tree traversal. If a higher element matched one of the 'ignoredirs' strings, that path part was filtered out and no further part is presented to this function.

'filterdirs' operates on the full path, i.e. $path concatenated with $node.

Note:

The filter is to be called from getdir().

This usage choice leaves the possibility to override the filter through manually entering the path in the URL. Since it does not go through getdir(), the "forbidden" path subdirectory is transmitted unaltered to the source display script.

`_ignorefiles ($path, $node)`

_ignorefiles is an internal (as indicated by _ prefix) filter utility to exclude files containing patterns defined in configuration parameters 'ignorefiles' and 'filterfiles'.

$path

a string containing the LXR full path for the parent directory
$node

a string containing the file name

Only filename filtering is done for 'ignorefiles', i.e. the same filter is applied in every directory. Usually, it screens off "dot" files, editor backups, binaries, ...

'filterfiles' operates on the full path, i.e. concatenation of the parent directory $path and the filename $node.

Note:

The filter is to be called from getdir().

This usage choice leaves the possibility to override the filter through manually entering the path in the URL. Since it does not go through getdir(), the "forbidden" filename is transmitted unaltered to the source display script.