NaturalDocs::SymbolTable::IndexElement

A class representing part of an indexed symbol.

Summary
NaturalDocs::SymbolTable::IndexElementA class representing part of an indexed symbol.
How IndexElements WorkThis is a little tricky, so make sure you understand this.
Implementation
MembersThe class is implemented as a blessed arrayref.
Modification Functions
NewReturns a new object.
MergeAdds another definition of the same symbol.
SortSorts the package and file lists of the symbol.
MakeSortableSymbolGenerates SortableSymbol() and IgnoredPrefix().
SymbolReturns the SymbolString without the package portion.
PackageIf HasMultiplePackages() is true, returns an arrayref of NaturalDocs::SymbolTable::IndexElement objects.
FileIf HasMultipleFiles() is true, returns an arrayref of NaturalDocs::SymbolTable::IndexElement objects.
TypeReturns the TopicType of the package/symbol/file, if applicable.
PrototypeReturns the prototype of the package/symbol/file, if applicable.
SummaryReturns the summary of the package/symbol/file, if applicable.
CombinedTypeReturns the combined TopicType of the element.
PackageSeparatorReturns the combined package separator symbol of the element.
SortableSymbolReturns the sortable symbol as a text string.
IgnoredPrefixReturns the part of the symbol that was stripped off to make the SortableSymbol(), or undef if none.
HasMultiplePackagesReturns whether Packages() is broken out into more elements.
HasMultipleFilesReturns whether File() is broken out into more elements.
Support Functions
MergeFileAdds another definition of the same package/symbol.

How IndexElements Work

This is a little tricky, so make sure you understand this.  Indexes are sorted by symbol, then packages, then file.  If there is only one package for a symbol, or one file definition for a package/symbol, they are added inline to the entry.  However, if there are multiple packages or files, the function for it returns an arrayref of IndexElements instead.  Which members are defined and undefined should follow common sense.  For example, if a symbol is defined in multiple packages, the symbol’s IndexElement will not define File(), Type(), or Prototype(); those will be defined in child elements.  Similarly, the child elements will not define Symbol() since it’s redundant.

Diagrams may be clearer.  If a member isn’t listed for an element, it isn’t defined.

A symbol that only has one package and file

[Element]
- Symbol
- Package
- File
- Type
- Prototype
- Summary

A symbol that is defined by multiple packages, each with only one file

[Element]
- Symbol
- Package
    [Element]
    - Package
    - File
    - Type
    - Prototype
    - Summary
    [Element]
    - ...

A symbol that is defined by one package, but has multiple files

[Element]
- Symbol
- Package
- File
   [Element]
   - File
   - Type
   - Protype
   - Summary
   [Element]
   - ...

A symbol that is defined by multiple packages which have multiple files

[Element]
- Symbol
- Package
   [Element]
   - Package
   - File
     [Element]
     - File
     - Type
     - Prototype
     - Summary
     [Element]
     - ...
   [Element]
   - ...

Why is it done this way?

Because it makes it easier to generate nice indexes since all the splitting and combining is done for you.  If a symbol has only one package, you just want to link to it, you don’t want to break out a subindex for just one package.  However, if it has multiple package, you do want the subindex and to link to each one individually.  Use HasMultiplePackages() and HasMultipleFiles() to determine whether you need to add a subindex for it.

Combining Properties

All IndexElements also have combining properties set.

CombinedTypeThe general TopicType of the entry.  Conflicts combine into TOPIC_GENERAL.
PackageSeparatorThe package separator symbol of the entry.  Conflicts combine into a dot.

So if an IndexElement only has one definition, CombinedType() is the same as the TopicType and PackageSeparator() is that of the definition’s language.  If other definitions are added and they have the same properties, the combined properties will remain the same.  However, if they’re different, they switch values as noted above.

Sortable Symbol

SortableSymbol() is a pseudo-combining property.  There were a few options for dealing with multiple languages defining the same symbol but stripping different prefixes off it, but ultimately I decided to go with whatever the language does that has the most definitions.  There’s not likely to be many conflicts here in the real world; probably the only thing would be defining it in a text file and forgetting to specify the prefixes to strip there too.  So this works.

Ties are broken pretty much randomly, except that text files always lose if its one of the options.

It’s a pseudo-combining property because it’s done after the IndexElements are all filled in and only stored in the top-level ones.

Implementation

Members

The class is implemented as a blessed arrayref.  The following constants are its members.

