Natural Docs Version 0.9 |
NaturalDocs:: SymbolTableA 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. Usage and Dependencies
Summary
symbols
A hash of all symbols, both those that are defined and those which are simply potential interpretations of references. The keys are the symbol strings, generated by by MakeSymbolString(), and the values are NaturalDocs::SymbolTable::Symbol objects. Note that because references can have many interpretations, there will probably be more symbols here that aren’t defined than that are. references
A hash of all references in the project. The keys are the reference strings, generated by by MakeReferenceString(), and the values are NaturalDocs::SymbolTable::Reference objects. files
A hash of all the files that define symbols and references in the project. The keys are the file names, and the values are NaturalDocs::SymbolTable::File objects. 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. watchedFileSymbolDefinitions
A hashref of the symbol definition information for all the symbols in the watched file. The keys are the symbol strings, and the values are NaturalDocs::SymbolTable::SymbolDefinition objects. indexes;A hash of generated symbol indexes. The keys are Topic Types or *, and the values are sorted arrayrefs of <NaturalDocs::SymbolTable::IndexElements>. A key of * means the index is not limited to a topic type. indexChanges
An existence hash of all the indexes that have changed. The keys are the Topic Types. Unlike <indexes>, there is no * entry. Simply check if there are any defined keys instead. NaturalDocs. symThe storage file for the symbol table. FormatThe first line of the file is NaturalDocs::Settings::FileVersion(). [file format version] The first stage of the file is for symbol definitions, analogous to symbols. For this stage, each entry continues until it reaches a blank line. The first line is the symbol string, and each subsequent line is a tab separated list of the definition, type, and prototype. The first file on this list will be the one that has the global definition. Undefined symbols are not included here. [symbol string] [global definition file] tab [symbol type] tab [prototype] [definition file] tab [symbol type] tab [prototype] blank line The two stages are separated by a blank line. That works out to meaning a symbol definition followed by two blank lines. blank line The second stage is for references, which is analogous to references. For this stage, each is a pair of lines. The first line is the reference string, and the second is a tab separated list of the files that define it. The interpretations will be regenerated. [reference string] [definition file] tab [definition file] tab [definition file] ... AddSymbol
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. Parameters
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. 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. Parameters
AnalyzeChanges
Handles any changes found when reparsing a file using WatchFileForChanges(). 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(). Defines
Returns the symbol the passed class and name define. This is not exactly the same as what was passed. Certain elements may be taken out to make pattern matching more tolerant, so you must use this function when defining symbols in output files to match the tolerance of this package. For example, say there’s a symbol definition A-space-space-B. SymbolTable condenses whitespace, so the symbol can also be referenced by A-space-B, A-tab-B, A-space-space-space-B, etc. In effect, A-space-space-B really defines the symbol A-space-B. If you encoded the anchor as A-space-space-B in the output file, when References() returns A-space-B, they won’t match. If you run it through this function first, they always will. Note that this is only required when encoding symbol definitions in output files. Every other SymbolTable function handles this automatically, so you don’t need to run symbols through this to call AddSymbol() etc. Parameters
ReturnsThe defined symbol as the array ( class, symbol ). If class was undef in the parameters, it will be undef here too. References
Returns what the passed symbol and scope reference, if anything. Note that this only works if the reference had been previously added to the table via AddReference(). Parameters
ReturnsA NaturalDocs::SymbolTable::ReferenceTarget object, or undef if the reference doesn’t resolve to anything. Index
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. Parameters
ReturnsA sorted arrayref of NaturalDocs::SymbolTable::IndexElement objects. IndexChanged
Returns whether the specified index has changed. Parameters
MakeSymbolString
Encodes the symbol information as a string. The format of the string should be treated as opaque and the string should not be used for anything other than direct comparison, file I/O, and hash keys. The only characteristic of the encoding you can depend on is that it will not contain line breaks, which should make using them in text files easier. Parameters
ReturnsThe encoded symbol string. MakeReferenceString
Encodes the reference information as a string. The format of the string should be treated as opaque and the string should not be used for anything other than direct comparison, file I/O, and hash keys. The only characteristic of the encoding you can depend on is that it will not contain line breaks, which should make using them in text files easier. Parameters
ReturnsThe encoded reference string. DeleteSymbol
Removes a symbol definition from the table. If any files reference it, the function will call NaturalDocs::Project::RebuildFile() for them. External code should not attempt to delete symbols using this function. Instead it should call <WatchFileFoChanges()>, reparse the file, and call AnalyzeChanges(). Parameters
DeleteReference
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. External code should not attempt to delete references using this function. Instead it should call <WatchFileFoChanges()>, reparse the file, and call AnalyzeChanges(). Parameters
AddInterpretation
Adds an interpretation to an existing reference. Creates potential symbols as necessary. Parameters
InterpretReference
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. Parameters
MakeIndex
Generates a symbol index. Parameters
ReturnsA sorted arrayref of NaturalDocs::SymbolTable::IndexElement objects. |