NaturalDocs::Settings

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

Summary
NaturalDocs::SettingsA package to handle the command line and various other program settings.
Information
Usage and Dependencies
Internal Overview
Named DirectoriesEver since Natural Docs introduced multiple input directories in 1.16, they’ve had to be named.
Removed DirectoriesDirectories that were part of the previous run but aren’t anymore are still stored in the package.
Variables
PREVIOUS_SETTINGS_FILEHANDLEThe file handle used with PreviousSettings.nd.
inputDirectoriesAn array of input directories.
inputDirectoryNamesAn array of the input directory names.
imageDirectoriesAn array of image directories.
imageDirectoryNamesAn array of the image directory names.
relativeImageDirectoriesAn array of the relative paths for images.
excludedInputDirectoriesAn array of input directories to exclude.
removedInputDirectoriesAn array of input directories that were once in the command line but are no longer.
removedInputDirectoryNamesAn array of the removed input directories’ names.
removedImageDirectoriesAn array of image directories that were once in the command line but are no longer.
removedImageDirectoryNamesAn array of the removed image directories’ names.
projectDirectoryThe project directory.
buildTargetsAn array of NaturalDocs::Settings::BuildTargets.
documentedOnlyWhether undocumented code aspects should be included in the output.
tabLengthThe number of spaces in tabs.
noAutoGroupWhether auto-grouping is turned off.
onlyFileTitlesWhether source files should always use the file name as the title.
isQuietWhether the script should be run in quiet mode or not.
rebuildDataWHether most data files should be ignored and rebuilt.
stylesAn array of style names to use, most important first.
highlightCodeWhether syntax highlighting should be applied to code tags.
highlightAnonymousWhether syntax highlighting should be applied to anonymous code tags.
Files
PreviousSettings.ndStores the previous command line settings.
Action Functions
LoadLoads and parses all settings from the command line and configuration files.
SaveSaves all settings in configuration files to disk.
GenerateDirectoryNamesGenerates names for each of the input and image directories, which can later be retrieved with InputDirectoryNameOf() and ImageDirectoryNameOf().
Information Functions
InputDirectoriesReturns an arrayref of input directories.
InputDirectoryNameOfReturns the generated name of the passed input directory.
SplitFromInputDirectoryTakes an input file name and returns the array ( inputDirectory, relativePath ).
ImageDirectoriesReturns an arrayref of image directories.
ImageDirectoryNameOfReturns the generated name of the passed image or input directory.
SplitFromImageDirectoryTakes an input image file name and returns the array ( imageDirectory, relativePath ).
RelativeImageDirectoriesReturns an arrayref of relative image directories.
ExcludedInputDirectoriesReturns an arrayref of input directories to exclude.
BuildTargetsReturns an arrayref of NaturalDocs::Settings::BuildTargets.
OutputDirectoryOfReturns the output directory of a builder object.
StylesReturns an arrayref of the styles associated with the output.
ProjectDirectoryReturns the project directory.
ProjectDataDirectoryReturns the project data directory.
StyleDirectoryReturns the main style directory.
JavaScriptDirectoryReturns the main JavaScript directory.
ConfigDirectoryReturns the main configuration directory.
DocumentedOnlyReturns whether undocumented code aspects should be included in the output.
TabLengthReturns the number of spaces tabs should be expanded to.
NoAutoGroupReturns whether auto-grouping is turned off.
OnlyFileTitlesReturns whether source files should always use the file name as the title.
IsQuietReturns whether the script should be run in quiet mode or not.
RebuildDataReturns whether all data files should be ignored and rebuilt.
HighlightCodeReturns whether to apply syntax highlighting (start code) sections.
HighlightAnonymousReturns whether to apply syntax highlighting to anonymous code sections designated with :, >, or |.
Constant Functions
AppVersionReturns Natural Docs’ version number as an integer.
TextAppVersionReturns Natural Docs’ version number as plain text.
AppURLReturns a string of the project’s current web address.
Support Functions
ParseCommandLineParses and validates the command line.
PrintSyntaxPrints the syntax reference.
PrintOutputFormatsPrints all the possible output formats that can be specified with -o.
LoadAndComparePreviousSettingsLoads PreviousSettings.nd and compares the values there with those in the command line.
SavePreviousSettingsSaves the settings into PreviousSettings.nd.

Information

Usage and Dependencies

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.

highlightCode

my $highlightCode

Whether syntax highlighting should be applied to code tags.

highlightAnonymous

my $highlightAnonymous

Whether syntax highlighting should be applied to anonymous code tags.

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)]
[UInt8: highlight code (0 or 1)]
[UInt8: highlight anonymous (0 or 1)]

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

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

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

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

Revisions

1.52

  • Changed AString16s to UString16s.

