NaturalDocs

Version 1.52

http://www.naturaldocs.org

Natural Docs is licensed under version 3 of the GNU Affero General Public License (AGPL). Refer to the License for the complete details.

Summary

NaturalDocs	Version 1.52
Code Conventions
File Format Conventions
INIT
Basic Types	Types used throughout the program.
FileName	A string representing the absolute, platform-dependent path to a file.
VersionInt	A comparable integer representing a version number.
SymbolString	A scalar which encodes a normalized array of identifier strings representing a full or partially-resolved symbol.
ReferenceString	All the information about a reference that makes it unique encoded into a string.
Support Functions	General functions that are used throughout the program, and that don’t really fit anywhere else.
StringCompare	Compares two strings so that the result is good for proper sorting.
ShortenToMatchStrings	Compares two arrayrefs and shortens the first array to only contain shared entries.
FindFirstSymbol	Searches a string for a number of symbols to see which appears first.
$filesToParse
$amount

Code Conventions

Every package function is called with an arrow operator. It’s needed for inheritance in some places, and consistency when it’s not.
No constant will ever be zero or undef. Those are reserved so any piece of code can allow a “none of the above” option and not worry about conflicts with an existing value.
Existence hashes are hashes where the value doesn’t matter. It acts more as a set, where the existence of the key is the significant part.

File Format Conventions

All integers appear in big-endian format. So a UInt16 should be handled with a ‘n’ in pack and unpack, not with a ‘S’.
UString16’s are a big-endian UInt16 followed by that many UTF-8 bytes. A null-terminator is not stored.
If a higher-level type is described in a file format, that means the loading and saving format is handled by that package. For example, if you see SymbolString in the format, that means NaturalDocs::SymbolString->ToBinaryFile() and NaturalDocs::SymbolString->FromBinaryFile() are used to manipulate it, and the underlying format should be treated as opaque.

INIT

sub INIT

Basic Types

Types used throughout the program. As Perl is a weakly-typed language unless you box things into objects, these types are for documentation purposes and are not enforced.

FileName

A string representing the absolute, platform-dependent path to a file. Relative file paths are no longer in use anywhere in the program. All path manipulation should be done through NaturalDocs::File.

VersionInt

A comparable integer representing a version number. Converting them to and from text and binary should be handled by NaturalDocs::Version.

SymbolString

A scalar which encodes a normalized array of identifier strings representing a full or partially-resolved symbol. All symbols must be retrieved from plain text via NaturalDocs::SymbolString->FromText() so that the separation and normalization is always consistent. SymbolStrings are comparable via string compare functions and are sortable.

ReferenceString

All the information about a reference that makes it unique encoded into a string. This includes the SymbolString of the reference, the scope SymbolString it appears in, the scope SymbolStrings it has access to via “using”, and the ReferenceType. This is done because if any of those parameters change, it needs to be treated as a completely separate reference.

Support Functions

General functions that are used throughout the program, and that don’t really fit anywhere else.

StringCompare

sub StringCompare #( a,
b )

Compares two strings so that the result is good for proper sorting. A proper sort orders the characters as follows:

End of string.
Whitespace. Line break-tab-space.
Symbols, which is anything not included in the other entries.
Numbers, 0-9.
Letters, case insensitive except to break ties.

If you use cmp instead of this function, the result would go by ASCII/Unicode values which would place certain symbols between letters and numbers instead of having them all grouped together. Also, you would have to choose between case sensitivity or complete case insensitivity, in which ties are broken arbitrarily.

Returns

Like cmp, it returns zero if A and B are equal, a positive value if A is greater than B, and a negative value if A is less than B.

ShortenToMatchStrings

sub ShortenToMatchStrings #( sharedArrayRef,
compareArrayRef )

Compares two arrayrefs and shortens the first array to only contain shared entries. Assumes all entries are strings.

Parameters

sharedArrayRef	The arrayref that will be shortened to only contain common elements.
compareArrayRef	The arrayref to match.

FindFirstSymbol

sub FindFirstSymbol #( string,
symbols,
index )

Searches a string for a number of symbols to see which appears first.

Parameters

string	The string to search.
symbols	An arrayref of symbols to look for.
index	The index to start at, if any.

Returns

The array ( index, symbol ).

index	The index the first symbol appears at, or -1 if none appear.
symbol	The symbol that appeared, or undef if none.

$filesToParse

my $filesToParse

$amount

my $amount