NaturalDocs::Menu

A package handling the menu’s contents and state.

Usage and Dependencies

Summary
NaturalDocs::MenuA package handling the menu’s contents and state.
Constants
Variables
hasChangedWhether the menu changed or not, regardless of why.
menuThe parsed menu file.
defaultTitlesChangedAn existence hash of default titles that have changed, since OnDefaultTitleChange() will be called before LoadAndUpdate().
titleThe title of the menu.
subTitleThe sub-title of the menu.
footerThe footer for the documentation.
timestampTextThe timestamp for the documentation, stored as the final output text.
timestampCodeThe timestamp for the documentation, storted as the symbolic code.
indexesAn existence hash of all the defined index TopicTypes appearing in the menu.
previousIndexesAn existence hash of all the index TopicTypes that appeared in the menu last time.
bannedIndexesAn existence hash of all the index TopicTypes that the user has manually deleted, and thus should not be added back to the menu automatically.
Files
Menu.txtThe file used to generate the menu.
PreviousMenuState.ndThe file used to store the previous state of the menu so as to detect changes.
File Functions
LoadAndUpdateLoads the menu file from disk and updates it.
SaveWrites the changes to the menu files.
Information Functions
HasChangedReturns whether the menu has changed or not.
ContentReturns the parsed menu as an arrayref of NaturalDocs::Menu::Entry objects.
TitleReturns the title of the menu, or undef if none.
SubTitleReturns the sub-title of the menu, or undef if none.
FooterReturns the footer of the documentation, or undef if none.
TimeStampReturns the timestamp text of the documentation, or undef if none.
IndexesReturns an existence hashref of all the index TopicTypes appearing in the menu.
PreviousIndexesReturns an existence hashref of all the index TopicTypes that previously appeared in the menu.
FilesInMenuReturns a hashref of all the files present in the menu.
Event HandlersThese functions are called by NaturalDocs::Project only.
OnDefaultTitleChangeCalled by NaturalDocs::Project if the default menu title of a source file has changed.
Support Functions
LoadMenuFileLoads and parses the menu file Menu.txt.
SaveMenuFileSaves the current menu to Menu.txt.
WriteMenuEntriesA recursive function to write the contents of an arrayref of NaturalDocs::Menu::Entry objects to disk.
LoadPreviousMenuStateFileLoads and parses the previous menu state file.
SavePreviousMenuStateFileSaves changes to PreviousMenuState.nd.
WritePreviousMenuStateEntriesA recursive function to write the contents of an arrayref of NaturalDocs::Menu::Entry objects to disk.
CheckForTrashedMenuChecks 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.
GenerateTimestampTextGenerates timestampText from timestampCode with the current date.
ConvertAmpCharsReplaces certain characters in the string with their entities and returns it.
RestoreAmpCharsReplaces entity characters in the string with their original characters and returns it.
Auto-Adjustment Functions
ResolveInputDirectoriesDetects if the input directories in the menu file match those in the command line, and if not, tries to resolve them.
ResolveRelativeInputDirectoriesResolves relative input directories to the input directories available.
ResolveFileTests a relative path against a list of directories.
LockUserTitleChangesDetects if the user manually changed any file titles, and if so, automatically locks them with MENU_FILE_NOAUTOTITLE.
FlagAutoTitleChangesFinds which files have auto-titles that changed and flags their groups for updating with MENU_GROUP_UPDATETITLES and MENU_GROUP_UPDATEORDER.
AutoPlaceNewFilesAdds files to the menu that aren’t already on it, attempting to guess where they belong.
MatchDirectoriesAndGroupsDetermines which groups files in certain directories should be placed in.
RemoveDeadFilesRemoves files from the menu that no longer exist or no longer have Natural Docs content.
BanAndUnbanIndexesAdjusts the indexes that are banned depending on if the user added or deleted any.
AddAndRemoveIndexesAutomatically adds and removes index entries on the menu as necessary.
RemoveDeadGroupsRemoves groups with less than two entries.
RemoveIfDeadChecks a group and all its sub-groups for life and remove any that are dead.
DetectIndexGroupsFinds groups that are primarily used for indexes and gives them the MENU_GROUP_ISINDEXGROUP flag.
CreateDirectorySubGroupsWhere possible, creates sub-groups based on directories for any long groups that have MENU_GROUP_UPDATESTRUCTURE set.
DetectOrderDetects the order of the entries in all groups that have the MENU_GROUP_UPDATEORDER flag set.
GenerateAutoFileTitlesCreates titles for the unlocked file entries in all groups that have the MENU_GROUP_UPDATETITLES flag set.
ResortGroupsResorts all groups that have MENU_GROUP_UPDATEORDER set.
CompareEntriesA comparison function for use in sorting.
SharedDirectoriesOfReturns an array of all the directories shared by the files in the group.

