NaturalDocs::Topics

Exporter

NaturalDocs::Topics

The topic constants and functions to convert them to and from strings used throughout the script. All constants are exported by default.

Summary

NaturalDocs::Topics	The topic constants and functions to convert them to and from strings used throughout the script.
@EXPORT
Types
TopicType	A string representing a topic type as defined in Topics.txt.
Default TopicTypes	Exported constants of the default TopicTypes, so you don’t have to go through TypeFromName() every time.
Variables
FH_TOPICS	The file handle used when writing to Topics.txt.
types	A hashref that maps TopicTypes to NaturalDocs::Topics::Types.
names	A hashref that maps various forms of the all-lowercase type names to TopicTypes.
keywords	A hashref that maps all-lowercase keywords to their TopicTypes.
pluralKeywords	A hashref that maps all-lowercase plural keywords to their TopicTypes.
indexable	An existence hash of all the indexable TopicTypes.
requiredTypeNames	An array of the TopicType names which are required to be defined in the main file.
legacyTypes	An array that converts the legacy topic types, which were numeric constants prior to 1.3, to the current TopicTypes.
mainTopicNames	An array of the TopicType names that are defined in the main Topics.txt.
Files
Topics.txt	The configuration file that defines or overrides the topic definitions for Natural Docs.
File Functions
Load	Loads both the master and the project version of Topics.txt.
LoadFile	Loads a particular version of Topics.txt.
Save	Saves the main and user versions of Topics.txt.
SaveFile	Saves a particular version of Topics.txt.
Functions
KeywordInfo	Returns information about a topic keyword.
NameInfo	Returns information about a topic name.
TypeInfo	Returns information about a TopicType.
NameOfType	Returns the name of the passed TopicType, or undef if it doesn’t exist.
TypeFromName	Returns a TopicType for the passed topic name.
IsValidType	Returns whether the passed TopicType is defined.
TypeFromLegacy	Returns a TopicType for the passed legacy topic type integer.
AllIndexableTypes	Returns an array of all possible indexable TopicTypes.
Support Functions
MakeTopicType	Returns a TopicType for the passed topic name.

@EXPORT

our @EXPORT

Types

TopicType

A string representing a topic type as defined in Topics.txt. It’s format should be treated as opaque; use MakeTopicType() to get them from topic names. However, they can be compared for equality with string functions.

Default TopicTypes

Exported constants of the default TopicTypes, so you don’t have to go through TypeFromName() every time.

TOPIC_GENERAL	The general TopicType, which has the special meaning of none in particular.
TOPIC_GENERIC	Generic TopicType.
TOPIC_GROUP	Group TopicType.
TOPIC_CLASS	Class TopicType.
TOPIC_INTERFACE	Interface TopicType.
TOPIC_FILE	File TopicType.
TOPIC_SECTION	Section TopicType.
TOPIC_FUNCTION	Function TopicType.
TOPIC_VARIABLE	Variable TopicType.
TOPIC_PROPERTY	Property TopicType.
TOPIC_TYPE	Type TopicType.
TOPIC_CONSTANT	Constant TopicType.
TOPIC_ENUMERATION	Enum TopicType.
TOPIC_DELEGATE	Delegate TopicType.
TOPIC_EVENT	Event TopicType.

Variables

FH_TOPICS

The file handle used when writing to Topics.txt.

types

my %types

A hashref that maps TopicTypes to NaturalDocs::Topics::Types.

names

my %names

A hashref that maps various forms of the all-lowercase type names to TopicTypes. All are in the same hash because two names that reduce to the same thing it would cause big problems, and we need to catch that. Keys include

Topic names
Plural topic names
Alphanumeric-only topic names
Alphanumeric-only plural topic names

keywords

my %keywords

A hashref that maps all-lowercase keywords to their TopicTypes. Must not have any of the same keys as pluralKeywords.

pluralKeywords

my %pluralKeywords

A hashref that maps all-lowercase plural keywords to their TopicTypes. Must not have any of the same keys as keywords.

indexable

my %indexable

An existence hash of all the indexable TopicTypes.

requiredTypeNames

my @requiredTypeNames

An array of the TopicType names which are required to be defined in the main file. Are in the order they should appear when reformatting.

legacyTypes

my @legacyTypes

An array that converts the legacy topic types, which were numeric constants prior to 1.3, to the current TopicTypes. The legacy types are used as an index into the array. Note that this does not support list type values.

mainTopicNames

my @mainTopicNames

An array of the TopicType names that are defined in the main Topics.txt.

Files

Topics.txt

The configuration file that defines or overrides the topic definitions for Natural Docs. One version sits in Natural Docs’ configuration directory, and another can be in a project directory to add to or override them.

# [comments]

Everything after a # symbol is ignored.

Except when specifying topic names, everything below is case-insensitive.

Format: [version]

Specifies the file format version of the file.

Sections

