A package that handles all the gory details of managing symbols. It handles where they are defined, which files reference them, if any are undefined or duplicated, and loading and saving them to a file.
| NaturalDocs:: | A package that handles all the gory details of managing symbols. |
| Variables | |
| SYMBOLTABLE_FILEHANDLE | The file handle used with SymbolTable.nd. |
| symbols | A hash of all SymbolStrings. |
| references | A hash of all references in the project. |
| files | A hash of all the files that define symbols and references in the project. |
| watchedFile | A NaturalDocs::SymbolTable::File object of the file being watched for changes. |
| watchedFileName | The FileName of the watched file, if any. |
| watchedFileSymbolDefinitions | A hashref of the symbol definition information for all the SymbolStrings in the watched file. |
| indexes | A hash of generated symbol indexes. |
| indexChanges | A hash of all the indexes that have changed. |
| indexSectionsWithContent | A hash of which sections in an index have content. |
| rebuildIndexes | Whether all indexes should be rebuilt regardless of whether they have been changed. |
| Files | |
| SymbolTable.nd | The storage file for the symbol table. |
| IndexInfo.nd | The storage file for information about the indexes. |
| File Functions | |
| Load | Loads all data files from disk. |
| LoadSymbolTable | Loads SymbolTable.nd from disk. |
| LoadIndexInfo | Loads IndexInfo.nd from disk. |
| Purge | Purges the symbol table of all symbols and references from files that no longer have Natural Docs content. |
| Save | Saves all data files to disk. |
| SaveSymbolTable | Saves SymbolTable.nd to disk. |
| SaveIndexInfo | Saves IndexInfo.nd to disk. |
| Modification Functions | These functions should not be called after PurgeResolvingInfo(). |
| AddSymbol | Adds a symbol definition to the table, if it doesn’t already exist. |
| AddReference | Adds a reference to the table, if it doesn’t already exist. |
| WatchFileForChanges | Tracks a file to see if any symbols or references were changed or deleted in ways that would require other files to be rebuilt. |
| AnalyzeChanges | Handles any changes found when reparsing a file using WatchFileForChanges(). |
| DeleteReference | Deletes a reference from the table. |
| RebuildAllIndexes | When called, it makes sure all indexes are listed as changed by IndexChanged(), regardless of whether they actually did or not. |
| PurgeResolvingInfo | Purges unnecessary information from the symbol table after it is fully resolved. |
| PurgeIndexes | Clears all generated indexes. |
| Information Functions | These functions should not be called until the symbol table is fully resolved. |
| References | Returns what the passed reference information resolve to, if anything. |
| Lookup | Returns information on the passed SymbolString, if it exists. |
| Index | Returns a symbol index. |
| HasIndexes | Determines which indexes out of a list actually have content. |
| IndexChanged | Returns whether the specified index has changed. |
| IndexSectionsWithContent | Returns an arrayref of whether each section of the specified index has content. |
| Event Handlers | |
| OnIndexChange | Called whenever a change happens to a symbol that would cause an index to be regenerated. |
| OnInterpretationChange | Called whenever the current interpretation of a reference changes, meaning it switched from one symbol to another. |
| OnTargetSymbolChange | Called whenever the symbol that serves as the interpretation of a reference changes, but the reference still resolves to the same symbol. |
| Support Functions | |
| DeleteSymbol | Removes a symbol definition from the table. |
| GenerateInterpretations | Generates the list of interpretations for the passed reference. |
| GenerateRelativeInterpretations | Generates the list of relative interpretations for the passed reference and packages. |
| SingularInterpretationsOf | Generates singular interpretations of a SymbolString if it can be interpreted as a plural. |
| AddInterpretation | Adds an interpretation to an existing reference. |
| InterpretReference | Interprets the passed reference, matching it to the defined symbol with the highest score. |
| MakeIndex | Generates a symbol index. |
| SplitSymbolForIndex | Splits a SymbolString into its symbol and package portions for indexing. |
The file handle used with SymbolTable.nd.
my %symbols
A hash of all SymbolStrings. The keys are the SymbolStrings and the values are NaturalDocs::SymbolTable::Symbol objects.
Prior to PurgeResolvingInfo(), both defined symbols and symbols that are merely potential interpretations of references will be here. Afterwards, only defined symbols will be here.
my %references
A hash of all references in the project. The keys are ReferenceStrings and the values are NaturalDocs::SymbolTable::Reference objects.
Prior to PurgeResolvingInfo(), all possible interpretations will be stored for each reference. Afterwards, only the current interpretation will be.
my %files
A hash of all the files that define symbols and references in the project. The keys are the FileNames, and the values are NaturalDocs::SymbolTable::File objects.
After PurgeResolvingInfo(), this hash will be empty.
my $watchedFile
A NaturalDocs::SymbolTable::File object of the file being watched for changes. This is compared to the version in files to see if anything was changed since the last parse.
my $watchedFileName
The FileName of the watched file, if any. If there is no watched file, this will be undef.
my %watchedFileSymbolDefinitions
A hashref of the symbol definition information for all the SymbolStrings in the watched file. The keys are the symbol strings, and the values are NaturalDocs::SymbolTable::SymbolDefinition objects.
my %indexes
A hash of generated symbol indexes. The keys are TopicTypes and the values are sorted arrayrefs of NaturalDocs::SymbolTable::IndexElements, or undef if its empty.
my %indexChanges
A hash of all the indexes that have changed. The keys are the TopicTypes and the entries are undef if they have not changed, or 1 if they have. The key will not exist if the TopicType has not been checked.
my %indexSectionsWithContent
A hash of which sections in an index have content. The keys are the TopicTypes of each index, and the values are arrayrefs of bools where the first represents symbols, the second numbers, and the rest A-Z. If there is no information available for an index, it’s entry will not exist here.
The storage file for the symbol table.
[BINARY_FORMAT] [VersionInt: app version]
The file starts with the standard BINARY_FORMAT VersionInt header.
The first stage of the file is for symbol definitions, analogous to symbols.
[SymbolString: symbol or undef to end] ...
[UInt16: number of definitions]
[AString16: global definition file] [AString16: TopicType]
[AString16: prototype] [AString16: summary]
[AString16: definition file] ...
...These blocks continue until the SymbolString is undef. Only defined symbols will be included in this file, so number of definitions will never be zero. The first one is always the global definition. If a symbol does not have a prototype or summary, the UInt16 length of the string will be zero.
The second stage is for references, which is analogous to references. Only REFERENCE_TEXT references are stored in this file, and their Resolving Flags are implied so they aren’t stored either.
[ReferenceString (no type, resolving flags): reference or undef to end] [UInt8: number of definition files] [AString16: definition file] [AString16: definition file] ...
These blocks continue until the ReferenceString is undef. Since there can be multiple using SymbolStrings, those continue until the number of identifiers is zero. Note that all interpretations are rebuilt rather than stored.
The storage file for information about the indexes.
[Standard Header]
The standard binary file header.
[AString16: index topic name] [uint8: symbols have content (0 or 1)] [uint8: numbers have content (0 or 1)] [uint8: A has content] [uint8: B has content] ... ...
Every index that has information about it is stored with the topic type name first, then 28 uint8s that say whether that part of the index has content or not. The first is for symbols, the second is for numbers, and the rest are for A-Z. If an index’s state is unknown, it won’t appear in this file.
sub LoadSymbolTable
Loads SymbolTable.nd from disk.
sub LoadIndexInfo
Loads IndexInfo.nd from disk.
sub SaveSymbolTable
Saves SymbolTable.nd to disk.
sub SaveIndexInfo
Saves IndexInfo.nd to disk.
These functions should not be called after PurgeResolvingInfo().
sub AddSymbol #( symbol, file, type, prototype, summary )
Adds a symbol definition to the table, if it doesn’t already exist. If the definition changes or otherwise requires the files that reference it to be updated, the function will call NaturalDocs::Project->RebuildFile() to make sure that they are.
| symbol | The SymbolString. |
| file | The FileName where it’s defined. |
| type | The symbol’s TopicType. |
| prototype | The symbol’s prototype, if applicable. |
| summary | The symbol’s summary, if applicable. |
sub AddReference #( type, symbol, scope, using, file, resolvingFlags ) or (referenceString, file)
Adds a reference to the table, if it doesn’t already exist.
| type | The ReferenceType. |
| symbol | The reference SymbolString. |
| scope | The scope SymbolString it appears in. |
| using | An arrayref of scope SymbolStrings accessible to the reference via “using” statements, or undef if none. |
| file | The FileName where the reference appears. This is not required unless the type is REFERENCE_TEXT. |
| resolvingFlags | The Resolving Flags of the reference. They will be ignored if the type is REFERENCE_TEXT. |
| referenceString | The ReferenceString to add. |
| file | The FileName where the reference appears. This is not required unless the type is REFERENCE_TEXT. |
sub WatchFileForChanges #( file )
Tracks a file to see if any symbols or references were changed or deleted in ways that would require other files to be rebuilt. Assumes that after this function call, the entire file will be parsed again, and thus every symbol and reference will go through AddSymbol() and AddReference(). Afterwards, call AnalyzeChanges() to handle any differences.
| file | The FileName to watch. |
sub AnalyzeChanges
Handles any changes found when reparsing a file using WatchFileForChanges().
sub DeleteReference #( referenceString, file )
Deletes a reference from the table.
Be careful with this function, as deleting a reference means there are no more of them in the file at all. The tables do not keep track of how many times references appear in a file. In these cases you should instead call WatchFileForChanges(), reparse the file, thus readding all the references, and call AnalyzeChanges().
REFERENCE_TEXT references should always be managed with WatchFileForChanges() and AnalyzeChanges(). This function should only be used externally for other types of references.
| referenceString | The ReferenceString. |
| file | The FileName where the reference is. This is not required unless the type is REFERENCE_TEXT. |
sub RebuildAllIndexes
When called, it makes sure all indexes are listed as changed by IndexChanged(), regardless of whether they actually did or not.
This can be called at any time.
sub PurgeResolvingInfo
Purges unnecessary information from the symbol table after it is fully resolved. This will reduce the memory footprint for the build stage. After calling this function, you can only call the Information Functions and Save().
sub References #( type, symbol, scope, using, file, resolvingFlags ) or (referenceString, file)
Returns what the passed reference information resolve to, if anything. Note that this only works if the reference had been previously added to the table via AddReference() with the exact same parameters.
| type | The ReferenceType. |
| symbol | The reference SymbolString. |
| scope | The scope SymbolString the reference appears in, or undef if none. |
| using | An arrayref of scope SymbolStrings available to the reference via using statements. |
| file | The source FileName the reference appears in, or undef if none. |
| resolvingFlags | The Resolving Flags of the reference. Ignored if the type is REFERENCE_TEXT. |
| referenceString | The ReferenceString to resolve. |
| file | The source FileName the reference appears in, or undef if none. |
A NaturalDocs::SymbolTable::ReferenceTarget object, or undef if the reference doesn’t resolve to anything.
sub Lookup #( symbol, file )
Returns information on the passed SymbolString, if it exists. Note that the symbol must be fully resolved.
| symbol | The SymbolString. |
| file | The source FileName the reference appears in, or undef if none. |
A NaturalDocs::SymbolTable::ReferenceTarget object, or undef if the symbol isn’t defined.
sub Index #( type )
Returns a symbol index.
Indexes are generated on demand, but they are stored so subsequent calls for the same index will be fast. Call PurgeIndexes() to clear the generated indexes.
| type | The TopicType of symbol to limit the index to, or undef for none. |
An arrayref of sections. The first represents all the symbols, the second the numbers, and the rest A through Z. Each section is a sorted arrayref of NaturalDocs::SymbolTable::IndexElement objects. If a section has no content, it will be undef.
sub HasIndexes #( types )
Determines which indexes out of a list actually have content.
| types | An existence hashref of the TopicTypes to check for indexes. |
An existence hashref of all the specified indexes that have content. Will return an empty hashref if none.
sub IndexChanged #( TopicType type )
Returns whether the specified index has changed.
| type | The TopicType to limit the index to. |
sub OnIndexChange #( TopicType type )
Called whenever a change happens to a symbol that would cause an index to be regenerated.
| type | The TopicType of the symbol that caused the change. |
sub OnInterpretationChange #( referenceString )
Called whenever the current interpretation of a reference changes, meaning it switched from one symbol to another.
| referenceString | The ReferenceString whose current interpretation changed. |
sub OnTargetSymbolChange #( referenceString )
Called whenever the symbol that serves as the interpretation of a reference changes, but the reference still resolves to the same symbol. This would happen if the type, prototype, summary, or which file serves as global definition of the symbol changes.
| referenceString | The ReferenceString whose interpretation’s symbol changed. |
sub DeleteSymbol #( symbol, file )
Removes a symbol definition from the table. It will call OnInterpretationChange() for all references that have it as their current interpretation.
External code should not attempt to delete symbols using this function. Instead it should call <WatchFileFoChanges()>, reparse the file, and call AnalyzeChanges().
| symbol | The SymbolString. |
| file | The FileName where the definition is. |
sub GenerateInterpretations #( referenceString )
Generates the list of interpretations for the passed reference. Also creates potential symbols as necessary.
| referenceString | The ReferenceString to generate the interpretations of. |
sub GenerateRelativeInterpretations #( referenceString, symbol, singulars, package, score, dontUseFull )
Generates the list of relative interpretations for the passed reference and packages. Also creates potential symbols as necessary.
This function will not create global interpretations. It will create a local interpretations (symbol + all packages) unless you set dontUseFull.
| referenceString | The ReferenceString to generate interpretations for. |
| symbol | The SymbolString to generate interpretations of. |
| singulars | A reference to an array of singular SymbolStrings to also generate interpretations of. Set to an empty array if none. |
| package | The package SymbolString to use. May be undef. |
| score | The starting score to apply. |
| dontUseFull | Whether to not generate an interpretation including the full package identifier. If set, generated interpretations will start one level down. |
The next unused score. This is basically the passed score minus the number of interpretations created.
sub SingularInterpretationsOf #( symbol )
Generates singular interpretations of a SymbolString if it can be interpreted as a plural. Not all of them will be valid singular forms, but that doesn’t matter since it’s incredibly unlikely an invalid form would exist as a symbol. What matters is that the legimate singular is present on the list.
| symbol | The SymbolString. |
An array of potential singular interpretations as SymbolStrings, in no particular order. If the symbol can’t be interpreted as a plural, returns an empty array.
sub AddInterpretation #( referenceString, symbol, score )
Adds an interpretation to an existing reference. Creates potential symbols as necessary.
| referenceString | The ReferenceString to add the interpretation to. |
| symbol | The SymbolString the reference can be interpreted as. |
| score | The score of the interpretation. |
sub InterpretReference #( referenceString )
Interprets the passed reference, matching it to the defined symbol with the highest score. If the symbol is already interpreted, it will reinterpret it. If there are no matches, it will make it an undefined reference.
| referenceString | The ReferenceString to interpret. |
sub MakeIndex #( type )
Generates a symbol index.
| type | The TopicType to limit the index to. |
An arrayref of sections. The first represents all the symbols, the second the numbers, and the rest A through Z. Each section is a sorted arrayref of NaturalDocs::SymbolTable::IndexElement objects. If a section has no content, it will be undef.
sub SplitSymbolForIndex #( symbol, type )
Splits a SymbolString into its symbol and package portions for indexing.
| symbol | The SymbolString. |
| type | Its TopicType. |
The array ( symbol, package ), which are both SymbolStrings. If the symbol is global, package will be undef.
A hash of all SymbolStrings.
my %symbols
A hash of all references in the project.
my %references
A hash of all the files that define symbols and references in the project.
my %files
A NaturalDocs::SymbolTable::File object of the file being watched for changes.
my $watchedFile
The FileName of the watched file, if any.
my $watchedFileName
A hashref of the symbol definition information for all the SymbolStrings in the watched file.
my %watchedFileSymbolDefinitions
A hash of generated symbol indexes.
my %indexes
A hash of all the indexes that have changed.
my %indexChanges
A hash of which sections in an index have content.
my %indexSectionsWithContent
Whether all indexes should be rebuilt regardless of whether they have been changed.
my $rebuildIndexes
Loads all data files from disk.
sub Load
Loads SymbolTable.nd from disk.
sub LoadSymbolTable
Loads IndexInfo.nd from disk.
sub LoadIndexInfo
Purges the symbol table of all symbols and references from files that no longer have Natural Docs content.
sub Purge
Saves all data files to disk.
sub Save
Saves SymbolTable.nd to disk.
sub SaveSymbolTable
Saves IndexInfo.nd to disk.
sub SaveIndexInfo
Purges unnecessary information from the symbol table after it is fully resolved.
sub PurgeResolvingInfo
Adds a symbol definition to the table, if it doesn’t already exist.
sub AddSymbol #( symbol, file, type, prototype, summary )
Adds a reference to the table, if it doesn’t already exist.
sub AddReference #( type, symbol, scope, using, file, resolvingFlags ) or (referenceString, file)
Tracks a file to see if any symbols or references were changed or deleted in ways that would require other files to be rebuilt.
sub WatchFileForChanges #( file )
Handles any changes found when reparsing a file using WatchFileForChanges().
sub AnalyzeChanges
Deletes a reference from the table.
sub DeleteReference #( referenceString, file )
When called, it makes sure all indexes are listed as changed by IndexChanged(), regardless of whether they actually did or not.
sub RebuildAllIndexes
Returns whether the specified index has changed.
sub IndexChanged #( TopicType type )
Clears all generated indexes.
sub PurgeIndexes
Returns what the passed reference information resolve to, if anything.
sub References #( type, symbol, scope, using, file, resolvingFlags ) or (referenceString, file)
Returns information on the passed SymbolString, if it exists.
sub Lookup #( symbol, file )
Returns a symbol index.
sub Index #( type )
Determines which indexes out of a list actually have content.
sub HasIndexes #( types )
Returns an arrayref of whether each section of the specified index has content.
sub IndexSectionsWithContent #( TopicType type )
Called whenever a change happens to a symbol that would cause an index to be regenerated.
sub OnIndexChange #( TopicType type )
Called whenever the current interpretation of a reference changes, meaning it switched from one symbol to another.
sub OnInterpretationChange #( referenceString )
Called whenever the symbol that serves as the interpretation of a reference changes, but the reference still resolves to the same symbol.
sub OnTargetSymbolChange #( referenceString )
Removes a symbol definition from the table.
sub DeleteSymbol #( symbol, file )
Generates the list of interpretations for the passed reference.
sub GenerateInterpretations #( referenceString )
Generates the list of relative interpretations for the passed reference and packages.
sub GenerateRelativeInterpretations #( referenceString, symbol, singulars, package, score, dontUseFull )
Generates singular interpretations of a SymbolString if it can be interpreted as a plural.
sub SingularInterpretationsOf #( symbol )
Adds an interpretation to an existing reference.
sub AddInterpretation #( referenceString, symbol, score )
Interprets the passed reference, matching it to the defined symbol with the highest score.
sub InterpretReference #( referenceString )
Generates a symbol index.
sub MakeIndex #( type )
Splits a SymbolString into its symbol and package portions for indexing.
sub SplitSymbolForIndex #( symbol, type )
Parses the input file for information.
sub ParseForInformation #( file )
Adds the file to the list of files to build.
sub RebuildFile #( file )