SYMBOLThe SymbolString without the package portion.
PACKAGEThe package SymbolString.  Will be a package SymbolString, undef for global, or an arrayref of NaturalDocs::SymbolTable::IndexElement objects if multiple packages define the symbol.
FILEThe FileName the package/symbol is defined in.  Will be the file name or an arrayref of NaturalDocs::SymbolTable::IndexElements if multiple files define the package/symbol.
TYPEThe package/symbol/file TopicType.
PROTOTYPEThe package/symbol/file prototype, or undef if not applicable.
SUMMARYThe package/symbol/file summary, or undef if not applicable.
COMBINED_TYPEThe combined TopicType of the element.
PACKAGE_SEPARATORThe combined package separator symbol of the element.
SORTABLE_SYMBOLThe sortable symbol as a text string.
IGNORED_PREFIXThe part of the symbol that was stripped off to make the sortable symbol.

Modification Functions

New

sub New #(symbol,
package,
file,
type,
prototype,
summary,
combinedType,
packageSeparator)

Returns a new object.

This should only be used for creating an entirely new symbol.  You should not pass arrayrefs as package or file parameters if you are calling this externally.  Use Merge() instead.

Parameters

symbolThe SymbolString without the package portion.
packageThe package SymbolString, or undef for global.
fileThe symbol’s definition file.
typeThe symbol’s TopicType.
prototypeThe symbol’s prototype, if applicable.
summaryThe symbol’s summary, if applicable.

Optional Parameters

These parameters don’t need to be specified.  You should ignore them when calling this externally.

combinedTypeThe symbol’s combined TopicType.
packageSeparatorThe symbol’s combined package separator symbol.

Merge

sub Merge #(package,
file,
type,
prototype,
summary)

Adds another definition of the same symbol.  Perhaps it has a different package or defining file.

Parameters

packageThe package SymbolString, or undef for global.
fileThe symbol’s definition file.
typeThe symbol’s TopicType.
prototypeThe symbol’s protoype if applicable.
summaryThe symbol’s summary if applicable.

Sort

sub Sort

Sorts the package and file lists of the symbol.

MakeSortableSymbol

sub MakeSortableSymbol

Generates SortableSymbol() and IgnoredPrefix().  Should only be called after everything is merged.

Symbol

Returns the SymbolString without the package portion.

Package

sub HasMultiplePackages

If HasMultiplePackages() is true, returns an arrayref of NaturalDocs::SymbolTable::IndexElement objects.  Otherwise returns the package SymbolString, or undef if global.

File

sub HasMultipleFiles

If HasMultipleFiles() is true, returns an arrayref of NaturalDocs::SymbolTable::IndexElement objects.  Otherwise returns the name of the definition file.

Type

Returns the TopicType of the package/symbol/file, if applicable.

Prototype

Returns the prototype of the package/symbol/file, if applicable.

Summary

Returns the summary of the package/symbol/file, if applicable.

CombinedType

Returns the combined TopicType of the element.

PackageSeparator

Returns the combined package separator symbol of the element.

SortableSymbol

Returns the sortable symbol as a text string.  Only available after calling MakeSortableSymbol().

IgnoredPrefix

Returns the part of the symbol that was stripped off to make the SortableSymbol(), or undef if none.  Only available after calling MakeSortableSymbol().

HasMultiplePackages

Returns whether Packages() is broken out into more elements.

HasMultipleFiles

Returns whether File() is broken out into more elements.

Support Functions

MergeFile

sub MergeFile #(file,
type,
prototype,
summary)

Adds another definition of the same package/symbol.  Perhaps the file is different.

Parameters

fileThe package/symbol’s definition file.
typeThe package/symbol’s TopicType.
prototypeThe package/symbol’s protoype if applicable.
summaryThe package/symbol’s summary if applicable.
sub New #(symbol,
package,
file,
type,
prototype,
summary,
combinedType,
packageSeparator)
Returns a new object.
sub Merge #(package,
file,
type,
prototype,
summary)
Adds another definition of the same symbol.
sub Sort
Sorts the package and file lists of the symbol.
sub MakeSortableSymbol
Generates SortableSymbol() and IgnoredPrefix().
Returns the sortable symbol as a text string.
Returns the part of the symbol that was stripped off to make the SortableSymbol(), or undef if none.
A scalar which encodes a normalized array of identifier strings representing a full or partially-resolved symbol.
sub HasMultiplePackages
If HasMultiplePackages() is true, returns an arrayref of NaturalDocs::SymbolTable::IndexElement objects.
Returns whether Packages() is broken out into more elements.
A class representing part of an indexed symbol.
sub HasMultipleFiles
If HasMultipleFiles() is true, returns an arrayref of NaturalDocs::SymbolTable::IndexElement objects.
Returns whether File() is broken out into more elements.
A string representing a topic type as defined in Topics.txt.
sub MergeFile #(file,
type,
prototype,
summary)
Adds another definition of the same package/symbol.
Returns the TopicType of the package/symbol/file, if applicable.
Returns the prototype of the package/symbol/file, if applicable.
Returns the SymbolString without the package portion.
The general TopicType, which has the special meaning of none in particular.
Returns the combined TopicType of the element.
Returns the combined package separator symbol of the element.
A string representing the absolute, platform-dependent path to a file.
Close