A NaturalDocs::SourceDB-based package that manages all the image references appearing in source files.
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.
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.
The data file which stores all the image references from the last run of Natural Docs.
[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.
- AString16s were changed to UString16s.
- The file was added to Natural Docs.
|sub AddReference #(||FileName ||file,|
Adds a new image reference.
|sub OnDeletedDefinition #(||ImageReferenceString ||referenceString,|
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.
|sub GetReferenceTarget #(||FileName ||sourceFile,|
|string ||text||) => FileName|
Returns the image file the reference resolves to, or undef if none.
|sourceFile||The source FileName the reference appears in.|
|text||The reference text.|