Natural Docs
Version 1.2
Natural Docs
Packages
Objects
Languages
Output Formats
Extensions
Documentation
Indexes
Web Site

NaturalDocs:: ClassHierarchy

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.

Usage and Dependencies

Summary
NaturalDocs:: ClassHierarchy
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.
watchedFile
A NaturalDocs::ClassHierarchy::File object of the file being watched for changes.
watchedFileName
The file name of the watched file, if any.
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.
Modification Functions
AddClass
Adds a class to the hierarchy.
AddParent
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 an array of the passed class’ parents, or an empty array if none.
ChildrenOf
Returns an 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.
DeleteParent
Deletes a class’ parent definiton.

Variables

CLASS_HIERARCHY_FILEHANDLE

The file handle used with ClassHierarchy.nd.

classes

my %classes

A hash of all the classes.  The keys are the class names, and the values are NaturalDocs::ClassHierarchy::Classes.

files

my %files

A hash of the hierarchy information referenced by file.  The keys are the file names, and the values are NaturalDocs::ClassHierarchy::Files.

watchedFile

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.

watchedFileName

my $watchedFileName

The file name of the watched file, if any.  If there is no watched file, this will be undef.

Files

ClassHierarchy.nd

Stores the class hierarchy on disk.

Format

[BINARY_FORMAT]

The firs byte is the <BINARY_FORMAT> constant.

[app version]

Next is the binary application version it was generated with.  Manage with NaturalDocs::Version.

[AString16: class]

Next we begin a class segment.  These continue until the end of the file.  The class segment starts of with the class’ name.

[UInt32: number of files]
[AString16: 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.

[UInt8: number of parents]
( [AString16: parent] [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 name, 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 the end of the file.

Revisions

1.2

  • This file was introduced in 1.2.

File Functions

Load

sub Load

Loads the class hierarchy from disk.

Save

sub Save

Saves the class hierarchy to disk.

Purge

sub Purge

Purges the hierarchy of files that no longer have Natural Docs content.

Modification Functions

AddClass

sub AddClass #(file,
class)

Adds a class to the hierarchy.

Parameters

fileThe file the class was defined in.
classThe class name.

AddParent

sub AddParent #(file,
class,
parent,
dontRebuild)

Adds a class-parent relationship to the hierarchy.  Unless dontRebuild is set, this will put any files whose hierarchy output will change on the build list.  This also adds a reference in NaturalDocs::SymbolTable between the files so that if the summary or definition of one class changes, both files will be affected.

Parameters

fileThe file the class was defined in.
classThe class name.
parentThe parent class name.
dontRebuildIf this flag is set, files will not be rebuilt when changes occur.  This is mainly for use by Load(), you probably should never set it externally.

WatchFileForChanges

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.

Parameters

fileThe file name to watch.

AnalyzeChanges

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().

Information Functions

ParentsOf

sub ParentsOf #(class)

Returns an array of the passed class’ parents, or an empty array if none.

ChildrenOf

sub ChildrenOf #(class)

Returns an array of the passed class’ children, or an empty array if none.

Support Functions

DeleteFile

sub DeleteFile #(file)

Deletes a file and everything defined in it.

Parameters

fileThe file name.

DeleteClass

sub DeleteClass #(file,
class)

Deletes a class definition from a file.  Will also delete any parent definitions from this class and file.

Parameters

fileThe name of the file that defines the class.
classThe class name.

DeleteParent

sub DeleteParent #(file,
class,
parent)

Deletes a class’ parent definiton.

Parameters

fileThe name of the file that defines the class.
classThe name of the class.
parentThe name of the parent.
Copyright © 2003-2004 Greg Valure.  Generated by Natural Docs.
Stores the class hierarchy on disk.
my %classes
A hash of all the classes.
my %files
A hash of the hierarchy information referenced by file.
my $watchedFile
A NaturalDocs::ClassHierarchy::File object of the file being watched for changes.
An object that stores information about what hierarchy information is present in a file.
my $watchedFileName
The file name of the watched file, if any.
sub Load
Loads the class hierarchy from disk.
sub Save
Saves the class hierarchy to disk.
sub Purge
Purges the hierarchy of files that no longer have Natural Docs content.
sub AddClass #(file,
class)
Adds a class to the hierarchy.
sub AddParent #(file,
class,
parent,
dontRebuild)
Adds a class-parent relationship to the hierarchy.
sub WatchFileForChanges #(file)
Watches a file for changes, which can then be applied by AnalyzeChanges().
sub AnalyzeChanges
Checks the watched file for any changes that occured since the last time is was parsed, and updates the hierarchy as necessary.
sub ParentsOf #(class)
Returns an array of the passed class’ parents, or an empty array if none.
sub ChildrenOf #(class)
Returns an array of the passed class’ children, or an empty array if none.
sub DeleteFile #(file)
Deletes a file and everything defined in it.
sub DeleteClass #(file,
class)
Deletes a class definition from a file.
sub DeleteParent #(file,
class,
parent)
Deletes a class’ parent definiton.
A package to handle the command line and various other program settings.
A package that manages information about the files in the source tree, as well as the list of files that have to be parsed and built.
A package that handles all the gory details of managing symbols.
sub ParseForInformation #(file)
Parses the input file for information.
An object that stores information about a class in the hierarchy.
A package for handling version information.
sub RebuildFile #(file)
Adds the file to the list of files to build.