Natural Docs
Version 1.2
Natural Docs
Packages
Objects
Languages
Output Formats
Extensions
Documentation
Indexes
Web Site

NaturalDocs:: Settings

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

Usage and Dependencies

Summary
NaturalDocs:: Settings
A package to handle the command line and various other program settings.
Variables
SETTINGSFILEHANDLE
The file handle used with Settings.txt.
PREVIOUS_SETTINGS_FILEHANDLE
The file handle used with PreviousSettings.nd.
inputDirectories
An array of input directories.
inputDirectoryNames
An array of the input directory 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.
rebuildData
Whether the script should rebuild all data files from scratch.
rebuildOutput
Whether the script should rebuild all output files from scratch.
isQuiet
Whether the script should be run in quiet mode or not.
headersOnly
Whether only the header files in C/C++ should be used.
defaultStyle
The style to be used if an output format doesn’t have its own style specified.
Files
Settings.txt
The file that stores the Natural Docs build targets.
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 directories, which can later be retrieved with InputDirectoryNameOf().
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 ).
BuildTargets
Returns an arrayref of NaturalDocs::Settings::BuildTargets.
OutputDirectoryOf
Returns the output directory of a builder object.
OutputStyleOf
Returns the style associated with a builder object.
ProjectDirectory
Returns the project directory.
ProjectDataDirectory
Returns the project data directory.
StyleDirectory
Returns the main style directory.
DocumentedOnly
Returns whether undocumented code aspects should be included in the output.
TabLength
Returns the number of spaces tabs should be expanded to.
RebuildData
Returns whether the script should rebuild all data files from scratch.
RebuildOutput
Returns whether the script should rebuild all output files from scratch.
IsQuiet
Returns whether the script should be run in quiet mode or not.
HeadersOnly
Returns whether to only check the header files in C/C++.
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.
LoadSettingsFile
Loads and parses Settings.txt.
SaveSettingsFile
Saves Settings.txt to disk.
LoadAndComparePreviousSettings
Loads PreviousSettings.nd and compares the values there with those in the command line.
SavePreviousSettings
Saves the settings into PreviousSettings.nd.

Variables

SETTINGSFILEHANDLE

The file handle used with Settings.txt.

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.

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.

rebuildData

my $rebuildData

Whether the script should rebuild all data files from scratch.

rebuildOutput

my $rebuildOutput

Whether the script should rebuild all output files from scratch.

isQuiet

my $isQuiet

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

headersOnly

my $headersOnly

Whether only the header files in C/C++ should be used.

defaultStyle

my $defaultStyle

The style to be used if an output format doesn’t have its own style specified.

Files

Settings.txt

The file that stores the Natural Docs build targets.

Format

The file is plain text.  Blank lines can appear anywhere and are ignored.  Tags and their content must be completely contained on one line.

# [comment]

The file supports single-line comments via #.  They can appear alone on a line or after content.

Format: [version]
TabLength: [length]
Style: [style]

The file format version, tab length, and default style are specified as above.  Each can only be specified once, with subsequent ones being ignored.  Notice that the tags correspond to the long forms of the command line options.

Source: [directory]
Input: [directory]

The input directory is specified as above.  As in the command line, either “Source” or “Input” can be used.

[Extension Option]: [opton]

Options for extensions can be specified as well.  The long form is used as the tag.

Option: [HeadersOnly], [Quiet], [Extension Option]

Options that don’t have parameters can be specified in an Option line.  The commas are not required.

Output: [name]

Specifies an output target with a user defined name.  The name is what will be referenced from the command line, and the name “All” is reserved.

The options below can only be specified after an output tag.  Everything that follows an output tag is part of that target’s options until the next output tag.

Format: [format]

The output format of the target.

Directory: [directory]
Location: [directory]
Folder: [directory]

The output directory of the target.  All are synonyms.

Style: [style]

The style of the output target.  This overrides the default and is optional.

PreviousSettings.nd

Stores the previous command line settings.

Format

[BINARY_FORMAT]

The file is binary, so the first byte is the <BINARY_FORMAT> token.

[app version]

Immediately after this is the application version it was generated with.  Manage with the binary functions in NaturalDocs::Version.

[UInt8: tab length]
[UInt8: headers only (0 or 1)]
[UInt8: documented only (0 or 1)]

[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.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 #(hints)

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

Parameters

hintsA hashref of suggested names, where the keys are the directories and the values are the names.  These take precedence over anything generated.  Directories here that aren’t on the list of input directories are ignored.  This parameter may be undef.

Information Functions

InputDirectories

sub InputDirectories

Returns an arrayref of input directories.  Do not change.

InputDirectoryNameOf

sub InputDirectoryNameOf #(directory)

Returns the generated name of the passed input directory.  GenerateDirectoryNames() must be called once before this function is available.  One possible directory name is “default”, and it will always be used if there has never been more than one input directory.

SplitFromInputDirectory

sub SplitFromInputDirectory #(file)

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

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.

Returns

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

OutputStyleOf

sub OutputStyleOf #(object)

Returns the style associated with a builder object.

Parameters

objectThe builder object.

Returns

The style string, or undef if the object wasn’t found.

ProjectDirectory

sub ProjectDirectory

Returns the project directory.

ProjectDataDirectory

sub ProjectDataDirectory

Returns the project data directory.

StyleDirectory

sub StyleDirectory

Returns the main style 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.

RebuildData

sub RebuildData

Returns whether the script should rebuild all data files from scratch.

RebuildOutput

sub RebuildOutput

Returns whether the script should rebuild all output files from scratch.

IsQuiet

sub IsQuiet

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

HeadersOnly

sub HeadersOnly

Returns whether to only check the header files in C/C++.

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.

LoadSettingsFile

sub LoadSettingsFile

Loads and parses Settings.txt.

Returns

An arrayref of NaturalDocs::Settings::BuildTargets.  If there’s nothing in the file, it returns an empty arrayref.

SaveSettingsFile

sub SaveSettingsFile

Saves Settings.txt to disk.

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.
Copyright © 2003-2004 Greg Valure.  Generated by Natural Docs.
The file that stores the Natural Docs build targets.
Stores the previous command line settings.
my @inputDirectories
An array of input directories.
my @inputDirectoryNames
An array of the input directory 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 $rebuildData
Whether the script should rebuild all data files from scratch.
my $rebuildOutput
Whether the script should rebuild all output files from scratch.
my $isQuiet
Whether the script should be run in quiet mode or not.
my $headersOnly
Whether only the header files in C/C++ should be used.
my $defaultStyle
The style to be used if an output format doesn’t have its own style specified.
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 #(hints)
Generates names for each of the input directories, which can later be retrieved with InputDirectoryNameOf().
sub InputDirectoryNameOf #(directory)
Returns the generated name of the passed 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 BuildTargets
Returns an arrayref of NaturalDocs::Settings::BuildTargets.
sub OutputDirectoryOf #(object)
Returns the output directory of a builder object.
sub OutputStyleOf #(object)
Returns the style associated with a builder object.
sub ProjectDirectory
Returns the project directory.
sub ProjectDataDirectory
Returns the project data directory.
sub StyleDirectory
Returns the main style 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 RebuildData
Returns whether the script should rebuild all data files from scratch.
sub RebuildOutput
Returns whether the script should rebuild all output files from scratch.
sub IsQuiet
Returns whether the script should be run in quiet mode or not.
sub HeadersOnly
Returns whether to only check the header files in C/C++.
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 LoadSettingsFile
Loads and parses Settings.txt.
sub SaveSettingsFile
Saves Settings.txt to disk.
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.
A package for handling version information.