NaturalDocs::Settings

A package to handle the command line and various other program settings.

Summary

NaturalDocs::Settings	A package to handle the command line and various other program settings.
Information
Usage and Dependencies
Internal Overview
Named Directories	Ever since Natural Docs introduced multiple input directories in 1.16, they’ve had to be named.
Removed Directories	Directories that were part of the previous run but aren’t anymore are still stored in the package.
Variables
PREVIOUS_SETTINGS_FILEHANDLE	The file handle used with PreviousSettings.nd.
inputDirectories	An array of input directories.
inputDirectoryNames	An array of the input directory names.
imageDirectories	An array of image directories.
imageDirectoryNames	An array of the image directory names.
relativeImageDirectories	An array of the relative paths for images.
excludedInputDirectories	An array of input directories to exclude.
removedInputDirectories	An array of input directories that were once in the command line but are no longer.
removedInputDirectoryNames	An array of the removed input directories’ names.
removedImageDirectories	An array of image directories that were once in the command line but are no longer.
removedImageDirectoryNames	An array of the removed image directories’ names.
projectDirectory	The project directory.
buildTargets	An array of NaturalDocs::Settings::BuildTargets.
documentedOnly	Whether undocumented code aspects should be included in the output.
tabLength	The number of spaces in tabs.
noAutoGroup	Whether auto-grouping is turned off.
onlyFileTitles	Whether source files should always use the file name as the title.
isQuiet	Whether the script should be run in quiet mode or not.
rebuildData	WHether most data files should be ignored and rebuilt.
styles	An array of style names to use, most important first.
charset	The character encoding of the source files, and thus the output.
Files
PreviousSettings.nd	Stores the previous command line settings.
Action Functions
Load	Loads and parses all settings from the command line and configuration files.
Save	Saves all settings in configuration files to disk.
GenerateDirectoryNames	Generates names for each of the input and image directories, which can later be retrieved with InputDirectoryNameOf() and ImageDirectoryNameOf().
Information Functions
InputDirectories	Returns an arrayref of input directories.
InputDirectoryNameOf	Returns the generated name of the passed input directory.
SplitFromInputDirectory	Takes an input file name and returns the array ( inputDirectory, relativePath ).
ImageDirectories	Returns an arrayref of image directories.
ImageDirectoryNameOf	Returns the generated name of the passed image or input directory.
SplitFromImageDirectory	Takes an input image file name and returns the array ( imageDirectory, relativePath ).
RelativeImageDirectories	Returns an arrayref of relative image directories.
ExcludedInputDirectories	Returns an arrayref of input directories to exclude.
BuildTargets	Returns an arrayref of NaturalDocs::Settings::BuildTargets.
OutputDirectoryOf	Returns the output directory of a builder object.
Styles	Returns an arrayref of the styles associated with the output.
ProjectDirectory	Returns the project directory.
ProjectDataDirectory	Returns the project data directory.
StyleDirectory	Returns the main style directory.
JavaScriptDirectory	Returns the main JavaScript directory.
ConfigDirectory	Returns the main configuration directory.
DocumentedOnly	Returns whether undocumented code aspects should be included in the output.
TabLength	Returns the number of spaces tabs should be expanded to.
NoAutoGroup	Returns whether auto-grouping is turned off.
OnlyFileTitles	Returns whether source files should always use the file name as the title.
IsQuiet	Returns whether the script should be run in quiet mode or not.
RebuildData	Returns whether all data files should be ignored and rebuilt.
CharSet	Returns the character set, or undef if none.
Constant Functions
AppVersion	Returns Natural Docs’ version number as an integer.
TextAppVersion	Returns Natural Docs’ version number as plain text.
AppURL	Returns a string of the project’s current web address.
Support Functions
ParseCommandLine	Parses and validates the command line.
PrintSyntax	Prints the syntax reference.
PrintOutputFormats	Prints all the possible output formats that can be specified with -o.
LoadAndComparePreviousSettings	Loads PreviousSettings.nd and compares the values there with those in the command line.
SavePreviousSettings	Saves the settings into PreviousSettings.nd.

Information

Usage and Dependencies

The Constant Functions can be called immediately.
Prior to initialization, NaturalDocs::Builder must have all its output packages registered.
To initialize, call Load(). All functions except InputDirectoryNameOf() will then be available.
GenerateDirectoryNames() must be called before InputDirectoryNameOf() will work. Currently it is called by NaturalDocs::Menu->LoadAndUpdate().

Internal Overview

