NaturalDocs::ImageReferenceTable

NaturalDocs::SourceDB::Extension

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

Summary

NaturalDocs::ImageReferenceTable	A NaturalDocs::SourceDB-based package that manages all the image references appearing in source files.
Information
Usage
Programming Notes	When working on this code, remember that there are three things it has to juggle.
Implementation	Managing image references is simpler than managing the references in NaturalDocs::SymbolTable.
Variables
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.
Functions
Register	Registers the package with NaturalDocs::SourceDB.
Load	Loads the data from ImageReferenceTable.nd.
Save	Saves the data to ImageReferenceTable.nd.
AddReference	Adds a new image reference.
OnDeletedDefinition	Called for each definition deleted by NaturalDocs::SourceDB.
GetReferenceTarget	Returns the image file the reference resolves to, or undef if none.
SetReferenceTarget	Determines the best target for the passed ImageReferenceString and sets it on the NaturalDocs::ImageReferenceTable::Reference object.

Information

Usage

NaturalDocs::Project and NaturalDocs::SourceDB must be initialized before this package can be used.
Call Register() before using.

Programming Notes

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

The information in NaturalDocs::SourceDB.
Image file references in NaturalDocs::Project.
Source file rebuilding on changes.

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]
[AString16: 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.

[AString16: definition file or undef] ...

Then comes a series of AString16s 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.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

sourceFile	The source FileName the reference appears in.
text	The 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.