Constants

MAXFILESINGROUPThe maximum number of file entries that can be present in a group before it becomes a candidate for sub-grouping.
MINFILESINNEWGROUPThe minimum number of file entries that must be present in a group before it will be automatically created.  This is not the number of files that must be in a group before it’s deleted.

Variables

hasChanged

my $hasChanged

Whether the menu changed or not, regardless of why.

menu

my $menu

The parsed menu file.  Is stored as a MENU_GROUP NaturalDocs::Menu::Entry object, with the top-level entries being stored as the group’s content.  This is done because it makes a number of functions simpler to implement, plus it allows group flags to be set on the top-level.  However, it is exposed externally via Content() as an arrayref.

This structure will only contain objects for MENU_FILE, MENU_GROUP, MENU_TEXT, MENU_LINK, and MENU_INDEX entries.  Other types, such as MENU_TITLE, are stored in variables such as title.

defaultTitlesChanged

my %defaultTitlesChanged

An existence hash of default titles that have changed, since OnDefaultTitleChange() will be called before LoadAndUpdate().  Collects them to be applied later.  The keys are the FileNames.

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.

timestampText

my $timestampText

The timestamp for the documentation, stored as the final output text.

timestampCode

my $timestampCode

The timestamp for the documentation, storted as the symbolic code.

indexes

my %indexes

An existence hash of all the defined index TopicTypes appearing in the menu.

previousIndexes

my %previousIndexes

An existence hash of all the index TopicTypes that appeared in the menu last time.

bannedIndexes

my %bannedIndexes

An existence hash of all the index TopicTypes 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.

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.  All values in brackets below are encoded with entity characters.

# [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]
Timestamp: [timestamp code]

The file format version, menu title, subtitle, footer, and timestamp 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.

The timestamp code is as follows.

mSingle digit month, where applicable.  January is “1”.
mmAlways double digit month.  January is “01”.
monShort month word.  January is “Jan”.
monthLong month word.  January is “January”.
dSingle digit day, where applicable.  1 is “1”.
ddAlways double digit day.  1 is “01”.
dayDay with text extension.  1 is “1st”.
yyDouble digit year.  2006 is “06”.
yyyyFour digit year.  2006 is “2006”.
yearFour digit year.  2006 is “2006”.

Anything else is left literal in the output.

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

Files are specified as above.  If there is only one input directory, file names are relative.  Otherwise they are absolute.  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]
[topic type name] Index: [name]

Indexes are specified as above.  The topic type names can be either singular or plural.  General is assumed if not specified.

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

The option above prevents indexes that exist but are not on the menu from being automatically added.

Data: [number]([obscured data])

Used to store non-user editable data.

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

When there is more than one directory, these lines store 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.

