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

All the Config and Data File Functions are available immediately, except for the status functions.
ReparseEverything() and RebuildEverything() are available immediately, because they may need to be called after LoadConfigFileInfo() but before LoadSourceFileInfo().
Prior to LoadConfigFileInfo(), NaturalDocs::Settings must be initialized.
After LoadConfigFileInfo(), the status Config and Data File Functions are available as well.
Prior to LoadSourceFileInfo(), NaturalDocs::Settings and NaturalDocs::Languages must be initialized.
After LoadSourceFileInfo(), the rest of the Source File Functions are available.

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.
File Handles
FH_FILEINFO	The file handle for the file information file, FileInfo.nd.
FH_CONFIGFILEINFO	The file handle for the config file information file, ConfigFileInfo.nd.
FH_IMAGEFILE	The file handle for determining the dimensions of image files.
Source File Variables
supportedFiles	A hash of all the supported files in the input directory.
filesToParse	An existence hash of all the FileNames that need to be parsed.
filesToBuild	An existence hash of all the FileNames that need to be built.
filesToPurge	An existence hash of the FileNames that had Natural Docs content last time, but now either don’t exist or no longer have content.
unbuiltFilesWithContent	An existence hash of all the FileNames that have Natural Docs content but are not part of filesToBuild.
reparseEverything	Whether all the source files need to be reparsed.
rebuildEverything	Whether all the source files need to be rebuilt.
mostUsedLanguage	The name of the most used language.
Configuration File Variables
mainConfigFile	A hash mapping all the main configuration file names without paths to their FileStatus.
userConfigFiles	A hash mapping all the user configuration file names without paths to their FileStatus.
Image File Variables
imageFileExtensions	An existence hash of all the file extensions for images.
imageFiles	A hash of all the image files in the project.
imageFilesToUpdate	An existence hash of all the image FileNames that need to be updated, either because they changed or they’re new to the project.
imageFilesToPurge	An existence hash of all the image FileNames that need to be purged, either because the files no longer exist or because they are no longer used.
insensitiveImageFiles	A hash that maps all lowercase image FileNames to their proper case as it would appear in imageFiles.
Files
FileInfo.nd	An index of the state of the files as of the last parse.
ConfigFileInfo.nd	An index of the state of the config files as of the last parse.
ImageFileInfo.nd	An index of the state of the image files as of the last parse.
File Functions
LoadSourceFileInfo	Loads the project file from disk and compares it against the files in the input directory.
SaveSourceFileInfo	Saves the source file info to disk.
LoadConfigFileInfo	Loads the config file info from disk.
SaveConfigFileInfo	Saves the config file info to disk.
LoadImageFileInfo	Loads the image file info from disk.
SaveImageFileInfo	Saves the image file info to disk.
MigrateOldFiles	If the project uses the old file names used prior to 1.14, it converts them to the new file names.
Config and Data File Functions
MainConfigFile	Returns the full path to the passed main configuration file.
MainConfigFileStatus	Returns the FileStatus of the passed main configuration file.
UserConfigFile	Returns the full path to the passed user configuration file.
UserConfigFileStatus	Returns the FileStatus of the passed user configuration file.
DataFile	Returns the full path to the passed data file.
Source File Functions
FilesToParse	Returns an existence hashref of the FileNames to parse.
FilesToBuild	Returns an existence hashref of the FileNames to build.
FilesToPurge	Returns an existence hashref of the FileNames that had content last time, but now either don’t anymore or were deleted.
RebuildFile	Adds the file to the list of files to build.
ReparseEverything	Adds all supported files to the list of files to parse.
RebuildEverything	Adds all supported files to the list of files to build.
UnbuiltFilesWithContent	Returns an existence hashref of the FileNames that have Natural Docs content but are not part of FilesToBuild().
FilesWithContent	Returns and existence hashref of the FileNames that have Natural Docs content.
HasContent	Returns whether the FileName contains Natural Docs content.
SetHasContent	Sets whether the FileName has Natural Docs content or not.
StatusOf	Returns the FileStatus of the passed FileName.
DefaultMenuTitleOf	Returns the default menu title of the FileName.
SetDefaultMenuTitle	Sets the FileName’s default menu title.
MostUsedLanguage	Returns the name of the most used language in the source trees.
Image File Functions
ImageFileExists	Returns whether the passed image file exists.
ImageFileDimensions	Returns the dimensions of the passed image file as the array ( width, height ).
ImageFileCapitalization	Returns the properly capitalized version of the passed image FileName.
AddImageFileReference	Adds a reference to the passed image FileName.
DeleteImageFileReference	Deletes a reference from the passed image FileName.
ImageFilesToUpdate	Returns an existence hashref of image FileNames that need to be updated.
ImageFilesToPurge	Returns an existence hashref of image FileNames that need to be updated.
Support Functions
GetAllSupportedFiles	Gets all the supported files in the passed directory and its subdirectories and puts them into supportedFiles.
DetermineImageDimensions	Attempts to determine the dimensions of the passed image and apply them to their object in imageFiles.

