NaturalDocs::ImageReferenceTable

NaturalDocs::ImageReferenceTable

A NaturalDocs::SourceDB-based package that manages all the image references appearing in source files.

Summary
NaturalDocs::ImageReferenceTableA NaturalDocs::SourceDB-based package that manages all the image references appearing in source files.
Information
Usage
Programming NotesWhen working on this code, remember that there are three things it has to juggle.
ImplementationManaging image references is simpler than managing the references in NaturalDocs::SymbolTable.
Variables
extensionIDThe ExtensionID granted by NaturalDocs::SourceDB.
Files
ImageReferenceTable.ndThe data file which stores all the image references from the last run of Natural Docs.
Functions
RegisterRegisters the package with NaturalDocs::SourceDB.
LoadLoads the data from ImageReferenceTable.nd.
SaveSaves the data to ImageReferenceTable.nd.
AddReferenceAdds a new image reference.
OnDeletedDefinitionCalled for each definition deleted by NaturalDocs::SourceDB.
GetReferenceTargetReturns the image file the reference resolves to, or undef if none.
SetReferenceTargetDetermines the best target for the passed ImageReferenceString and sets it on the NaturalDocs::ImageReferenceTable::Reference object.

Information

Usage

Programming Notes

When working on this code, remember that there are three things it has to juggle.

Managing the actual image files will be handled between NaturalDocs::Project and the NaturalDocs::Builder sub-packages.

Implementation

Managing image references is simpler than managing the references in NaturalDocs::SymbolTable.  In SymbolTable, you have to worry about reference targets popping into and out of existence.  A link may go to a file that hasn’t been reparsed yet and the target may no longer exist.  We have to deal with that when we know it, which may be after the reference’s file was parsed.  Also, a new definition may appear that serves as a better interpretation of a link than its current target, and again we may only know that after the reference’s file has been parsed already.  So we have to deal with scores and potential symbols and each symbol knowing exactly what links to it and so forth.

Not so with image references.  All possible targets (all possible image files) are known by NaturalDocs::Project early on and will remain consistent throughout execution.  So because of that, we can get away with only storing reference counts with each image and determining exactly where a reference points to as we find them.

Reference counts are stored with the image file information in NaturalDocs::Project.  However, it is not loaded and saved to disk by it.  Rather, it is regenerated by this package when it loads ImageReferenceTable.nd.  NaturalDocs::Project only stores the last modification time (so it can add files to the build list if they’ve changed) and whether it had any references at all on the last run (so it knows whether it should care if they’ve changed.)  ImageReferenceTable.nd stores each reference’s target, width, and height.  Whether their interpretations have changed is dealt with in the Load() function, again since the list of targets (image files) is constant.

The package is based on NaturalDocs::SourceDB, so read it’s documentation for more information on how it works.

Variables

extensionID

my $extensionID

The ExtensionID granted by NaturalDocs::SourceDB.

Files

ImageReferenceTable.nd

The data file which stores all the image references from the last run of Natural Docs.

Format

[Standard Binary Header]

It starts with the standard binary header from NaturalDocs::BinaryFile.

[Image Reference String or undef]
[UString16: target file]
[UInt16: target width or 0]
[UInt16: target height or 0]

For each ImageReferenceString, it’s target, width, and height are stored.  The target is needed so we can tell if it changed from the last run, and the dimensions are needed because if the target hasn’t changed but the file’s dimensions have, the source files need to be rebuilt.

ImageReferenceStrings are encoded by NaturalDocs::ImageReferenceTable::String.

[UString16: definition file or undef] ...

Then comes a series of UString16s for all the files that define the reference until it hits an undef.

This whole series is repeated for each ImageReferenceString until it hits an undef.

Revisions

1.52

  • AString16s were changed to UString16s.

1.4

  • The file was added to Natural Docs.

Functions

Register

sub Register

Registers the package with NaturalDocs::SourceDB.

Load

sub Load # => bool

Loads the data from ImageReferenceTable.nd.  Returns whether it was successful.

Save

sub Save

Saves the data to ImageReferenceTable.nd.

AddReference

sub AddReference #(FileName file,
string referenceText)

Adds a new image reference.

OnDeletedDefinition

sub OnDeletedDefinition #(ImageReferenceString referenceString,
FileName file,
bool wasLastDefinition)

Called for each definition deleted by NaturalDocs::SourceDB.  This is called after the definition has been deleted from the database, so don’t expect to be able to read it.

GetReferenceTarget

sub GetReferenceTarget #(FileName sourceFile,
string text) => FileName

Returns the image file the reference resolves to, or undef if none.

Parameters

sourceFileThe source FileName the reference appears in.
textThe reference text.

SetReferenceTarget

sub SetReferenceTarget #(ImageReferenceString referenceString) => FileName

Determines the best target for the passed ImageReferenceString and sets it on the NaturalDocs::ImageReferenceTable::Reference object.  Returns the new target FileName.  Does not add any source files to the bulid list.

A base package for all SourceDB extensions.
SourceDB is an experimental package meant to unify the tracking of various elements in the source code.
A package that handles all the gory details of managing symbols.
my $extensionID
The ExtensionID granted by NaturalDocs::SourceDB.
A unique identifier for each NaturalDocs::SourceDB extension as given out by RegisterExtension().
sub Register
Registers the package with NaturalDocs::SourceDB.
sub Load # => bool
Loads the data from ImageReferenceTable.nd.
The data file which stores all the image references from the last run of Natural Docs.
sub Save
Saves the data to ImageReferenceTable.nd.
sub AddReference #(FileName file,
string referenceText)
Adds a new image reference.
sub OnDeletedDefinition #(ImageReferenceString referenceString,
FileName file,
bool wasLastDefinition)
Called for each definition deleted by NaturalDocs::SourceDB.
sub GetReferenceTarget #(FileName sourceFile,
string text) => FileName
Returns the image file the reference resolves to, or undef if none.
sub SetReferenceTarget #(ImageReferenceString referenceString) => FileName
Determines the best target for the passed ImageReferenceString and sets it on the NaturalDocs::ImageReferenceTable::Reference object.
A string representing a unique image reference.
A class for references being tracked in NaturalDocs::SourceDB.
A package that manages information about the files in the source tree, as well as the list of files that have to be parsed and built.
A package that takes parsed source file and builds the output for it.
A package to manage Natural Docs’ binary data files.
A package for creating and managing ImageReferenceStrings.
A string representing the absolute, platform-dependent path to a file.
Close