Data: 2([obscured: [directory name])

When there is only one directory and its name is not “default”, this stores the name.

Entities

&Ampersand.
&lparen;Left parenthesis.
&rparen;Right parenthesis.
{Left brace.
}Right brace.

Revisions

1.4

  • Added Timestamp property.
  • Values are now encoded with entity characters.

1.3

  • File names are now relative again if there is only one input directory.
  • Data: 2(...) added.
  • Can’t use synonyms like “copyright” for “footer” or “sub-title” for “subtitle”.
  • ”Don’t Index” line now requires commas to separate them, whereas it tolerated just spaces before.

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.

Break in support

Releases prior to 1.0 are no longer supported.  Why?

  • They don’t have a Format: line, which is required by NaturalDocs::ConfigFile, although I could work around this if I needed to.
  • No significant number of downloads for pre-1.0 releases.
  • Code simplification.  I don’t have to bridge the conversion from manual-only menu organization to automatic.

0.9

  • Added index entries.

PreviousMenuState.nd

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

Format

[BINARY_FORMAT]
[VersionInt: app version]

First is the standard BINARY_FORMAT VersionInt header.

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

The first UInt8 of each following line is either zero or one of the <Menu Entry Types>.  What follows is contextual.

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

See Also

File Format Conventions

Dependencies

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

Revisions

1.52

  • All AString16s were changed to UString16s.

1.3

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.

Break in support

Pre-1.0 files are no longer supported.  There was no significant number of downloads for pre-1.0 releases, and this eliminates a separate code path for them.

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.

File Functions

LoadAndUpdate

sub LoadAndUpdate

Loads the menu file from disk and updates it.  Will add, remove, rearrange, and remove auto-titling from entries as necessary.  Will also call NaturalDocs::Settings->GenerateDirectoryNames().

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 only contain MENU_FILE, MENU_GROUP, MENU_INDEX, MENU_TEXT, and MENU_LINK entries.  Entries such as MENU_TITLE are parsed out and are only accessible via functions such as Title().

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.

TimeStamp

sub TimeStamp

Returns the timestamp text of the documentation, or undef if none.

Indexes

sub Indexes

Returns an existence hashref of all the index TopicTypes appearing in the menu.  Do not change the hashref.

PreviousIndexes

sub PreviousIndexes

Returns an existence hashref of all the index TopicTypes that previously appeared in the menu.  Do not change the hashref.

FilesInMenu

sub FilesInMenu

Returns a hashref of all the files present in the menu.  The keys are the FileNames, and the values are references to their NaturalDocs::Menu::Entry objects.

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().

OnDefaultTitleChange

sub OnDefaultTitleChange #(file)

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

Parameters

fileThe source FileName that had its default menu title changed.

Support Functions

LoadMenuFile

sub LoadMenuFile

Loads and parses the menu file Menu.txt.  This will fill menu, title, subTitle, footer, timestampText, timestampCode, indexes, and bannedIndexes.  If there are any errors in the file, they will be recorded with NaturalDocs::ConfigFile->AddError().

Returns

The array ( inputDirectories, relativeFiles, onlyDirectoryName ) or an empty array if the file doesn’t exist.

inputDirectoriesA hashref of all the input directories and their names stored in the menu file.  The keys are the directories and the values are their names.  Undef if none.
relativeFilesWhether the menu uses relative file names.
onlyDirectoryNameThe name of the input directory if there is only one.

SaveMenuFile

sub SaveMenuFile

Saves the current menu to Menu.txt.

WriteMenuEntries

sub WriteMenuEntries #(entries,
fileHandle,
indentChars,
relativeFiles)

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

Parameters

entriesThe arrayref of menu entries to write.
fileHandleThe handle to the output file.
indentCharsThe indentation characters to add before each line.  It is not the number of characters, it is the characters themselves.  Use undef for none.
relativeFilesWhether to use relative file names.

LoadPreviousMenuStateFile

sub LoadPreviousMenuStateFile

Loads and parses the previous menu state file.

Returns

The array ( previousMenu, previousIndexes, previousFiles ) or an empty array if there was a problem with the file.

previousMenuA MENU_GROUP NaturalDocs::Menu::Entry object, similar to menu, which contains the entire previous menu.
previousIndexesAn existence hashref of the index TopicTypes present in the previous menu.
previousFilesA hashref of the files present in the previous menu.  The keys are the FileNames, and the entries are references to its object in previousMenu.

SavePreviousMenuStateFile

sub SavePreviousMenuStateFile

Saves changes to PreviousMenuState.nd.

WritePreviousMenuStateEntries

sub WritePreviousMenuStateEntries #(entries,
fileHandle)

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

Parameters

entriesThe arrayref of menu entries to write.
fileHandleThe handle to the output file.

CheckForTrashedMenu

sub CheckForTrashedMenu #(numberOriginallyInMenu,
numberRemoved)

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.

Parameters

numberOriginallyInMenuA count of how many file entries were in the menu orignally.
numberRemovedA count of how many file entries were removed from the menu.

GenerateTimestampText

sub GenerateTimestampText

Generates timestampText from timestampCode with the current date.

ConvertAmpChars

sub ConvertAmpChars #(string text,
int flags) => string

Replaces certain characters in the string with their entities and returns it.

Parameters

textThe text to convert.
flagsThe flags of any additional characters to convert.

Flags

  • CONVERT_PARENTHESIS
  • CONVERT_COMMAS
  • CONVERT_COLONS

Returns

The string with the amp chars converted.

RestoreAmpChars

sub RestoreAmpChars #(string text) => string

Replaces entity characters in the string with their original characters and returns it.  This will restore all amp chars regardless of the flags passed to ConvertAmpChars().

