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. Also, LoadAndUpdate() will call NaturalDocs::Settings->GenerateDirectoryNames().
To save the changes back to disk, call Save().

Summary

NaturalDocs:: Menu	A package handling the menu’s contents and state.
Constants
Variables
menuSynonyms	A hash of the text synonyms for the menu tokens.
hasChanged	Whether the menu changed or not, regardless of why.
fileChanged	Whether the menu file has changed, usually meaning the user edited it.
menu	The parsed menu file.
defaultTitlesChanged	An existence 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.
bannedIndexes	An existence hash of all the indexes that the user has manually deleted, and thus should not be added back to the menu automatically.
Files
Menu.txt	The file used to generate the menu.
PreviousMenuState.nd	The file used to store the previous state of the menu so as to detect changes.
File Functions
LoadAndUpdate	Loads the menu file from disk and updates it.
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.
FilesInMenu	Returns a hashref of all the files present 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
LoadMenuFile	Loads and parses the menu file Menu.txt.
SaveMenuFile	Saves the current menu to Menu.txt.
WriteMenuEntries	A recursive function to write the contents of an arrayref of NaturalDocs::Menu::Entry objects to disk.
LoadPreviousMenuStateFile	Loads and parses the previous menu state file.
SavePreviousMenuStateFile	Saves changes to PreviousMenuState.nd.
WritePreviousMenuStateEntries	A recursive function to write the contents of an arrayref of NaturalDocs::Menu::Entry objects to disk.
CheckForTrashedMenu	Checks the menu to see if a significant number of file entries didn’t resolve to actual files, and if so, saves a backup of the menu and issues a warning.
Auto-Adjustment Functions
ResolveInputDirectories	Detects if the input directories in the menu file match those in the command line, and if not, tries to resolve them.
ResolveRelativeInputDirectories	Resolves pre-1.16 relative input directories to the input directories available.
ResolveFile	Tests a relative path against a list of directories.
LockUserTitleChanges	Detects if the user manually changed any file titles, and if so, automatically locks them with <MENU_FILE_NOAUTOTITLE>.
FlagAutoTitleChanges	Finds which files have auto-titles that changed and flags their groups for updating with <MENU_GROUP_UPDATETITLES> and <MENU_GROUP_UPDATEORDER>.
AutoPlaceNewFiles	Adds files to the menu that aren’t already on it, attempting to guess where they belong.
MatchDirectoriesAndGroups	Determines which groups files in certain directories should be placed in.
RemoveDeadFiles	Removes files from the menu that no longer exist or no longer have Natural Docs content.
BanAndUnbanIndexes	Adjusts the indexes that are banned depending on if the user added or deleted any.
AddAndRemoveIndexes	Automatically adds and removes index entries on the menu as necessary.
RemoveDeadGroups	Removes groups with less than two entries.
RemoveIfDead	Checks a group and all its sub-groups for life and remove any that are dead.
DetectIndexGroups	Finds groups that are primarily used for indexes and gives them the <MENU_GROUP_ISINDEXGROUP> flag.
CreateDirectorySubGroups	Where possible, creates sub-groups based on directories for any long groups that have <MENU_GROUP_UPDATESTRUCTURE> set.
DetectOrder	Detects the order of the entries in all groups that have the <MENU_GROUP_UPDATEORDER> flag set.
GenerateAutoFileTitles	Creates titles for the unlocked file entries in all groups that have the <MENU_GROUP_UPDATETITLES> flag set.
ResortGroups	Resorts all groups that have <MENU_GROUP_UPDATEORDER> set.
CompareEntries	A comparison function for use in sorting.
SharedDirectoriesOf	Returns an array of all the directories shared by the files in the group.

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.

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

The file format version, 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. Format must be the first entry in the file. If it’s not present, it’s assumed the menu is from version 0.95 or earlier, since it was added with 1.0.

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

Files are specified as above. If “no auto-title” is specified, the title on the line is used. If not, the title is ignored and the default file title is used instead. Auto-title defaults to on, so specifying “auto-title” is for compatibility only.

Group: [title]
Group: [title] { ... }

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 topic keywords, either singular or plural. If the modifier is “General” or not specified, the line specifies a general index.

Don't Index: [type]
Don't Index: [type], [type], ...

The option above prevents indexes that exist but are not on the menu from being automatically added. “General” is used to specify the general index. Commas aren’t required.