1.51

  • Removed charset.

1.5

  • Added highlight code and highlight anonymous.

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

inputHintsA 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.
imageHintsSame 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

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

HighlightCode

sub HighlightCode

Returns whether to apply syntax highlighting (start code) sections.

HighlightAnonymous

sub HighlightAnonymous

Returns whether to apply syntax highlighting to anonymous code sections designated with :, >, or |.

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

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

Stores the previous command line settings.
my @inputDirectories
An array of input directories.
my @inputDirectoryNames
An array of the input directory names.
my @imageDirectories
An array of image directories.
my @imageDirectoryNames
An array of the image directory names.
my @relativeImageDirectories
An array of the relative paths for images.
my @excludedInputDirectories
An array of input directories to exclude.
my @removedInputDirectories
An array of input directories that were once in the command line but are no longer.
my @removedInputDirectoryNames
An array of the removed input directories’ names.
my @removedImageDirectories
An array of image directories that were once in the command line but are no longer.
my @removedImageDirectoryNames
An array of the removed image directories’ names.
my $projectDirectory
The project directory.
my @buildTargets
An array of NaturalDocs::Settings::BuildTargets.
A class that stores information about a build target.
my $documentedOnly
Whether undocumented code aspects should be included in the output.
my $tabLength
The number of spaces in tabs.
my $noAutoGroup
Whether auto-grouping is turned off.
my $onlyFileTitles
Whether source files should always use the file name as the title.
my $isQuiet
Whether the script should be run in quiet mode or not.
my $rebuildData
WHether most data files should be ignored and rebuilt.
my @styles
An array of style names to use, most important first.
my $highlightCode
Whether syntax highlighting should be applied to code tags.
my $highlightAnonymous
Whether syntax highlighting should be applied to anonymous code tags.
sub Load
Loads and parses all settings from the command line and configuration files.
sub Save
Saves all settings in configuration files to disk.
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().
sub InputDirectoryNameOf #(directory)
Returns the generated name of the passed input directory.
sub ImageDirectoryNameOf #(directory)
Returns the generated name of the passed image or input directory.
sub InputDirectories
Returns an arrayref of input directories.
sub SplitFromInputDirectory #(file)
Takes an input file name and returns the array ( inputDirectory, relativePath ).
sub ImageDirectories
Returns an arrayref of image directories.
sub SplitFromImageDirectory #(file)
Takes an input image file name and returns the array ( imageDirectory, relativePath ).
sub RelativeImageDirectories
Returns an arrayref of relative image directories.
sub ExcludedInputDirectories
Returns an arrayref of input directories to exclude.
sub BuildTargets
Returns an arrayref of NaturalDocs::Settings::BuildTargets.
sub OutputDirectoryOf #(object)
Returns the output directory of a builder object.
sub Styles
Returns an arrayref of the styles associated with the output.
sub ProjectDirectory
Returns the project directory.
sub ProjectDataDirectory
Returns the project data directory.
sub StyleDirectory
Returns the main style directory.
sub JavaScriptDirectory
Returns the main JavaScript directory.
sub ConfigDirectory
Returns the main configuration directory.
sub DocumentedOnly
Returns whether undocumented code aspects should be included in the output.
sub TabLength
Returns the number of spaces tabs should be expanded to.
sub NoAutoGroup
Returns whether auto-grouping is turned off.
sub OnlyFileTitles
Returns whether source files should always use the file name as the title.
sub IsQuiet
Returns whether the script should be run in quiet mode or not.
sub RebuildData
Returns whether all data files should be ignored and rebuilt.
sub HighlightCode
Returns whether to apply syntax highlighting (start code) sections.
sub HighlightAnonymous
Returns whether to apply syntax highlighting to anonymous code sections designated with :, >, or |.
sub AppVersion
Returns Natural Docs’ version number as an integer.
sub TextAppVersion
Returns Natural Docs’ version number as plain text.
sub AppURL
Returns a string of the project’s current web address.
sub ParseCommandLine
Parses and validates the command line.
sub PrintSyntax
Prints the syntax reference.
sub PrintOutputFormats #(prefix)
Prints all the possible output formats that can be specified with -o.
sub LoadAndComparePreviousSettings
Loads PreviousSettings.nd and compares the values there with those in the command line.
sub SavePreviousSettings
Saves the settings into PreviousSettings.nd.
A package that takes parsed source file and builds the output for it.
sub LoadAndUpdate
Loads the menu file from disk and updates it.
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.
Ever since Natural Docs introduced multiple input directories in 1.16, they’ve had to be named.
A package handling the menu’s contents and state.
The file used to generate the menu.
An 8-bit constant that’s used as the first byte of binary data files.
A comparable integer representing a version number.
A base class for all Builder output formats.
Close