Auto-Adjustment Functions

ResolveInputDirectories

sub ResolveInputDirectories #(inputDirectoryNames)

Detects if the input directories in the menu file match those in the command line, and if not, tries to resolve them.  This allows menu files to work across machines, since the absolute paths won’t be the same but the relative ones should be.

Parameters

inputDirectoryNamesA hashref of the input directories appearing in the menu file, or undef if none.  The keys are the directories, and the values are their names.  May be undef.

ResolveRelativeInputDirectories

sub ResolveRelativeInputDirectories

Resolves relative input directories to the input directories available.

ResolveFile

sub ResolveFile #(relativePath,
possibleBases,
possibleBaseScores)

Tests a relative path against a list of directories.  Adds one to the score of each base where there is a match.

Parameters

relativePathThe relative file name to test.
possibleBasesAn arrayref of bases to test it against.
possibleBaseScoresAn arrayref of scores to adjust.  The score indexes should correspond to the base indexes.

LockUserTitleChanges

sub LockUserTitleChanges #(previousMenuFiles)

Detects if the user manually changed any file titles, and if so, automatically locks them with MENU_FILE_NOAUTOTITLE.

Parameters

previousMenuFilesA hashref of the files from the previous menu state.  The keys are the FileNames, and the values are references to their NaturalDocs::Menu::Entry objects.

FlagAutoTitleChanges

sub FlagAutoTitleChanges

Finds which files have auto-titles that changed and flags their groups for updating with MENU_GROUP_UPDATETITLES and MENU_GROUP_UPDATEORDER.

AutoPlaceNewFiles

sub AutoPlaceNewFiles #(fileInMenu)

Adds files to the menu that aren’t already on it, attempting to guess where they belong.

New files are placed after a dummy MENU_ENDOFORIGINAL entry so that they don’t affect the detected order.  Also, the groups they’re placed in get MENU_GROUP_UPDATETITLES, MENU_GROUP_UPDATESTRUCTURE, and MENU_GROUP_UPDATEORDER flags.

Parameters

filesInMenuAn existence hash of all the FileNames present in the menu.

MatchDirectoriesAndGroups

sub MatchDirectoriesAndGroups

Determines which groups files in certain directories should be placed in.

Returns

A hashref.  The keys are the directory names, and the values are references to the group objects they should be placed in.

This only repreesents directories that currently have files on the menu, so it shouldn’t be assumed that every possible directory will exist.  To match, you should first try to match the directory, and then strip the deepest directories one by one until there’s a match or there’s none left.  If there’s none left, use the root group menu.

RemoveDeadFiles

sub RemoveDeadFiles

Removes files from the menu that no longer exist or no longer have Natural Docs content.

Returns

The number of file entries removed.

BanAndUnbanIndexes

sub BanAndUnbanIndexes

Adjusts the indexes that are banned depending on if the user added or deleted any.

AddAndRemoveIndexes

sub AddAndRemoveIndexes

Automatically adds and removes index entries on the menu as necessary.  DetectIndexGroups() should be called beforehand.

RemoveDeadGroups

sub RemoveDeadGroups

Removes groups with less than two entries.  It will always remove empty groups, and it will remove groups with one entry if it has the MENU_GROUP_UPDATESTRUCTURE flag.

RemoveIfDead

sub RemoveIfDead #(groupEntry,
parentGroupEntry,
parentGroupIndex)

Checks a group and all its sub-groups for life and remove any that are dead.  Empty groups are removed, and groups with one entry and the MENU_GROUP_UPDATESTRUCTURE flag have their entry moved to the parent group.

Parameters

groupEntryThe group to check for possible deletion.
parentGroupEntryThe parent group to move the single entry to if necessary.
parentGroupIndexThe index of the group in its parent.

Returns

Whether the group was removed or not.

DetectIndexGroups

sub DetectIndexGroups

Finds groups that are primarily used for indexes and gives them the MENU_GROUP_ISINDEXGROUP flag.

CreateDirectorySubGroups

sub CreateDirectorySubGroups

Where possible, creates sub-groups based on directories for any long groups that have MENU_GROUP_UPDATESTRUCTURE set.  Clears the flag afterwards on groups that are short enough to not need any more sub-groups, but leaves it for the rest.

DetectOrder

sub DetectOrder #(forceAll)