File Handles

FH_FILEINFO

The file handle for the file information file, FileInfo.nd.

FH_CONFIGFILEINFO

The file handle for the config file information file, ConfigFileInfo.nd.

FH_IMAGEFILE

The file handle for determining the dimensions of image files.

Source File Variables

supportedFiles

my %supportedFiles

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

filesToParse

my %filesToParse

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

filesToBuild

my %filesToBuild

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

filesToPurge

my %filesToPurge

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

unbuiltFilesWithContent

my %unbuiltFilesWithContent

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

reparseEverything

my $reparseEverything

Whether all the source files need to be reparsed.

rebuildEverything

my $rebuildEverything

Whether all the source files need to be rebuilt.

mostUsedLanguage

my $mostUsedLanguage

The name of the most used language. Doesn’t include text files.

Configuration File Variables

mainConfigFile

my %mainConfigFiles

A hash mapping all the main configuration file names without paths to their FileStatus. Prior to LoadConfigFileInfo(), it serves as an existence hashref of the file names.

userConfigFiles

my %userConfigFiles

A hash mapping all the user configuration file names without paths to their FileStatus. Prior to LoadConfigFileInfo(), it serves as an existence hashref of the file names.

Image File Variables

imageFileExtensions

my %imageFileExtensions

An existence hash of all the file extensions for images. Extensions are in all lowercase.

imageFiles

my %imageFiles

A hash of all the image files in the project. The keys are the FileNames and the values are NaturalDocs::Project::ImageFiles.

imageFilesToUpdate

my %imageFilesToUpdate

An existence hash of all the image FileNames that need to be updated, either because they changed or they’re new to the project.

imageFilesToPurge

my %imageFilesToPurge

An existence hash of all the image FileNames that need to be purged, either because the files no longer exist or because they are no longer used.

insensitiveImageFiles

my %insensitiveImageFiles

A hash that maps all lowercase image FileNames to their proper case as it would appear in imageFiles. Used for case insensitivity, obviously.

You can’t just use all lowercase in imageFiles because both Linux and HTTP are case sensitive, so the original case must be preserved. We also want to allow separate entries for files that differ based only on case, so it goes to imageFiles first where they can be distinguished and here only if there’s no match. Ties are broken by whichever is lower with cmp, because it has to resolve consistently on all runs of the program.

Files

FileInfo.nd

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 format is a text file.

[VersionInt: app version]

The beginning of the file is the VersionInt it was generated with.

[most used language name]

Next is the name of the most used language in the source tree. Does not include text files.

Each following line is

[file name] tab [last modification time] tab [has ND content (0 or 1)] tab [default menu title] \n

Revisions

1.3

The line following the VersionInt, which was previously the last modification time of Menu.txt, was changed to the name of the most used language.

1.16

File names are now absolute. Prior to 1.16, they were relative to the input directory since only one was allowed.

1.14

The file was renamed from NaturalDocs.files to FileInfo.nd and moved into the Data subdirectory.

0.95

The file version was changed to match the program version. Prior to 0.95, the version line was 1. Test for “1” instead of “1.0” to distinguish.

ConfigFileInfo.nd

An index of the state of the config files as of the last parse.

Format

[BINARY_FORMAT]
[VersionInt: app version]

First is the standard BINARY_FORMAT VersionInt header.

[UInt32: last modification time of menu]
[UInt32: last modification of main topics file]
[UInt32: last modification of user topics file]
[UInt32: last modification of main languages file]
[UInt32: last modification of user languages file]

Next are the last modification times of various configuration files as UInt32s in the standard Unix format.

Revisions

1.3

The file was added to Natural Docs. Previously the last modification of Menu.txt was stored in FileInfo.nd, and Topics.txt and Languages.txt didn’t exist.

ImageFileInfo.nd

An index of the state of the image files as of the last parse.

Format

[Standard Binary Header]

First is the standard binary file header as defined by NaturalDocs::BinaryFile.

[AString16: file name or undef]
[UInt32: last modification time]
[UInt8: was used]

This section is repeated until the file name is null. The last modification times are UInt32s in the standard Unix format.

Revisions

1.4

The file was added to Natural Docs.

File Functions

LoadSourceFileInfo

