NaturalDocs:: SymbolTable:: IndexElement

A class representing part of an indexed symbol. 

Summary
A class representing part of an indexed symbol.
This is a little tricky, so make sure you understand this.
The class is implemented as a blessed arrayref.
Returns a new object.
Adds another definition of the same symbol.
Sorts the class and file lists of the symbol.
Returns the symbol name if applicable.
Returns the class of the symbol, if applicable.
Returns the file the class/symbol is defined in, if applicable.
Returns the type of the class/symbol/file, if applicable.
Returns the prototype of the class/symbol/file, if applicable.
Adds another definition of the same class/symbol.

How IndexElements Work

This is a little tricky, so make sure you understand this.  Indexes are sorted by symbol, then class, then file.  If there is only one class for a symbol, or one file definition for a class/symbol, they are added inline to the entry.  However, if there are multiple classes or definitions, 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 classes, 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 class and definiton

[Element]
- Symbol
- Class
- File
- Type
- Prototype

A symbol that is defined by multiple classes, each with only one definition

[Element]
- Symbol
- Class
    [Element]
    - Class
    - File
    - Type
    - Prototype
    [Element]
    - ...

A symbol that is defined by one class, but has multiple definitions

[Element]
- Symbol
- Class
- File
   [Element]
   - File
   - Type
   - Protype
   [Element]
   - ...

A symbol that is defined by multiple classes which have multiple definitions

[Element]
- Symbol
- Class
   [Element]
   - Class
   - File
     [Element]
     - File
     - Type
     - Prototype
     [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 class, you just want to link to it, you don’t want to break out a subindex for just one class.  However, if it has multiple classes, you do want the subindex and to link to each one individually.  Whether Class() or File() returns an array or not determines whether you need to add a subindex for it. 

Implementation

Members

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

SYMBOLThe name of the symbol. 
CLASSThe class of the symbol.  Will be that class name, undef for global, or an arrayref of NaturalDocs::SymbolTable::IndexElement objects if multiple classes define the symbol. 
FILEThe file the class/symbol is defined in.  Will be the file name or an arrayref of NaturalDocs::SymbolTable::IndexElements if multiple files define the class/symbol. 
TYPEThe class/symbol/file type.  Will be one of the Topic Types
PROTOTYPEThe class/symbol/file prototype, or undef if not applicable. 

Modification Functions

New

sub New #(symbol, class, file, type, prototype)

Returns a new object. 

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

Parameters

symbolThe symbol’s name. 
classThe symbol’s class, or undef for global. 
fileThe symbol’s definition file. 
typeThe symbol’s type.  One of the Topic Types
prototypeThe symbol’s prototype, if applicable. 

Merge

sub Merge #(class, file, type, prototype)

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

Parameters

classThe symbol’s class, or undef for global. 
fileThe symbol’s definition file. 
typeThe symbol’s type.  One of the Topic Types
prototypeThe symbol’s protoype if applicable. 

Sort

sub Sort

Sorts the class and file lists of the symbol. 

Information Functions

Symbol

sub Symbol

Returns the symbol name if applicable. 

Class

sub Class

Returns the class of the symbol, if applicable.  Will be undef for global, the name if there’s one definiton, or an arrayref of NaturalDocs::SymbolTable::IndexElement objects if there are multiple classes that define the symbol. 

File

sub File

Returns the file the class/symbol is defined in, if applicable.  Will be the name if there’s one definition, or an arrayref of NaturalDocs::SymbolTable::IndexElement objects if there are multiple files that define the class/symbol. 

Type

sub Type

Returns the type of the class/symbol/file, if applicable.  Will be one of the Topic Types

Prototype

sub Prototype

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

Support Functions

MergeFile

sub MergeFile #(file, type, prototype)

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

Parameters

fileThe class/symbol’s definition file. 
typeThe class/symbol’s type.  One of the Topic Types
prototypeThe class/symbol’s protoype if applicable.