Detects the order of the entries in all groups that have the MENU_GROUP_UPDATEORDER flag set.  Will set one of the MENU_GROUP_FILESSORTED, MENU_GROUP_FILESANDGROUPSSORTED, MENU_GROUP_EVERYTHINGSORTED, or MENU_GROUP_UNSORTED flags.  It will always go for the most comprehensive sort possible, so if a group only has one entry, it will be flagged as MENU_GROUP_EVERYTHINGSORTED.

DetectIndexGroups() should be called beforehand, as the MENU_GROUP_ISINDEXGROUP flag affects how the order is detected.

The sort detection stops if it reaches a MENU_ENDOFORIGINAL entry, so new entries can be added to the end while still allowing the original sort to be detected.

Parameters

forceAllIf set, the order will be detected for all groups regardless of whether MENU_GROUP_UPDATEORDER is set.

GenerateAutoFileTitles

sub GenerateAutoFileTitles #(forceAll)

Creates titles for the unlocked file entries in all groups that have the MENU_GROUP_UPDATETITLES flag set.  It clears the flag afterwards so it can be used efficiently for multiple sweeps.

Parameters

forceAllIf set, forces all the unlocked file titles to update regardless of whether the group has the MENU_GROUP_UPDATETITLES flag set.

ResortGroups

sub ResortGroups #(forceAll)

Resorts all groups that have MENU_GROUP_UPDATEORDER set.  Assumes DetectOrder() and GenerateAutoFileTitles() have already been called.  Will clear the flag and any MENU_ENDOFORIGINAL entries on reordered groups.

Parameters

forceAllIf set, resorts all groups regardless of whether MENU_GROUP_UPDATEORDER is set.

CompareEntries

sub CompareEntries #(a,
b)

A comparison function for use in sorting.  Compares the two entries by their titles with StringCompare(), but in the case of a tie, puts MENU_FILE entries above MENU_GROUP entries.

SharedDirectoriesOf

sub SharedDirectoriesOf #(group)

Returns an array of all the directories shared by the files in the group.  If none, returns an empty array.

