NaturalDocs::ReferenceString

Exporter
NaturalDocs::ReferenceString

A package to manage ReferenceString handling throughout the program.

Summary
NaturalDocs::ReferenceStringA package to manage ReferenceString handling throughout the program.
Constants
Binary Format FlagsThese flags can be combined to specify the format when using ToBinaryFile() and FromBinaryFile().
ReferenceTypeThe type of a reference.
Resolving FlagsUsed to influence the method of resolving references in NaturalDocs::SymbolTable.
Functions
MakeFromEncodes the passed information as a ReferenceString.
ToBinaryFileWrites a ReferenceString to the passed filehandle.
FromBinaryFileReads a ReferenceString or undef from the passed filehandle.
InformationOfReturns the information encoded in a ReferenceString.
TypeOfReturns the ReferenceType encoded in the reference string.

Constants

Binary Format Flags

These flags can be combined to specify the format when using ToBinaryFile() and FromBinaryFile().  All are exported by default.

BINARYREF_NOTYPEDo not include the ReferenceType.
BINARYREF_NORESOLVEFLAGSDo not include the Resolving Flags.

ReferenceType

The type of a reference.

REFERENCE_TEXTThe reference appears in the text of the documentation.
REFERENCE_CH_CLASSA class reference handled by NaturalDocs::ClassHierarchy.
REFERENCE_CH_PARENTA parent class reference handled by NaturalDocs::ClassHierarchy.

Dependencies

Resolving Flags

Used to influence the method of resolving references in NaturalDocs::SymbolTable.

RESOLVE_RELATIVEThe reference text is truly relative, rather than Natural Docs’ semi-relative.
RESOLVE_ABSOLUTEThe reference text is always absolute.  No local or relative references.
RESOLVE_NOPLURALThe reference text may not be interpreted as a plural, and thus match singular forms as well.
RESOLVE_NOUSINGThe reference text may not include “using” statements when being resolved.

If neither RESOLVE_RELATIVE or RESOLVE_ABSOLUTE is specified, Natural Docs’ semi-relative kicks in instead, which is where links are interpreted as local, then global, then relative.  RESOLVE_RELATIVE states that links are local, then relative, then global.

Dependencies

Functions

MakeFrom

sub MakeFrom #(ReferenceType type,
SymbolString symbol,
string language,
SymbolString scope,
SymbolString[] *using,
flags resolvingFlags)

Encodes the passed information as a ReferenceString.  The format of the string should be treated as opaque.  However, the characteristic you can rely on is that the same string will always be made from the same parameters, and thus it’s suitable for comparison and use as hash keys.

Parameters

typeThe ReferenceType.
symbolThe SymbolString of the reference.
languageThe name of the language that defines the file this reference appears in.
scopeThe scope SymbolString the reference appears in, or undef if none.
usingAn arrayref of scope SymbolStrings that are also available for checking due to the equivalent a “using” statement, or undef if none.
resolvingFlagsThe Resolving Flags to use with this reference.  They are ignored if the type is REFERENCE_TEXT.

Returns

The encoded ReferenceString.

ToBinaryFile

sub ToBinaryFile #(FileHandle fileHandle,
ReferenceString referenceString,
flags binaryFormatFlags)

Writes a ReferenceString to the passed filehandle.  Can also encode an undef.

Parameters

fileHandleThe filehandle to write to.
referenceStringThe ReferenceString to write, or undef.
binaryFormatFlagsAny Binary Format Flags you want to use to influence encoding.

Format

[SymbolString: Symbol or undef for an undef reference]
[UString16: language]
[SymbolString: Scope or undef for none]

[SymbolString: Using or undef for none]
[SymbolString: Using or undef for no more]
...

[UInt8: Type unless BINARYREF_NOTYPE is set]
[UInt8: Resolving Flags unless BINARYREF_NORESOLVINGFLAGS is set]

Dependencies

FromBinaryFile

sub FromBinaryFile #(FileHandle fileHandle,
flags binaryFormatFlags,
ReferenceType type,
flags resolvingFlags)

Reads a ReferenceString or undef from the passed filehandle.

Parameters

fileHandleThe filehandle to read from.
binaryFormatFlagsAny Binary Format Flags you want to use to influence decoding.
typeThe ReferenceType to use if BINARYREF_NOTYPE is set.
resolvingFlagsThe Resolving Flags to use if <BINARYREF_NORESOLVINGFLAGS> is set.

Returns

The ReferenceString or undef.

See Also

See ToBinaryFile() for format and dependencies.

InformationOf

sub InformationOf #(ReferenceString referenceString)

Returns the information encoded in a ReferenceString.

Parameters

referenceStringThe ReferenceString to decode.

Returns

The array ( type, symbol, language, scope, using, resolvingFlags ).

typeThe ReferenceType.
symbolThe SymbolString.
languageThe name of the language that defined the file the reference was defined in.
scopeThe scope SymbolString, or undef if none.
usingAn arrayref of scope SymbolStrings that the reference also has access to via “using” statements, or undef if none.
resolvingFlagsThe Resolving Flags of the reference.

TypeOf

sub TypeOf #(ReferenceString referenceString)

Returns the ReferenceType encoded in the reference string.  This is faster than InformationOf() if this is the only information you need.

All the information about a reference that makes it unique encoded into a string.
sub ToBinaryFile #(FileHandle fileHandle,
ReferenceString referenceString,
flags binaryFormatFlags)
Writes a ReferenceString to the passed filehandle.
sub FromBinaryFile #(FileHandle fileHandle,
flags binaryFormatFlags,
ReferenceType type,
flags resolvingFlags)
Reads a ReferenceString or undef from the passed filehandle.
A package that handles all the gory details of managing symbols.
sub MakeFrom #(ReferenceType type,
SymbolString symbol,
string language,
SymbolString scope,
SymbolString[] *using,
flags resolvingFlags)
Encodes the passed information as a ReferenceString.
sub InformationOf #(ReferenceString referenceString)
Returns the information encoded in a ReferenceString.
sub TypeOf #(ReferenceString referenceString)
Returns the ReferenceType encoded in the reference string.
The type of a reference.
Used to influence the method of resolving references in NaturalDocs::SymbolTable.
A package that handles all the gory details of managing the class hierarchy.
The reference text is truly relative, rather than Natural Docs’ semi-relative.
The reference text is always absolute.
A scalar which encodes a normalized array of identifier strings representing a full or partially-resolved symbol.
The reference appears in the text of the documentation.
These flags can be combined to specify the format when using ToBinaryFile() and FromBinaryFile().
Do not include the ReferenceType.
Close