sub LoadSourceFileInfo

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

Will call NaturalDocs::Languages->OnMostUsedLanguageKnown() if MostUsedLanguage() changes.

Returns

Returns whether the project was changed in any way.

SaveSourceFileInfo

sub SaveSourceFileInfo

Saves the source file info to disk. Everything is saved in FileInfo.nd.

LoadConfigFileInfo

sub LoadConfigFileInfo

Loads the config file info from disk.

SaveConfigFileInfo

sub SaveConfigFileInfo

Saves the config file info to disk. You must save all other config files first, such as Menu.txt and Topics.txt.

LoadImageFileInfo

sub LoadImageFileInfo

Loads the image file info from disk.

SaveImageFileInfo

sub SaveImageFileInfo

Saves the image file info to disk.

MigrateOldFiles

sub MigrateOldFiles

If the project uses the old file names used prior to 1.14, it converts them to the new file names.

Config and Data File Functions

MainConfigFile

sub MainConfigFile #( string file )

Returns the full path to the passed main configuration file. Pass the file name only.

MainConfigFileStatus

sub MainConfigFileStatus #( string file )

Returns the FileStatus of the passed main configuration file. Pass the file name only.

UserConfigFile

sub UserConfigFile #( string file )

Returns the full path to the passed user configuration file. Pass the file name only.

UserConfigFileStatus

sub UserConfigFileStatus #( string file )

Returns the FileStatus of the passed user configuration file. Pass the file name only.

DataFile

sub DataFile #( string file )

Returns the full path to the passed data file. Pass the file name only.

Source File Functions

FilesToParse

sub FilesToParse

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

FilesToBuild

sub FilesToBuild

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

FilesToPurge

sub FilesToPurge

Returns an existence hashref of the FileNames 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.

RebuildFile

sub RebuildFile #( file )

Adds the file to the list of files to build. This function will automatically filter out files that don’t have Natural Docs content and files that are part of FilesToPurge(). If this gets called on a file and that file later gets Natural Docs content, it will be added.

Parameters

file	The FileName to build or rebuild.

ReparseEverything

sub ReparseEverything

Adds all supported files to the list of files to parse. This does not necessarily mean these files are going to be rebuilt.

RebuildEverything

sub RebuildEverything

Adds all supported files to the list of files to build. This does not necessarily mean these files are going to be reparsed.

UnbuiltFilesWithContent

sub UnbuiltFilesWithContent

Returns an existence hashref of the FileNames 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 FileNames that have Natural Docs content.

HasContent

sub HasContent #( file )

Returns whether the FileName contains Natural Docs content.

SetHasContent

sub SetHasContent #( file,
hasContent )

Sets whether the FileName has Natural Docs content or not.

StatusOf

sub StatusOf #( file )

Returns the FileStatus of the passed FileName.

DefaultMenuTitleOf

sub DefaultMenuTitleOf #( file )

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

SetDefaultMenuTitle

sub SetDefaultMenuTitle #( file,
menuTitle )

Sets the FileName’s default menu title.

MostUsedLanguage

sub MostUsedLanguage

Returns the name of the most used language in the source trees. Does not include text files.

Image File Functions

ImageFileExists

sub ImageFileExists #( FileName file ) => bool

Returns whether the passed image file exists.

ImageFileDimensions

sub ImageFileDimensions #( FileName file ) => (int, int)

Returns the dimensions of the passed image file as the array ( width, height ). Returns them both as undef if it cannot be determined.

ImageFileCapitalization

sub ImageFileCapitalization #( FileName file ) => FileName

Returns the properly capitalized version of the passed image FileName. Image file paths are treated as case insensitive regardless of whether the underlying operating system is or not, so we have to make sure the final version matches the capitalization of the actual file.

AddImageFileReference

sub AddImageFileReference #( FileName imageFile )

Adds a reference to the passed image FileName.

DeleteImageFileReference

sub DeleteImageFileReference #( FileName imageFile )

Deletes a reference from the passed image FileName.

ImageFilesToUpdate

sub ImageFilesToUpdate

Returns an existence hashref of image FileNames that need to be updated. Do not change.

ImageFilesToPurge

sub ImageFilesToPurge

Returns an existence hashref of image FileNames that need to be updated. Do not change.

Support Functions

GetAllSupportedFiles

sub GetAllSupportedFiles

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::SourceFile->LastModified(). Also sets mostUsedLanguage.

DetermineImageDimensions

sub DetermineImageDimensions #( FileName imageFile )

Attempts to determine the dimensions of the passed image and apply them to their object in imageFiles. Will set them to undef if they can’t be determined.