Data: 1([obscured: [directory name]///[input directory]])

Used to store non-user editable data. The leading 1 specifies it as storage for the input directories used in the last run and their names. This allows menu files to be shared across machines, since the names will be consistent and the directories can be used to convert filenames to the local machine’s paths. We don’t want this user-editable because they may think changing it changes the input directories, when it doesn’t. Also, changing it without changing all the paths screws up resolving.

Revisions

1.16

File names are now absolute instead of relative. Prior to 1.16 only one input directory was allowed, so they could be relative.
Data keywords introduced to store input directories and their names.

1.14

Renamed this file from NaturalDocs_Menu.txt to Menu.txt.

1.1

Added the “don’t index” line.

This is also the point where indexes were automatically added and removed, so all index entries from prior revisions were manually added and are not guaranteed to contain anything.

1.0

Added the format line.
Added the “no auto-title” attribute.
Changed the file entry default to auto-title.

This is also the point where auto-organization and better auto-titles were introduced. All groups in prior revisions were manually added, with the exception of a top-level Other group where new files were automatically added if there were groups defined.

0.9

Added index entries.

PreviousMenuState.nd

The file used to store the previous state of the menu so as to detect changes.

[BINARY_FORMAT]

The file is binary, so the first byte is the <BINARY_FORMAT> token.

[app version]

Immediately after is the application version it was generated with. Manage with the binary functions in NaturalDocs::Version.

[UInt8: 0 (end group)]
[UInt8: MENU_FILE] [UInt8: noAutoTitle] [AString16: title] [AString16: target]
[UInt8: MENU_GROUP] [AString16: title]
[UInt8: MENU_INDEX] [AString16: title] [UInt8: type (0 for general)]
[UInt8: MENU_LINK] [AString16: title] [AString16: url]
[UInt8: MENU_TEXT] [AString16: text]

The first UInt8 of each following line is either zero or one of the <Menu Entry Types>. What follows is contextual. AString16s are big-endian UInt16’s followed by that many ASCII characters.

There are no entries for title, subtitle, or footer. Only the entries present in menu.

Dependencies

Because the type is represented by a UInt8, the <Menu Entry Types> must all be <= 255.
Because the index target is represented by a UInt8, the <Topic Types> must all be <= 255.

Revisions

1.16

The file targets are now absolute. Prior to 1.16, they were relative to the input directory since only one was allowed.

1.14

The file was renamed from NaturalDocs.m to PreviousMenuState.nd and moved into the Data subdirectory.

1.0

The file’s format was completely redone. Prior to 1.0, the file was a text file consisting of the app version and a line which was a tab-separated list of the indexes present in the menu. * meant the general index.

0.95

Change the file version to match the app version. Prior to 0.95, the version line was 1. Test for “1” instead of “1.0” to distinguish.

0.9

The file was added to the project. Prior to 0.9, it didn’t exist.

LoadPreviousMenuStateFile

sub LoadPreviousMenuStateFile

Loads and parses the previous menu state file.

Note that this is not affected by NaturalDocs::Settings->RebuildData(). Since this is used to detect user changes, the information here can’t be ditched on a whim.

Returns

The array ( previousMenu, previousIndexes, previousFiles ).

previousMenu	A <MENU_GROUP> NaturalDocs::Menu::Entry object, similar to menu, which contains the entire previous menu.
previousIndexes	An existence hashref of the indexes present in the previous menu. The keys are the <Topic Types> or ‘*’ for general.
previousFiles	A hashref of the files present in the previous menu. The keys are the file names, and the entries are references to its object in previousMenu.

If there is no data available on a topic, it will be undef. For example, if the file didn’t exist, all three will be undef. If the file was from 0.95 or earlier, previousIndexes will be set but the other two would be undef.

NaturalDocs:: Menu

Usage and Dependencies

Constants

Variables

menuSynonyms

hasChanged

fileChanged

menu

defaultTitlesChanged

title

subTitle

footer

indexes

previousIndexes

bannedIndexes

Files

Menu.txt

Format

Revisions

1.16

1.14

1.1

1.0

0.9

PreviousMenuState.nd

Dependencies

Revisions

1.16

1.14

1.0

0.95

0.9

File Functions

LoadAndUpdate

Save

Information Functions

HasChanged

Content

Title

SubTitle

Footer

Indexes

PreviousIndexes

FilesInMenu

Event Handlers

OnFileChange

OnDefaultTitleChange

Parameters

Support Functions

LoadMenuFile

Returns

SaveMenuFile

WriteMenuEntries

Parameters

LoadPreviousMenuStateFile

Returns

SavePreviousMenuStateFile

WritePreviousMenuStateEntries

Parameters

CheckForTrashedMenu

Parameters

Auto-Adjustment Functions

ResolveInputDirectories

Parameters

ResolveRelativeInputDirectories

ResolveFile

Parameters

LockUserTitleChanges

Parameters

FlagAutoTitleChanges

AutoPlaceNewFiles

Parameters

MatchDirectoriesAndGroups

Returns

RemoveDeadFiles

Returns

BanAndUnbanIndexes

AddAndRemoveIndexes

RemoveDeadGroups

RemoveIfDead