Ignore[d] Keyword[s]: [keyword], [keyword] ...
   [keyword]
   [keyword], [keyword]
   ...

Ignores the keywords so that they’re not recognized as Natural Docs topics anymore. Can be specified as a list on the same line and/or following like a normal Keywords section.

Topic Type: [name]
Alter Topic Type: [name]

Creates a new topic type or alters an existing one. The name can only contain CFChars and isn’t case sensitive, although the original case is remembered for presentation.

The name General is reserved. There are a number of default types that must be defined in the main file as well, but those are governed by NaturalDocs::Topics and are not included here. The default types can have their keywords or behaviors changed, though, either by editing the default file or by overriding them in the user file.

Enumeration is a special type. It is indexed with Types and its definition list members are listed with Constants according to the rules in Languages.txt.

Topic Type Sections

Plural: [name]

Specifies the plural name of the topic type. Defaults to the singular name. Has the same restrictions as the topic type name.

Index: [yes|no]

Whether the topic type gets an index. Defaults to yes.

Scope: [normal|start|end|always global]

How the topic affects scope. Defaults to normal.

normal	The topic stays within the current scope.
start	The topic starts a new scope for all the topics beneath it, like class topics.
end	The topic resets the scope back to global for all the topics beneath it, like section topics.
always global	The topic is defined as a global symbol, but does not change the scope for any other topics.

Class Hierarchy: [yes|no]

Whether the topic is part of the class hierarchy. Defaults to no.

Page Title if First: [yes|no]

Whether the title of this topic becomes the page title if it is the first topic in a file. Defaults to no.

Break Lists: [yes|no]

Whether list topics should be broken into individual topics in the output. Defaults to no.

Can Group With: [topic type], [topic type], ...

The list of TopicTypes the topic can possibly be grouped with.

[Add] Keyword[s]:
   [keyword]
   [keyword], [plural keyword]
   ...

A list of the topic type’s keywords. Each line after the heading is the keyword and optionally its plural form. This continues until the next line in “keyword: value” format. “Add” isn’t required.

Keywords can only have letters and numbers. No punctuation or spaces are allowed.
Keywords are not case sensitive.
Subsequent keyword sections add to the list. They don’t replace it.
Keywords can be redefined by other keyword sections.

Revisions

1.3

The initial version of this file.

File Functions

Load

sub Load

Loads both the master and the project version of Topics.txt.

LoadFile

sub LoadFile #( isMain )

Loads a particular version of Topics.txt.

Parameters

isMain

Whether the file is the main file or not.

Save

sub Save

Saves the main and user versions of Topics.txt.

SaveFile

sub SaveFile #( isMain )

Saves a particular version of Topics.txt.

Parameters

isMain

Whether the file is the main file or not.

Functions

KeywordInfo

sub KeywordInfo #( keyword )

Returns information about a topic keyword.

Parameters

keyword

The keyword, which may be plural.

Returns

The array ( topicType, info, isPlural ), or an empty array if the keyword doesn’t exist.

topicType	The TopicType of the keyword.
info	The NaturalDocs::Topics::Type of its type.
isPlural	Whether the keyword was plural or not.

NameInfo

sub NameInfo #( name )

Returns information about a topic name.

Parameters

name	The topic type name, which can be plural and/or alphanumeric only.

Returns

The array ( topicType, info ), or an empty array if the name doesn’t exist. Note that unlike KeywordInfo(), this does not tell you whether the name is plural or not.

topicType	The TopicType of the name.
info	The NaturalDocs::Topics::Type of the type.

TypeInfo

sub TypeInfo #( type )

Returns information about a TopicType.

Parameters

type	The TopicType.

Returns

The NaturalDocs::Topics::Type of the type, or undef if it didn’t exist.

NameOfType

sub NameOfType #( topicType,
plural,
alphanumericOnly )

Returns the name of the passed TopicType, or undef if it doesn’t exist.

Parameters

topicType	The TopicType.
plural	Whether to return the plural instead of the singular.
alphanumericOnly	Whether to strips everything but alphanumeric characters out. Case isn’t modified.

Returns

The topic type name, according to what was specified in the parameters, or undef if it doesn’t exist.

TypeFromName

sub TypeFromName #( topicName )

Returns a TopicType for the passed topic name.

Parameters

topicName

The name of the topic, which can be plural and/or alphanumeric only.

Returns

The TopicType. It does not specify whether the name was plural or not.

IsValidType

sub IsValidType #( type )

Returns whether the passed TopicType is defined.

TypeFromLegacy

sub TypeFromLegacy #( legacyInt )

Returns a TopicType for the passed legacy topic type integer. TopicTypes were changed from integer constants to strings in 1.3.

AllIndexableTypes

sub AllIndexableTypes

Returns an array of all possible indexable TopicTypes.

Support Functions

MakeTopicType

sub MakeTopicType #( topicName )

Returns a TopicType for the passed topic name. It does not check to see if it exists already.