NaturalDocs:: Project

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.

Usage and Dependencies

Prior to initialization, NaturalDocs::Settings and NaturalDocs::Languages must be initialized and NaturalDocs::Menu’s event handlers must be available.
To initialize, call LoadAndDetectChanges(). All other functions will then be available.
All operations that can change project file information or the files themselves must be performed before saving the project back to disk. These include NaturalDocs::Parser::ParseForInformation() and NaturalDocs::Menu::Save().
To save the changes to disk, call Save().

Summary

NaturalDocs:: Project	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.
Variables
supportedFiles	A hash of all the supported files in the input directory.
filesToParse	An existence hash of all the files that need to be parsed.
filesToBuild	An existence hash of all the files that need to be built.
filesToPurge	An existence hash of files that had Natural Docs content last time, but now either don’t exist or no longer have content.
unbuiltFilesWithContent	An existence hashref of all the files that have Natural Docs content but are not part of filesToBuild.
Files
NaturalDocs. files	An index of the state of the files as of the last parse.
Action Functions
LoadAndDetectChanges	Loads the project file from disk and compares it against the files in the input directory.
Save	Saves the project file to disk.
RebuildFile	Adds the file to the list of files to build.
ReparseEverything	Adds all supported files to the list of files to parse.
Information Functions
ProjectFile	Returns the full path to the project’s data file.
SymbolTableFile	Returns the full path to the symbol table’s data file.
MenuFile	Returns the full path to the project’s menu file.
PreviousMenuStateFile	Returns the full path to the project’s previous menu state file.
MenuBackupFile	Returns the full path to the project’s menu backup file, which is used to save the original menu in some situations.
FilesToParse	Returns an existence hashref of the list of files to parse.
FilesToBuild	Returns an existence hashref of the list of files to build.
FilesToPurge	Returns an existence hashref of the list of files that had content last time, but now either don’t anymore or were deleted.
UnbuiltFilesWithContent	Returns an existence hashref of files that have Natural Docs content but are not part of FilesToBuild().
FilesWithContent	Returns and existence hashref of the files that have Natural Docs content.
HasContent	Returns whether the file contains Natural Docs content.
StatusOf	Returns the status of the passed file.
DefaultMenuTitleOf	Returns the default menu title of the file.
SetHasContent	Sets whether the file has Natural Docs content or not.
SetDefaultMenuTitle	Sets the file’s default menu title.
Support Functions
GetAllSupportedFiles	Gets all the supported files in the passed directory and its subdirectories and puts them into supportedFiles.

Variables

supportedFiles

my %supportedFiles

A hash of all the supported files in the input directory. The keys are the file names, and the values are NaturalDocs::Project::File objects.

filesToParse

my %filesToParse

An existence hash of all the files that need to be parsed.

filesToBuild

my %filesToBuild

An existence hash of all the files that need to be built.

filesToPurge

my %filesToPurge

An existence hash of files that had Natural Docs content last time, but now either don’t exist or no longer have content.

unbuiltFilesWithContent

my %unbuiltFilesWithContent

An existence hashref of all the files that have Natural Docs content but are not part of filesToBuild.

Files

NaturalDocs. files

An index of the state of the files as of the last parse. Used to determine if files were added, deleted, or changed.

Format

The first line is NaturalDocs::Settings::FileVersion().

The second line is the last modification time of NaturalDocs_Menu.txt.

Each following line is [file name]\t[last modification time]\t[has ND content boolean]\t[default menu title].

Action Functions

LoadAndDetectChanges

sub LoadAndDetectChanges

Loads the project file from disk and compares it against the files in the input directory. Project is loaded from NaturalDocs.files. New and changed files will be added to FilesToParse(), and if they have content, FilesToBuild().

Returns

Returns whether the project was changed in any way.

Save

sub Save

Saves the project file to disk. Everything is saved in NaturalDocs.files. NaturalDocs::Menu::Save() should be called prior to this function because its last modification time is saved here.

RebuildFile

sub RebuildFile #(file)

Adds the file to the list of files to build. Assumes the file contains Natural Docs content.

Parameters

file	The name of the file to build or rebuild.

ReparseEverything

sub ReparseEverything

Adds all supported files to the list of files to parse.

Information Functions

ProjectFile

sub ProjectFile

Returns the full path to the project’s data file.

SymbolTableFile

sub SymbolTableFile

Returns the full path to the symbol table’s data file.

MenuFile

sub MenuFile

Returns the full path to the project’s menu file.

PreviousMenuStateFile

sub PreviousMenuStateFile

Returns the full path to the project’s previous menu state file.

MenuBackupFile

sub MenuBackupFile

Returns the full path to the project’s menu backup file, which is used to save the original menu in some situations.

FilesToParse

sub FilesToParse

Returns an existence hashref of the list of files to parse. This is not a copy of the data, so don’t change it.

FilesToBuild

sub FilesToBuild

Returns an existence hashref of the list of files to build. This is not a copy of the data, so don’t change it.

FilesToPurge

sub FilesToPurge

Returns an existence hashref of the list of files that had content last time, but now either don’t anymore or were deleted. This is not a copy of the data, so don’t change it.

UnbuiltFilesWithContent

sub UnbuiltFilesWithContent

Returns an existence hashref of files that have Natural Docs content but are not part of FilesToBuild(). This is not a copy of the data so don’t change it.

FilesWithContent

sub FilesWithContent

Returns and existence hashref of the files that have Natural Docs content.

HasContent

sub HasContent #(file)

Returns whether the file contains Natural Docs content.

StatusOf

sub StatusOf #(file)

Returns the status of the passed file. Will be onen of the File Status Constants.

DefaultMenuTitleOf

sub DefaultMenuTitleOf #(file)

Returns the default menu title of the file. If one isn’t specified, it returns the file name.

Parameters

file	The name of the file.

SetHasContent

sub SetHasContent #(file, hasContent)

Sets whether the file has Natural Docs content or not.

Parameters

file	The file being modified.
hasContent	Whether the file now has Natural Docs content or not.

SetDefaultMenuTitle

sub SetDefaultMenuTitle #(file, menuTitle)

Sets the file’s default menu title.

Parameters

file	The file which is having its title changed.
menuTitle	The new menu title.

Support Functions

GetAllSupportedFiles

sub GetAllSupportedFiles #(directory)

Gets all the supported files in the passed directory and its subdirectories and puts them into supportedFiles. The only attribute that will be set is NaturalDocs::Project::File->LastModified().