Load() first parses the command line, gathering all the settings and checking for errors. All NaturalDocs::Builder packages must be registered before this is called because it needs their command line options. NaturalDocs::Project->ReparseEverything() and NaturalDocs::Project->RebuildEverything() are called right away if -r or -ro are used.
Output directories are not named at this point. See Named Directories.
The previous settings from the last time Natural Docs was run are loaded and compared to the current settings. NaturalDocs::Project->ReparseEverything() and NaturalDocs::Project->RebuildEverything() are called if there are any differences that warrant it.
It then waits for GenerateDirectoryNames() to be called by NaturalDocs::Menu. The reason for this is that the previous directory names are stored as hints in the menu file, for reasons explained in Named Directories. Once that happens all the unnamed directories have names generated for them so everything is named. The package is completely set up.
The input directories are stored in an array instead of a hash because the order they were declared in matters. If two people use multiple input directories on separate computers without sharing a menu file, they should at least get consistent directory names by declaring them in the same order.

Named Directories

Ever since Natural Docs introduced multiple input directories in 1.16, they’ve had to be named. Since they don’t necessarily extend from the same root anymore, they can’t share an output directory without the risk of file name conflicts. There was an early attempt at giving them actual names, but now they’re just numbered from 1.

Directory names aren’t generated right away. It waits for Menu.txt to load because that holds the obfuscated names from the last run. NaturalDocs::Menu then calls GenerateDirectoryNames() and passes those along as hints. GenerateDirectoryNames() then applies them to any matches and generates new ones for any remaining. This is done so that output page locations can remain consistent when built on multiple computers, so long as the menu file is shared. I tend to think the menu file is the most likely configuration file to be shared.

Removed Directories

Directories that were part of the previous run but aren’t anymore are still stored in the package. The primary reason, though there may be others, is file purging. If an input directory is removed, all the output files that were generated from anything in it need to be removed. To find out what the output file name was for a removed source file, it needs to be able to split it from it’s original input directory and know what that directory was named. If this didn’t happen those output files would be orphaned, as was the case prior to 1.32.

Variables

PREVIOUS_SETTINGS_FILEHANDLE

The file handle used with PreviousSettings.nd.

inputDirectories

my @inputDirectories

An array of input directories.

inputDirectoryNames

my @inputDirectoryNames

An array of the input directory names. Each name corresponds to the directory of the same index in inputDirectories.

imageDirectories

my @imageDirectories

An array of image directories.

imageDirectoryNames

my @imageDirectoryNames

An array of the image directory names. Each name corresponds to the directory of the same index in imageDirectories.

relativeImageDirectories

my @relativeImageDirectories

An array of the relative paths for images. The asterisks found in the command line are not present.

excludedInputDirectories

my @excludedInputDirectories

An array of input directories to exclude.

removedInputDirectories

my @removedInputDirectories

An array of input directories that were once in the command line but are no longer.

removedInputDirectoryNames

my @removedInputDirectoryNames

An array of the removed input directories’ names. Each name corresponds to the directory of the same index in removedInputDirectories.

removedImageDirectories

my @removedImageDirectories

An array of image directories that were once in the command line but are no longer.

removedImageDirectoryNames

my @removedImageDirectoryNames

An array of the removed image directories’ names. Each name corresponds to the directory of the same index in removedImageDirectories.

projectDirectory

my $projectDirectory

The project directory.

buildTargets

my @buildTargets

An array of NaturalDocs::Settings::BuildTargets.

documentedOnly

my $documentedOnly

Whether undocumented code aspects should be included in the output.

tabLength

my $tabLength

The number of spaces in tabs.

noAutoGroup

my $noAutoGroup

Whether auto-grouping is turned off.

onlyFileTitles

my $onlyFileTitles

Whether source files should always use the file name as the title.

isQuiet

my $isQuiet

Whether the script should be run in quiet mode or not.

rebuildData

my $rebuildData

WHether most data files should be ignored and rebuilt.

styles

my @styles

An array of style names to use, most important first.

charset

my $charset

The character encoding of the source files, and thus the output.

Files

PreviousSettings.nd

Stores the previous command line settings.

Format

[BINARY_FORMAT]
[VersionInt: app version]

The file starts with the standard BINARY_FORMAT VersionInt header.

[UInt8: tab length]
[UInt8: documented only (0 or 1)]
[UInt8: no auto-group (0 or 1)]
[UInt8: only file titles (0 or 1)]
[AString16: charset]

[UInt8: number of input directories]
[AString16: input directory] [AString16: input directory name] ...

A count of input directories, then that number of directory/name pairs.

[UInt8: number of output targets]
[AString16: output directory] [AString16: output format command line option] ...

A count of output targets, then that number of directory/format pairs.

Revisions

1.4

Added only file titles.

1.33

Added charset.

1.3

Removed headers-only, which was a 0/1 UInt8 after tab length.
Change auto-group level (1 = no, 2 = yes, 3 = full only) to no auto-group (0 or 1).

1.22

