NaturalDocs:: Menu

A package handling the menu’s contents and state.

Usage and Dependencies

The Event Handlers can be called by NaturalDocs::Project immediately.
Prior to initialization, NaturalDocs::Project must be initialized, and all files that have been changed must be run through NaturalDocs::Parser::ParseForInformation().
To initialize, call LoadAndUpdate(). Afterwards, all other functions are available.
To save the changes back to disk, call Save().

Summary

NaturalDocs:: Menu	A package handling the menu’s contents and state.
Variables
menuSynonyms	A hash of the text synonyms for the menu tokens.
indexSynonyms	A hash of the text synonyms for the index modifiers.
indexNames	A hash of text equivalents of the possible index types.
hasChanged	Whether the menu changed or not, regardless of why.
menu	The parsed menu file.
defaultTitlesChanged	A hash of default titles that have changed, since OnDefaultTitleChange() will be called before LoadAndUpdate().
title	The title of the menu.
subTitle	The sub-title of the menu.
footer	The footer for the documentation.
indexes	An existence hash of all the defined index types appearing in the menu.
previousIndexes	An existence hash of all the indexes that appeared in the menu last time.
Files
NaturalDocs_Menu. txt	The file used to generate the menu.
NaturalDocs. m	The file used to store the previous state of the menu so as to detect changes.
File Functions
LoadAndUpdate	Loads the menu file from NaturalDocs_Menu.txt and updates it.
LoadUnchanged	Loads the menu, assuming neither the menu file nor any of the source files have changed, and thus it definitely doesn’t need to be updated.
Save	Writes the changes to the menu files.
Information Functions
HasChanged	Returns whether the menu has changed or not.
Content	Returns the parsed menu as an arrayref of NaturalDocs::Menu::Entry objects.
Title	Returns the title of the menu, or undef if none.
SubTitle	Returns the sub-title of the menu, or undef if none.
Footer	Returns the footer of the documentation, or undef if none.
Indexes	Returns an existence hashref of all the indexes appearing in the menu.
PreviousIndexes	Returns an existence hashref of all the indexes that previously appeared in the menu.
Event Handlers	These functions are called by NaturalDocs::Project only.
OnFileChange	Called by NaturalDocs::Project if it detects that the menu file has changed.
OnDefaultTitleChange	Called by NaturalDocs::Project if the default menu title of a source file has changed.
Support Functions
ParseMenuFile	Loads and parses the menu file.
SaveMenuFile	Saves the current menu to NaturalDocs_Menu.txt.
ParsePreviousMenuStateFile	Loads and parses the previous menu state file.
SavePreviousMenuStateFile	Saves changes to NaturalDocs.m.
AddMissingFiles	Adds all files with Natural Docs content to the menu that are not already on it.
HandleErrors	Handles errors appearing in the menu file.
WriteEntries	A recursive function to write the contents of an arrayref of NaturalDocs::Menu::Entry objects to disk.

Variables

menuSynonyms

my %menuSynonyms

A hash of the text synonyms for the menu tokens. The keys are the lowercase synonyms, and the values are one of the Menu Item Types.

indexSynonyms

my %indexSynonyms

A hash of the text synonyms for the index modifiers. The keys are the all lowercase synonyms, and the values are the associated Topic Types.

indexNames

my %indexNames

A hash of text equivalents of the possible index types. The keys are the Topic Types, and the values are the strings.

hasChanged

my $hasChanged

Whether the menu changed or not, regardless of why.

defaultTitlesChanged

my %defaultTitlesChanged

A hash of default titles that have changed, since OnDefaultTitleChange() will be called before LoadAndUpdate(). Collects them to be applied later.

title

my $title

The title of the menu.

subTitle

my $subTitle

The sub-title of the menu.

footer

my $footer

The footer for the documentation.

indexes

my %indexes

An existence hash of all the defined index types appearing in the menu. Keys are the Topic Types or * for the general index.

previousIndexes

my %previousIndexes

An existence hash of all the indexes that appeared in the menu last time. Keys are the Topic Types or * for the general index.

Files

NaturalDocs_Menu. txt

The file used to generate the menu.

Format

The file is plain text. Blank lines can appear anywhere and are ignored. Tags and their content must be completely contained on one line with the exception of Group’s braces.

# [comment]

The file supports single-line comments via #. They can appear alone on a line or after content.

Title: [title]
SubTitle: [subtitle]
Footer: [footer]

The menu title, subtitle, and footer are specified as above. Each can only be specified once, with subsequent ones being ignored. Subtitle is ignored if Title is not present.

File: [file title] ([file name])
File: [file title] (auto-title, [file name])

Files are specified as above. If “auto-title,” precedes the file name in the parenthesis, the file title is ignored and the default is used instead. If not specified, the file title overrides the default title.

Group: [name]
Group: [name] { ... }

Groups are specified as above. If no braces are specified, the group’s content is everything that follows until the end of the file, the next group (braced or unbraced), or the closing brace of a parent group. Group braces are the only things in this file that can span multiple lines.

There is no limitations on where the braces can appear. The opening brace can appear after the group tag, on its own line, or preceding another tag on a line. Similarly, the closing brace can appear after another tag or on its own line. Being bitchy here would just get in the way of quick and dirty editing; the package will clean it up automatically when it writes it back to disk.

