NaturalDocs::Parser::ParsedTopic

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

Summary
NaturalDocs::Parser::ParsedTopicA class for parsed topics of source files.
Implementation
MembersThe object is a blessed arrayref with the following indexes.
Title, Package, and Symbol BehaviorTitle, package, and symbol behavior is a little awkward so it deserves some explanation.
Functions
NewCreates a new object.
TypeReturns the TopicType.
SetTypeReplaces the TopicType.
IsListReturns whether the topic is a list.
SetIsListSets whether the topic is a list.
TitleReturns the title of the topic.
SetTitleReplaces the topic title.
SymbolReturns the SymbolString defined by the topic.
PackageReturns the package SymbolString that the topic appears in.
SetPackageReplaces the package the topic appears in.
UsingReturns an arrayref of additional scope SymbolStrings available to the topic via “using” statements, or undef if none.
SetUsingReplaces the using arrayref of sope SymbolStrings.
PrototypeReturns the prototype if one is defined.
SetPrototypeReplaces the function or variable prototype.
SummaryReturns the topic summary, if it exists, formatted in NDMarkup.
BodyReturns the topic’s body, formatted in NDMarkup.
SetBodyReplaces the topic’s body, formatted in NDMarkup.
LineNumberReturns the line the topic appears at in the file.

Implementation

Members

The object is a blessed arrayref with the following indexes.

TYPEThe TopicType.
TITLEThe title of the topic.
PACKAGEThe package SymbolString the topic appears in, or undef if none.
USINGAn arrayref of additional package SymbolStrings available to the topic via “using” statements, or undef if none.
PROTOTYPEThe prototype, if it exists and is applicable.
SUMMARYThe summary, if it exists.
BODYThe body of the topic, formatted in NDMarkup.  Some topics may not have bodies, and if not, this will be undef.
LINE_NUMBERThe line number the topic appears at in the file.
IS_LISTWhether 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

typeThe TopicType.
titleThe title of the topic.
packageThe package SymbolString the topic appears in, or undef if none.
usingAn arrayref of additional package SymbolStrings available to the topic via “using” statements, or undef if none.
prototypeThe prototype, if it exists and is applicable.  Otherwise set to undef.
summaryThe summary of the topic, if any.
bodyThe body of the topic, formatted in NDMarkup.  May be undef, as some topics may not have bodies.
lineNumberThe line number the topic appears at in the file.
isListWhether 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.

sub New #(type,
title,
package,
using,
prototype,
summary,
body,
lineNumber,
isList)
Creates a new object.
sub Type
Returns the TopicType.
A string representing a topic type as defined in Topics.txt.
sub SetType #(type)
Replaces the TopicType.
sub IsList
Returns whether the topic is a list.
sub SetIsList
Sets whether the topic is a list.
sub Title
Returns the title of the topic.
sub SetTitle #(title)
Replaces the topic title.
sub Symbol
Returns the SymbolString defined by the topic.
A scalar which encodes a normalized array of identifier strings representing a full or partially-resolved symbol.
sub Package
Returns the package SymbolString that the topic appears in.
sub SetPackage #(package)
Replaces the package the topic appears in.
sub Using
Returns an arrayref of additional scope SymbolStrings available to the topic via “using” statements, or undef if none.
sub SetUsing #(using)
Replaces the using arrayref of sope SymbolStrings.
sub Prototype
Returns the prototype if one is defined.
sub SetPrototype #(prototype)
Replaces the function or variable prototype.
sub Summary
Returns the topic summary, if it exists, formatted in NDMarkup.
A markup format used by the parser, both internally and in NaturalDocs::Parser::ParsedTopic objects.
sub Body
Returns the topic’s body, formatted in NDMarkup.
sub SetBody #(body)
Replaces the topic’s body, formatted in NDMarkup.
sub LineNumber
Returns the line the topic appears at in the file.
Close