NaturalDocs:: SymbolTable:: IndexElement

A class representing part of an indexed symbol.

Summary

NaturalDocs:: SymbolTable:: IndexElement	A class representing part of an indexed symbol.
How IndexElements Work	This is a little tricky, so make sure you understand this.
Implementation
Members	The class is implemented as a blessed arrayref.
Modification Functions
New	Returns a new object.
Merge	Adds another definition of the same symbol.
Sort	Sorts the class and file lists of the symbol.
Information Functions
Symbol	Returns the symbol name if applicable.
Class	Returns the class of the symbol, if applicable.
File	Returns the file the class/symbol is defined in, if applicable.
Type	Returns the type of the class/symbol/file, if applicable.
Prototype	Returns the prototype of the class/symbol/file, if applicable.
Support Functions
MergeFile	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.

SYMBOL	The name of the symbol.
CLASS	The 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.
FILE	The 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.
TYPE	The class/symbol/file type. Will be one of the Topic Types.
PROTOTYPE	The 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

symbol	The symbol’s name.
class	The symbol’s class, or undef for global.
file	The symbol’s definition file.
type	The symbol’s type. One of the Topic Types.
prototype	The 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

class	The symbol’s class, or undef for global.
file	The symbol’s definition file.
type	The symbol’s type. One of the Topic Types.
prototype	The 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

file	The class/symbol’s definition file.
type	The class/symbol’s type. One of the Topic Types.
prototype	The class/symbol’s protoype if applicable.