Added auto-group level.

1.2

File was added to the project. Prior to 1.2, it didn’t exist.

Action Functions

Load

sub Load

Loads and parses all settings from the command line and configuration files. Will exit if the options are invalid or the syntax reference was requested.

Save

sub Save

Saves all settings in configuration files to disk.

GenerateDirectoryNames

sub GenerateDirectoryNames #( hashref inputHints,
hashref imageHints )

Generates names for each of the input and image directories, which can later be retrieved with InputDirectoryNameOf() and ImageDirectoryNameOf().

Parameters

inputHints	A hashref of suggested input directory names, where the keys are the directories and the values are the names. These take precedence over anything generated. You should include names for directories that are no longer in the command line. This parameter may be undef.
imageHints	Same as inputHints, only for the image directories.

Information Functions

InputDirectories

sub InputDirectories

Returns an arrayref of input directories. Do not change.

This will not return any removed input directories.

InputDirectoryNameOf

sub InputDirectoryNameOf #( directory )

Returns the generated name of the passed input directory. GenerateDirectoryNames() must be called once before this function is available.

If a name for a removed input directory is available, it will be returned as well.

SplitFromInputDirectory

sub SplitFromInputDirectory #( file )

Takes an input file name and returns the array ( inputDirectory, relativePath ).

If the file cannot be split from an input directory, it will try to do it with the removed input directories.

ImageDirectories

sub ImageDirectories

Returns an arrayref of image directories. Do not change.

This will not return any removed image directories.

ImageDirectoryNameOf

sub ImageDirectoryNameOf #( directory )

Returns the generated name of the passed image or input directory. GenerateDirectoryNames() must be called once before this function is available.

If a name for a removed input or image directory is available, it will be returned as well.

SplitFromImageDirectory

sub SplitFromImageDirectory #( file )

Takes an input image file name and returns the array ( imageDirectory, relativePath ).

If the file cannot be split from an image directory, it will try to do it with the removed image directories.

RelativeImageDirectories

sub RelativeImageDirectories

Returns an arrayref of relative image directories. Do not change.

ExcludedInputDirectories

sub ExcludedInputDirectories

Returns an arrayref of input directories to exclude. Do not change.

BuildTargets

sub BuildTargets

Returns an arrayref of NaturalDocs::Settings::BuildTargets. Do not change.

OutputDirectoryOf

sub OutputDirectoryOf #( object )

Returns the output directory of a builder object.

Parameters

object

The builder object, whose class is derived from NaturalDocs::Builder::Base.

Returns

The builder directory, or undef if the object wasn’t found..

Styles

sub Styles

Returns an arrayref of the styles associated with the output.

ProjectDirectory

sub ProjectDirectory

Returns the project directory.

ProjectDataDirectory

sub ProjectDataDirectory

Returns the project data directory.

StyleDirectory

sub StyleDirectory

Returns the main style directory.

JavaScriptDirectory

sub JavaScriptDirectory

Returns the main JavaScript directory.

ConfigDirectory

sub ConfigDirectory

Returns the main configuration directory.

DocumentedOnly

sub DocumentedOnly

Returns whether undocumented code aspects should be included in the output.

TabLength

sub TabLength

Returns the number of spaces tabs should be expanded to.

NoAutoGroup

sub NoAutoGroup

Returns whether auto-grouping is turned off.

OnlyFileTitles

sub OnlyFileTitles

Returns whether source files should always use the file name as the title.

IsQuiet

sub IsQuiet

Returns whether the script should be run in quiet mode or not.

RebuildData

sub RebuildData

Returns whether all data files should be ignored and rebuilt.

CharSet

sub CharSet

Returns the character set, or undef if none.

Constant Functions

AppVersion

sub AppVersion

Returns Natural Docs’ version number as an integer. Use TextAppVersion() to get a printable version.

TextAppVersion

sub TextAppVersion

Returns Natural Docs’ version number as plain text.

AppURL

sub AppURL

Returns a string of the project’s current web address.

Support Functions

ParseCommandLine

sub ParseCommandLine

Parses and validates the command line. Will cause the script to exit if the options ask for the syntax reference or are invalid.

PrintSyntax

sub PrintSyntax

Prints the syntax reference.

PrintOutputFormats

sub PrintOutputFormats #( prefix )

Prints all the possible output formats that can be specified with -o. Each one will be placed on its own line.

Parameters

prefix

Characters to prefix each one with, such as for indentation.

LoadAndComparePreviousSettings

sub LoadAndComparePreviousSettings

Loads PreviousSettings.nd and compares the values there with those in the command line. If differences require it, sets rebuildData and/or <rebuildOutput>.

SavePreviousSettings

sub SavePreviousSettings

Saves the settings into PreviousSettings.nd.