NaturalDocs

Version 1.52

Copyright © 2003-2010 Greg Valure

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
NaturalDocsVersion 1.52
Code Conventions
File Format Conventions
INIT
Basic TypesTypes used throughout the program.
FileNameA string representing the absolute, platform-dependent path to a file.
VersionIntA comparable integer representing a version number.
SymbolStringA scalar which encodes a normalized array of identifier strings representing a full or partially-resolved symbol.
ReferenceStringAll the information about a reference that makes it unique encoded into a string.
Support FunctionsGeneral functions that are used throughout the program, and that don’t really fit anywhere else.
StringCompareCompares two strings so that the result is good for proper sorting.
ShortenToMatchStringsCompares two arrayrefs and shortens the first array to only contain shared entries.
FindFirstSymbolSearches 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

sharedArrayRefThe arrayref that will be shortened to only contain common elements.
compareArrayRefThe arrayref to match.

FindFirstSymbol

sub FindFirstSymbol #(string,
symbols,
index)

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

Parameters

stringThe string to search.
symbolsAn arrayref of symbols to look for.
indexThe index to start at, if any.

Returns

The array ( index, symbol ).

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

$filesToParse

my $filesToParse

$amount

my $amount
sub INIT
sub StringCompare #(a,
b)
Compares two strings so that the result is good for proper sorting.
sub ShortenToMatchStrings #(sharedArrayRef,
compareArrayRef)
Compares two arrayrefs and shortens the first array to only contain shared entries.
sub FindFirstSymbol #(string,
symbols,
index)
Searches a string for a number of symbols to see which appears first.
my $filesToParse
my $amount
Natural Docs is Copyright © 2003-2010 Greg Valure.
A scalar which encodes a normalized array of identifier strings representing a full or partially-resolved symbol.
sub ToBinaryFile #(FileHandle fileHandle,
SymbolString symbol)
Writes a SymbolString to the passed filehandle.
sub FromBinaryFile #(FileHandle fileHandle)
Loads a SymbolString or undef from the filehandle and returns it.
A package to manage file access across platforms.
A package for handling version information.
sub FromText #(string textSymbol)
Extracts and returns a SymbolString from plain text.
The type of a reference.
Close