my $hasChanged
Whether the menu changed or not, regardless of why.
my $menu
The parsed menu file.
my %defaultTitlesChanged
An existence hash of default titles that have changed, since OnDefaultTitleChange() will be called before LoadAndUpdate().
sub OnDefaultTitleChange #(file)
Called by NaturalDocs::Project if the default menu title of a source file has changed.
sub LoadAndUpdate
Loads the menu file from disk and updates it.
my $title
The title of the menu.
my $subTitle
The sub-title of the menu.
my $footer
The footer for the documentation.
my $timestampText
The timestamp for the documentation, stored as the final output text.
my $timestampCode
The timestamp for the documentation, storted as the symbolic code.
my %indexes
An existence hash of all the defined index TopicTypes appearing in the menu.
A string representing a topic type as defined in Topics.txt.
my %previousIndexes
An existence hash of all the index TopicTypes that appeared in the menu last time.
my %bannedIndexes
An existence hash of all the index TopicTypes that the user has manually deleted, and thus should not be added back to the menu automatically.
sub Save
Writes the changes to the menu files.
sub HasChanged
Returns whether the menu has changed or not.
sub Content
Returns the parsed menu as an arrayref of NaturalDocs::Menu::Entry objects.
A class representing an entry in the menu.
sub Title
Returns the title of the menu, or undef if none.
sub SubTitle
Returns the sub-title of the menu, or undef if none.
sub Footer
Returns the footer of the documentation, or undef if none.
sub TimeStamp
Returns the timestamp text of the documentation, or undef if none.
sub Indexes
Returns an existence hashref of all the index TopicTypes appearing in the menu.
sub PreviousIndexes
Returns an existence hashref of all the index TopicTypes that previously appeared in the menu.
sub FilesInMenu
Returns a hashref of all the files present in the menu.
A package that manages information about the files in the source tree, as well as the list of files that have to be parsed and built.
sub LoadMenuFile
Loads and parses the menu file Menu.txt.
The file used to generate the menu.
sub SaveMenuFile
Saves the current menu to Menu.txt.
sub WriteMenuEntries #(entries,
fileHandle,
indentChars,
relativeFiles)
A recursive function to write the contents of an arrayref of NaturalDocs::Menu::Entry objects to disk.
sub LoadPreviousMenuStateFile
Loads and parses the previous menu state file.
sub SavePreviousMenuStateFile
Saves changes to PreviousMenuState.nd.
The file used to store the previous state of the menu so as to detect changes.
sub WritePreviousMenuStateEntries #(entries,
fileHandle)
A recursive function to write the contents of an arrayref of NaturalDocs::Menu::Entry objects to disk.
sub CheckForTrashedMenu #(numberOriginallyInMenu,
numberRemoved)
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.
sub GenerateTimestampText
Generates timestampText from timestampCode with the current date.
sub ConvertAmpChars #(string text,
int flags) => string
Replaces certain characters in the string with their entities and returns it.
sub RestoreAmpChars #(string text) => string
Replaces entity characters in the string with their original characters and returns it.
sub ResolveInputDirectories #(inputDirectoryNames)
Detects if the input directories in the menu file match those in the command line, and if not, tries to resolve them.
sub ResolveRelativeInputDirectories
Resolves relative input directories to the input directories available.
sub ResolveFile #(relativePath,
possibleBases,
possibleBaseScores)
Tests a relative path against a list of directories.
sub LockUserTitleChanges #(previousMenuFiles)
Detects if the user manually changed any file titles, and if so, automatically locks them with MENU_FILE_NOAUTOTITLE.
Whether the file is auto-titled or not.
sub FlagAutoTitleChanges
Finds which files have auto-titles that changed and flags their groups for updating with MENU_GROUP_UPDATETITLES and MENU_GROUP_UPDATEORDER.
The group should have its auto-titles regenerated.
The group should be resorted.
sub AutoPlaceNewFiles #(fileInMenu)
Adds files to the menu that aren’t already on it, attempting to guess where they belong.
sub MatchDirectoriesAndGroups
Determines which groups files in certain directories should be placed in.
sub RemoveDeadFiles
Removes files from the menu that no longer exist or no longer have Natural Docs content.
sub BanAndUnbanIndexes
Adjusts the indexes that are banned depending on if the user added or deleted any.
sub AddAndRemoveIndexes
Automatically adds and removes index entries on the menu as necessary.
sub RemoveDeadGroups
Removes groups with less than two entries.
sub RemoveIfDead #(groupEntry,
parentGroupEntry,
parentGroupIndex)
Checks a group and all its sub-groups for life and remove any that are dead.
sub DetectIndexGroups
Finds groups that are primarily used for indexes and gives them the MENU_GROUP_ISINDEXGROUP flag.
Whether the group is used primarily for MENU_INDEX entries.
sub CreateDirectorySubGroups
Where possible, creates sub-groups based on directories for any long groups that have MENU_GROUP_UPDATESTRUCTURE set.
The group should be checked for structural changes, such as being removed or being split into subgroups.
sub DetectOrder #(forceAll)
Detects the order of the entries in all groups that have the MENU_GROUP_UPDATEORDER flag set.
sub GenerateAutoFileTitles #(forceAll)
Creates titles for the unlocked file entries in all groups that have the MENU_GROUP_UPDATETITLES flag set.
sub ResortGroups #(forceAll)
Resorts all groups that have MENU_GROUP_UPDATEORDER set.
sub CompareEntries #(a,
b)
A comparison function for use in sorting.
sub SharedDirectoriesOf #(group)
Returns an array of all the directories shared by the files in the group.
These functions are called by NaturalDocs::Project only.
sub ParseForInformation #(file)
Parses the input file for information.
sub GenerateDirectoryNames #(hashref inputHints,
hashref imageHints)
Generates names for each of the input and image directories, which can later be retrieved with InputDirectoryNameOf() and ImageDirectoryNameOf().
A group.
A source file, relative to the source directory.
Arbitrary text.
A web link.
An index.
The title of the menu.
A string representing the absolute, platform-dependent path to a file.
A package to manage Natural Docs’ configuration files.
An 8-bit constant that’s used as the first byte of binary data files.
A comparable integer representing a version number.
sub TypeFromLegacy #(legacyInt)
Returns a TopicType for the passed legacy topic type integer.
sub SetDefaultMenuTitle #(file,
menuTitle)
Sets the FileName’s default menu title.
sub AddError #(message,
lineNumber)
Stores an error for the current configuration file.
A dummy entry that marks where the original group content ends.
The group’s files are sorted alphabetically.
The group’s files and sub-groups are sorted alphabetically.
All entries in the group are sorted alphabetically.
The group’s contents are not sorted.
sub StringCompare #(a,
b)
Compares two strings so that the result is good for proper sorting.
Close