A package that handles all the gory details of managing the class hierarchy. It handles the hierarchy itself, which files define them, rebuilding the files that are affected by changes, and loading and saving them to a file.
| NaturalDocs:: | A package that handles all the gory details of managing the class hierarchy. |
| Variables | |
| CLASS_HIERARCHY_FILEHANDLE | The file handle used with ClassHierarchy.nd. |
| classes | A hash of all the classes. |
| files | A hash of the hierarchy information referenced by file. |
| parentReferences | A hash of all the parent reference strings and what they resolve to. |
| watchedFile | A NaturalDocs::ClassHierarchy::File object of the file being watched for changes. |
| watchedFileName | The FileName of the watched file, if any. |
| dontRebuildFiles | A bool to set if you don’t want changes in the hierarchy to cause files to be rebuilt. |
| Files | |
| ClassHierarchy.nd | Stores the class hierarchy on disk. |
| File Functions | |
| Load | Loads the class hierarchy from disk. |
| Save | Saves the class hierarchy to disk. |
| Purge | Purges the hierarchy of files that no longer have Natural Docs content. |
| Interface Functions | |
| OnInterpretationChange | Called by NaturalDocs::SymbolTable whenever a class hierarchy reference’s intepretation changes, meaning it switched from one symbol to another. |
| OnTargetSymbolChange | Called by NaturalDocs::SymbolTable whenever a class hierarchy reference’s target symbol changes, but the reference still resolves to the same symbol. |
| Modification Functions | |
| AddClass | Adds a class to the hierarchy. |
| AddParentReference | Adds a class-parent relationship to the hierarchy. |
| WatchFileForChanges | Watches a file for changes, which can then be applied by AnalyzeChanges(). |
| AnalyzeChanges | Checks the watched file for any changes that occured since the last time is was parsed, and updates the hierarchy as necessary. |
| Information Functions | |
| ParentsOf | Returns a SymbolString array of the passed class’ parents, or an empty array if none. |
| ChildrenOf | Returns a SymbolString array of the passed class’ children, or an empty array if none. |
| Support Functions | |
| DeleteFile | Deletes a file and everything defined in it. |
| DeleteClass | Deletes a class definition from a file. |
| DeleteParentReference | Deletes a class’ parent reference and returns whether it resulted in the loss of a parent class. |
| ClassReferenceOf | Returns the REFERENCE_CH_CLASS ReferenceString of the passed class SymbolString. |
| RebuildFilesFor | Calls NaturalDocs::Project->RebuildFile() for every file defining the passed class, its parents, and/or its children. |
The file handle used with ClassHierarchy.nd.
my %classes
A hash of all the classes. The keys are the class SymbolStrings and the values are NaturalDocs::ClassHierarchy::Classes.
my %files
A hash of the hierarchy information referenced by file. The keys are the FileNames, and the values are NaturalDocs::ClassHierarchy::Files.
my %parentReferences
A hash of all the parent reference strings and what they resolve to. The keys are the ReferenceStrings and the values are the class SymbolStrings that they resolve to.
my $watchedFile
A NaturalDocs::ClassHierarchy::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.
Stores the class hierarchy on disk.
[BINARY_FORMAT] [VersionInt: app version]
The standard BINARY_FORMAT and VersionInt header.
[SymbolString: class or undef to end]
Next we begin a class segment with its SymbolString. These continue until the end of the file. Only defined classes are included.
[UInt32: number of files] [UString16: file] [UString16: file] ...
Next there is the number of files that define that class. It’s a UInt32, which seems like overkill, but I could imagine every file in a huge C++ project being under the same namespace, and thus contributing its own definition. It’s theoretically possible.
Following the number is that many file names. You must remember the index of each file, as they will be important later. Indexes start at one because zero has a special meaning.
[UInt8: number of parents] ( [ReferenceString (no type): parent] [UInt32: file index] [UInt32: file index] ... [UInt32: 0] ) ...
Next there is the number of parents defined for this class. For each one, we define a parent segment, which consists of its ReferenceString, and then a zero-terminated string of indexes of the files that define that parent as part of that class. The indexes start at one, and are into the list of files we saw previously.
Note that we do store class segments for classes without parents, but not for undefined classes.
This concludes a class segment. These segments continue until an undef SymbolString.
sub OnInterpretationChange #( reference )
Called by NaturalDocs::SymbolTable whenever a class hierarchy reference’s intepretation changes, meaning it switched from one symbol to another.
| reference | The ReferenceString whose current interpretation changed. |
sub OnTargetSymbolChange #( reference )
Called by NaturalDocs::SymbolTable whenever a class hierarchy reference’s target symbol changes, but the reference still resolves to the same symbol.
| reference | The ReferenceString that was affected by the change. |
sub AddClass #( file, class, languageName )
Adds a class to the hierarchy.
| file | The FileName the class was defined in. |
| class | The class SymbolString. |
| languageName | The name of the language this applies to. |
The file parameter must be defined when using this function externally. It may be undef for internal use only.
sub AddParentReference #( file, class, symbol, scope, using, resolvingFlags ) or (file, class, reference)
Adds a class-parent relationship to the hierarchy. The classes will be created if they don’t already exist.
| file | The FileName the reference was defined in. |
| class | The class SymbolString. |
| symbol | The parent class SymbolString. |
| scope | The package SymbolString that the reference appeared in. |
| using | An arrayref of package SymbolStrings that the reference has access to via “using” statements. |
| resolvingFlags | Any Resolving Flags to be used when resolving the reference. |
| file | The FileName the reference was defined in. |
| class | The class SymbolString. |
| reference | The parent ReferenceString. |
sub WatchFileForChanges #( file )
Watches a file for changes, which can then be applied by AnalyzeChanges(). Definitions are not deleted via a DeleteClass() function. Instead, a file is watched for changes, reparsed, and then a comparison is made to look for definitions that disappeared and any other relevant changes.
| file | The FileName to watch. |
sub AnalyzeChanges
Checks the watched file for any changes that occured since the last time is was parsed, and updates the hierarchy as necessary. Also sends any files that are affected to NaturalDocs::Project->RebuildFile().
sub ParentsOf #( class )
Returns a SymbolString array of the passed class’ parents, or an empty array if none. Note that not all of them may be defined.
sub ChildrenOf #( class )
Returns a SymbolString array of the passed class’ children, or an empty array if none. Note that not all of them may be defined.
sub DeleteClass #( file, class )
Deletes a class definition from a file. Will also delete any parent references from this class and file. Will rebuild any file affected unless dontRebuildFiles is set.
| file | The FileName that defines the class. |
| class | The class SymbolString. |
sub DeleteParentReference #( file, class, reference )
Deletes a class’ parent reference and returns whether it resulted in the loss of a parent class. Will rebuild any file affected unless dontRebuildFiles is set.
| file | The FileName that defines the reference. |
| class | The class SymbolString. |
| reference | The parent ReferenceString. |
If the class lost a parent as a result of this, it will return its SymbolString. It will return undef otherwise.
sub ClassReferenceOf #( class, languageName )
Returns the REFERENCE_CH_CLASS ReferenceString of the passed class SymbolString.
sub RebuildFilesFor #( class, rebuildParents, rebuildSelf, rebuildChildren )
Calls NaturalDocs::Project->RebuildFile() for every file defining the passed class, its parents, and/or its children. Returns without doing anything if dontRebuildFiles is set.
| class | The class SymbolString. |
| rebuildParents | Whether to rebuild the class’ parents. |
| rebuildSelf | Whether to rebuild the class. |
| rebuildChildren | Whether to rebuild the class’ children. |
A hash of all the classes.
my %classes
A hash of the hierarchy information referenced by file.
my %files
A hash of all the parent reference strings and what they resolve to.
my %parentReferences
A NaturalDocs::ClassHierarchy::File object of the file being watched for changes.
my $watchedFile
The FileName of the watched file, if any.
my $watchedFileName
A bool to set if you don’t want changes in the hierarchy to cause files to be rebuilt.
my $dontRebuildFiles
Loads the class hierarchy from disk.
sub Load
Saves the class hierarchy to disk.
sub Save
Purges the hierarchy of files that no longer have Natural Docs content.
sub Purge
Called by NaturalDocs::SymbolTable whenever a class hierarchy reference’s intepretation changes, meaning it switched from one symbol to another.
sub OnInterpretationChange #( reference )
Called by NaturalDocs::SymbolTable whenever a class hierarchy reference’s target symbol changes, but the reference still resolves to the same symbol.
sub OnTargetSymbolChange #( reference )
Adds a class to the hierarchy.
sub AddClass #( file, class, languageName )
Adds a class-parent relationship to the hierarchy.
sub AddParentReference #( file, class, symbol, scope, using, resolvingFlags ) or (file, class, reference)
Watches a file for changes, which can then be applied by AnalyzeChanges().
sub WatchFileForChanges #( file )
Checks the watched file for any changes that occured since the last time is was parsed, and updates the hierarchy as necessary.
sub AnalyzeChanges
Returns a SymbolString array of the passed class’ parents, or an empty array if none.
sub ParentsOf #( class )
Returns a SymbolString array of the passed class’ children, or an empty array if none.
sub ChildrenOf #( class )
Deletes a file and everything defined in it.
sub DeleteFile #( file )
Deletes a class definition from a file.
sub DeleteClass #( file, class )
Deletes a class’ parent reference and returns whether it resulted in the loss of a parent class.
sub DeleteParentReference #( file, class, reference )
Returns the REFERENCE_CH_CLASS ReferenceString of the passed class SymbolString.
sub ClassReferenceOf #( class, languageName )
Calls NaturalDocs::Project->RebuildFile() for every file defining the passed class, its parents, and/or its children.
sub RebuildFilesFor #( class, rebuildParents, rebuildSelf, rebuildChildren )
Adds the file to the list of files to build.
sub RebuildFile #( file )
Parses the input file for information.
sub ParseForInformation #( file )