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

Summary
NaturalDocs::ProjectA 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_FILEINFOThe file handle for the file information file, FileInfo.nd.
FH_CONFIGFILEINFOThe file handle for the config file information file, ConfigFileInfo.nd.
FH_IMAGEFILEThe file handle for determining the dimensions of image files.
Source File Variables
supportedFilesA hash of all the supported files in the input directory.
filesToParseAn existence hash of all the FileNames that need to be parsed.
filesToBuildAn existence hash of all the FileNames that need to be built.
filesToPurgeAn existence hash of the FileNames that had Natural Docs content last time, but now either don’t exist or no longer have content.
unbuiltFilesWithContentAn existence hash of all the FileNames that have Natural Docs content but are not part of filesToBuild.
reparseEverythingWhether all the source files need to be reparsed.
rebuildEverythingWhether all the source files need to be rebuilt.
mostUsedLanguageThe name of the most used language.
Configuration File Variables
mainConfigFileA hash mapping all the main configuration file names without paths to their FileStatus.
userConfigFilesA hash mapping all the user configuration file names without paths to their FileStatus.
Image File Variables
imageFileExtensionsAn existence hash of all the file extensions for images.
imageFilesA hash of all the image files in the project.
imageFilesToUpdateAn existence hash of all the image FileNames that need to be updated, either because they changed or they’re new to the project.
imageFilesToPurgeAn 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.
insensitiveImageFilesA hash that maps all lowercase image FileNames to their proper case as it would appear in imageFiles.
Files
FileInfo.ndAn index of the state of the files as of the last parse.
ConfigFileInfo.ndAn index of the state of the config files as of the last parse.
ImageFileInfo.ndAn index of the state of the image files as of the last parse.
File Functions
LoadSourceFileInfoLoads the project file from disk and compares it against the files in the input directory.
SaveSourceFileInfoSaves the source file info to disk.
LoadConfigFileInfoLoads the config file info from disk.
SaveConfigFileInfoSaves the config file info to disk.
LoadImageFileInfoLoads the image file info from disk.
SaveImageFileInfoSaves the image file info to disk.
MigrateOldFilesIf 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
MainConfigFileReturns the full path to the passed main configuration file.
MainConfigFileStatusReturns the FileStatus of the passed main configuration file.
UserConfigFileReturns the full path to the passed user configuration file.
UserConfigFileStatusReturns the FileStatus of the passed user configuration file.
DataFileReturns the full path to the passed data file.
Source File Functions
FilesToParseReturns an existence hashref of the FileNames to parse.
FilesToBuildReturns an existence hashref of the FileNames to build.
FilesToPurgeReturns an existence hashref of the FileNames that had content last time, but now either don’t anymore or were deleted.
RebuildFileAdds the file to the list of files to build.
ReparseEverythingAdds all supported files to the list of files to parse.
RebuildEverythingAdds all supported files to the list of files to build.
UnbuiltFilesWithContentReturns an existence hashref of the FileNames that have Natural Docs content but are not part of FilesToBuild().
FilesWithContentReturns and existence hashref of the FileNames that have Natural Docs content.
HasContentReturns whether the FileName contains Natural Docs content.
SetHasContentSets whether the FileName has Natural Docs content or not.
StatusOfReturns the FileStatus of the passed FileName.
DefaultMenuTitleOfReturns the default menu title of the FileName.
SetDefaultMenuTitleSets the FileName’s default menu title.
MostUsedLanguageReturns the name of the most used language in the source trees.
Image File Functions
ImageFileExistsReturns whether the passed image file exists.
ImageFileDimensionsReturns the dimensions of the passed image file as the array ( width, height ).
ImageFileCapitalizationReturns the properly capitalized version of the passed image FileName.
AddImageFileReferenceAdds a reference to the passed image FileName.
DeleteImageFileReferenceDeletes a reference from the passed image FileName.
ImageFilesToUpdateReturns an existence hashref of image FileNames that need to be updated.
ImageFilesToPurgeReturns an existence hashref of image FileNames that need to be updated.
Support Functions
GetAllSupportedFilesGets all the supported files in the passed directory and its subdirectories and puts them into supportedFiles.
DetermineImageDimensionsAttempts 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

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.

