NaturalDocs::Parser::ParsedTopic

A class for parsed topics of source files. Also encompasses some of the TopicType-specific behavior.

Summary

NaturalDocs::Parser::ParsedTopic	A class for parsed topics of source files.
Implementation
Members	The object is a blessed arrayref with the following indexes.
Title, Package, and Symbol Behavior	Title, package, and symbol behavior is a little awkward so it deserves some explanation.
Functions
New	Creates a new object.
Type	Returns the TopicType.
SetType	Replaces the TopicType.
IsList	Returns whether the topic is a list.
SetIsList	Sets whether the topic is a list.
Title	Returns the title of the topic.
SetTitle	Replaces the topic title.
Symbol	Returns the SymbolString defined by the topic.
Package	Returns the package SymbolString that the topic appears in.
SetPackage	Replaces the package the topic appears in.
Using	Returns an arrayref of additional scope SymbolStrings available to the topic via “using” statements, or undef if none.
SetUsing	Replaces the using arrayref of sope SymbolStrings.
Prototype	Returns the prototype if one is defined.
SetPrototype	Replaces the function or variable prototype.
Summary	Returns the topic summary, if it exists, formatted in NDMarkup.
Body	Returns the topic’s body, formatted in NDMarkup.
SetBody	Replaces the topic’s body, formatted in NDMarkup.
LineNumber	Returns the line the topic appears at in the file.

Implementation

Members

The object is a blessed arrayref with the following indexes.

TYPE	The TopicType.
TITLE	The title of the topic.
PACKAGE	The package SymbolString the topic appears in, or undef if none.
USING	An arrayref of additional package SymbolStrings available to the topic via “using” statements, or undef if none.
PROTOTYPE	The prototype, if it exists and is applicable.
SUMMARY	The summary, if it exists.
BODY	The body of the topic, formatted in NDMarkup. Some topics may not have bodies, and if not, this will be undef.
LINE_NUMBER	The line number the topic appears at in the file.
IS_LIST	Whether the topic is a list.

Title, Package, and Symbol Behavior

Title, package, and symbol behavior is a little awkward so it deserves some explanation. Basically you set them according to certain rules, but you get computed values that try to hide all the different scoping situations.

Normal Topics

Set them to the title and package as they appear. “Function” and “PkgA.PkgB” will return “Function” for the title, “PkgA.PkgB” for the package, and “PkgA.PkgB.Function” for the symbol.

In the rare case that a title has a separator symbol it’s treated as inadvertant, so “A vs. B” in “PkgA.PkgB” still returns just “PkgA.PkgB” for the package even though if you got it from the symbol it can be seen as “PkgA.PkgB.A vs”.

Scope Topics

Set the title normally and leave the package undef. So “PkgA.PkgB” and undef will return “PkgA.PkgB” for the title as well as for the package and symbol.

The only time you should set the package is when you have full language support and they only documented the class with a partial title. So if you documented “PkgA.PkgB” with just “PkgB”, you want to set the package to “PkgA”. This will return “PkgB” as the title for presentation and will return “PkgA.PkgB” for the package and symbol, which is correct.

Always Global Topics

Set the title and package normally, do not set the package to undef. So “Global” and “PkgA.PkgB” will return “Global” as the title, “PkgA.PkgB” as the package, and “Global” as the symbol.

Um, yeah...

So does this suck? Yes, yes it does. But the suckiness is centralized here instead of having to be handled everywhere these issues come into play. Just realize there are a certain set of rules to follow when you set these variables, and the results you see when you get them are computed rather than literal.

Functions

New

sub New #( type,
title,
package,
using,
prototype,
summary,
body,
lineNumber,
isList )

Creates a new object.

Parameters

type	The TopicType.
title	The title of the topic.
package	The package SymbolString the topic appears in, or undef if none.
using	An arrayref of additional package SymbolStrings available to the topic via “using” statements, or undef if none.
prototype	The prototype, if it exists and is applicable. Otherwise set to undef.
summary	The summary of the topic, if any.
body	The body of the topic, formatted in NDMarkup. May be undef, as some topics may not have bodies.
lineNumber	The line number the topic appears at in the file.
isList	Whether the topic is a list topic or not.

Returns

The new object.

Type

sub Type

Returns the TopicType.

SetType

sub SetType #( type )

Replaces the TopicType.

IsList

sub IsList

Returns whether the topic is a list.

SetIsList

sub SetIsList

Sets whether the topic is a list.

Title

sub Title

Returns the title of the topic.

SetTitle

sub SetTitle #( title )

Replaces the topic title.

Symbol

sub Symbol

Returns the SymbolString defined by the topic. It is fully resolved and does not need to be joined with Package().

Type-Specific Behavior

If the TopicType is always global, the symbol will be generated from the title only.
Everything else’s symbols will be generated from the title and the package passed to New().

Package

sub Package

Returns the package SymbolString that the topic appears in.

Type-Specific Behavior

If the TopicType has scope, the package will be generated from both the title and the package passed to New(), not just the package.
If the TopicType is always global, the package will be the one passed to New(), even though it isn’t part of it’s Symbol().
Everything else’s package will be what was passed to New(), even if the title has separator symbols in it.

SetPackage

sub SetPackage #( package )

Replaces the package the topic appears in. This will behave the same way as the package parameter in New(). Later calls to Package() will still be generated according to its type-specific behavior.

Using

sub Using

Returns an arrayref of additional scope SymbolStrings available to the topic via “using” statements, or undef if none.

SetUsing

sub SetUsing #( using )

Replaces the using arrayref of sope SymbolStrings.

Prototype

sub Prototype

Returns the prototype if one is defined. Will be undef otherwise.

SetPrototype

sub SetPrototype #( prototype )

Replaces the function or variable prototype.

Summary

sub Summary

Returns the topic summary, if it exists, formatted in NDMarkup.

Body

sub Body

Returns the topic’s body, formatted in NDMarkup. May be undef.

SetBody

sub SetBody #( body )

Replaces the topic’s body, formatted in NDMarkup. May be undef.

LineNumber

sub LineNumber

Returns the line the topic appears at in the file.