Text: [text]

Arbitrary text is specified as above. As with other tags, everything must be contained on the same line.

Link: [URL]
Link: [title] ([URL])

External links can be specified as above. If the titled form is not used, the URL is used as the title.

Index: [name]
[modifier] Index: [name]

Indexes are specified with the types above. Valid modifiers are defined in indexSynonyms and include Function and Class. If no modifier is specified, the line specifies a general index.

NaturalDocs. m

The file used to store the previous state of the menu so as to detect changes. Is named NaturalDocs.m instead of something like NaturalDocs.menu to avoid confusion with NaturalDocs_Menu.txt. This one is not user-editable so we don’t want people opening it by accident.

[file version]

The first line is the file version number from NaturalDocs::Settings::FileVersion().

[index type] tab [index type] tab ...

The next line is a tab-separated list of all the index types present in the menu. They are the values of the Topic Types or

for the general index.

That’s all for now. In the future this will store the entire previous state so auto-locking can be applied. The file version will have to be incremented though.

File Functions

LoadAndUpdate

sub LoadAndUpdate

Loads the menu file from NaturalDocs_Menu.txt and updates it. If a file is deleted or no longer has Natural Docs content, it is removed from the menu. If files are added or get Natural Docs content, they are added to the end. If there are groups defined, the new ones will be added in group Other.

LoadUnchanged

sub LoadUnchanged

Loads the menu, assuming neither the menu file nor any of the source files have changed, and thus it definitely doesn’t need to be updated.

Save

sub Save

Writes the changes to the menu files.

Information Functions

HasChanged

sub HasChanged

Returns whether the menu has changed or not.

Content

sub Content

Returns the parsed menu as an arrayref of NaturalDocs::Menu::Entry objects. Do not change the arrayref.

The arrayref will not contain MENU_TITLE and MENU_SUBTITLE entries. Use the Title() and SubTitle() functions instead.

Title

sub Title

Returns the title of the menu, or undef if none.

SubTitle

sub SubTitle

Returns the sub-title of the menu, or undef if none.

Footer

sub Footer

Returns the footer of the documentation, or undef if none.

Indexes

sub Indexes

Returns an existence hashref of all the indexes appearing in the menu. The keys are the Topic Types or * for the general index. Do not change the arrayref.

PreviousIndexes

sub PreviousIndexes

Returns an existence hashref of all the indexes that previously appeared in the menu. The keys are the Topic Types or * for the general index. Do not change the arrayref.

Event Handlers

These functions are called by NaturalDocs::Project only. You don’t need to worry about calling them. For example, when changing the default menu title of a file, you only need to call NaturalDocs::Project::SetDefaultMenuTitle(). That function will handle calling OnDefaultTitleChange().

OnFileChange

sub OnFileChange

Called by NaturalDocs::Project if it detects that the menu file has changed.

OnDefaultTitleChange

sub OnDefaultTitleChange #(file, title)

Called by NaturalDocs::Project if the default menu title of a source file has changed.

Parameters

file	The source file that had its default menu title changed.
title	The new title

Support Functions

ParseMenuFile

sub ParseMenuFile

Loads and parses the menu file.

Returns

The array ( hasGroups, errors, filesInMenu, trashAlert ).

hasGroups	Whether the menu uses groups or not.
errors	An arrayref of errors appearing in the file, each one being an NaturalDocs::Menu::Error object.
filesInMenu	An existence hashref of all the source files that appear in the menu. This parameter will always exist.
trashAlert	Will be true if the menu file had a significant number of file entries, but all of them resolved invalid. Use to protect against accidential menu file trashing due to mistakes in the command line.

Yeah, this method isn’t the best, but the alternatives would be to make them package variables (they aren’t needed outside of LoadAndUpdate()) or to make LoadAndUpdate() a huge beast function (which it was before this was split off.)

SaveMenuFile

sub SaveMenuFile

Saves the current menu to NaturalDocs_Menu.txt.

ParsePreviousMenuStateFile

sub ParsePreviousMenuStateFile

Loads and parses the previous menu state file.

SavePreviousMenuStateFile

sub SavePreviousMenuStateFile

Saves changes to NaturalDocs.m.

AddMissingFiles

sub AddMissingFiles #(filesInMenu, hasGroups)

Adds all files with Natural Docs content to the menu that are not already on it.

Parameters

filesInMenu	An existence hashref of all the files present in the menu.
hasGroups	Whether the menu uses groups or not. Determines whether new files will be added to the end or to a group named Other.

HandleErrors

sub HandleErrors #(errors)

Handles errors appearing in the menu file.

Parameters

errors

An arrayref of the errors as NaturalDocs::Menu::Error objects.

WriteEntries

sub WriteEntries #(entries, fileHandle, indentChars)

A recursive function to write the contents of an arrayref of NaturalDocs::Menu::Entry objects to disk.

Parameters

entries	The arrayref of menu entries to write.
fileHandle	The handle to the output file.
indentChars	The indentation characters to add before each line. It is not the number of characters, it is the characters themselves. Use undef for none.