[UString16: 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.52

  • AString16s were changed to UString16s.

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

fileThe 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.

An index of the state of the files as of the last parse.
An index of the state of the config files as of the last parse.
my %supportedFiles
A hash of all the supported files in the input directory.
my %filesToParse
An existence hash of all the FileNames that need to be parsed.
A string representing the absolute, platform-dependent path to a file.
my %filesToBuild
An existence hash of all the FileNames that need to be built.
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.
my %unbuiltFilesWithContent
An existence hash of all the FileNames that have Natural Docs content but are not part of filesToBuild.
my $reparseEverything
Whether all the source files need to be reparsed.
my $rebuildEverything
Whether all the source files need to be rebuilt.
my $mostUsedLanguage
The name of the most used language.
my %mainConfigFiles
A hash mapping all the main configuration file names without paths to their FileStatus.
What happened to a file since Natural Docs’ last execution.
my %userConfigFiles
A hash mapping all the user configuration file names without paths to their FileStatus.
my %imageFileExtensions
An existence hash of all the file extensions for images.
my %imageFiles
A hash of all the image files in the project.
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.
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.
my %insensitiveImageFiles
A hash that maps all lowercase image FileNames to their proper case as it would appear in imageFiles.
sub LoadSourceFileInfo
Loads the project file from disk and compares it against the files in the input directory.
sub SaveSourceFileInfo
Saves the source file info to disk.
sub LoadConfigFileInfo
Loads the config file info from disk.
sub SaveConfigFileInfo
Saves the config file info to disk.
sub LoadImageFileInfo
Loads the image file info from disk.
sub SaveImageFileInfo
Saves the image file info to disk.
sub MigrateOldFiles
If the project uses the old file names used prior to 1.14, it converts them to the new file names.
sub MainConfigFile #(string file)
Returns the full path to the passed main configuration file.
sub MainConfigFileStatus #(string file)
Returns the FileStatus of the passed main configuration file.
sub UserConfigFile #(string file)
Returns the full path to the passed user configuration file.
sub UserConfigFileStatus #(string file)
Returns the FileStatus of the passed user configuration file.
sub DataFile #(string file)
Returns the full path to the passed data file.
sub FilesToParse
Returns an existence hashref of the FileNames to parse.
sub FilesToBuild
Returns an existence hashref of the FileNames to build.
sub FilesToPurge
Returns an existence hashref of the FileNames that had content last time, but now either don’t anymore or were deleted.
sub RebuildFile #(file)
Adds the file to the list of files to build.
sub ReparseEverything
Adds all supported files to the list of files to parse.
sub RebuildEverything
Adds all supported files to the list of files to build.
sub UnbuiltFilesWithContent
Returns an existence hashref of the FileNames that have Natural Docs content but are not part of FilesToBuild().
sub FilesWithContent
Returns and existence hashref of the FileNames that have Natural Docs content.
sub HasContent #(file)
Returns whether the FileName contains Natural Docs content.
sub SetHasContent #(file,
hasContent)
Sets whether the FileName has Natural Docs content or not.
sub StatusOf #(file)
Returns the FileStatus of the passed FileName.
sub DefaultMenuTitleOf #(file)
Returns the default menu title of the FileName.
sub SetDefaultMenuTitle #(file,
menuTitle)
Sets the FileName’s default menu title.
sub MostUsedLanguage
Returns the name of the most used language in the source trees.
sub ImageFileExists #(FileName file) => bool
Returns whether the passed image file exists.
sub ImageFileDimensions #(FileName file) => (int, int)
Returns the dimensions of the passed image file as the array ( width, height ).
sub ImageFileCapitalization #(FileName file) => FileName
Returns the properly capitalized version of the passed image FileName.
sub AddImageFileReference #(FileName imageFile)
Adds a reference to the passed image FileName.
sub DeleteImageFileReference #(FileName imageFile)
Deletes a reference from the passed image FileName.
sub ImageFilesToUpdate
Returns an existence hashref of image FileNames that need to be updated.
sub ImageFilesToPurge
Returns an existence hashref of image FileNames that need to be updated.
sub GetAllSupportedFiles
Gets all the supported files in the passed directory and its subdirectories and puts them into supportedFiles.
sub DetermineImageDimensions #(FileName imageFile)
Attempts to determine the dimensions of the passed image and apply them to their object in imageFiles.
A package to handle the command line and various other program settings.
A package to manage all the programming languages Natural Docs supports.
A simple information class about project files.
A simple information class about project image files.
A comparable integer representing a version number.
The file used to generate the menu.
An 8-bit constant that’s used as the first byte of binary data files.
The configuration file that defines or overrides the topic definitions for Natural Docs.
The configuration file that defines or overrides the language definitions for Natural Docs.
A package to manage Natural Docs’ binary data files.
sub OnMostUsedLanguageKnown
Called when the most used language is known.
sub LastModified
Returns the integer timestamp of when the file was last modified.
Close