Natural Docs Version 1.0 |
NaturalDocs:: MenuA package handling the menu’s contents and state. Usage and Dependencies
Summary
ConstantsmenuSynonyms
A hash of the text synonyms for the menu tokens. The keys are the lowercase synonyms, and the values are one of the Menu Entry Types. 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
A hash of text equivalents of the possible index types. The keys are the Topic Types, and the values are the strings. 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 not contain objects for MENU_TITLE, MENU_SUBTITLE, or MENU_FOOTER entries. Those will be stored in the title, subTitle, and footer variables instead. 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 file names. 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
An existence hash of all the indexes that appeared in the menu last time. Keys are the Topic Types or * for the general index. NaturalDocs_Menu.txtThe file used to generate the menu. FormatThe 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 defined in indexSynonyms and include Function and Class. If no modifier is specified, the line specifies a general index. RevisionsPrior to 1.0, there was no Format line. Use that to detect pre-1.0 files. Also:
Prior to 0.9, there were no Index entries. NaturalDocs.mThe 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. [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
RevisionsPrior 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. Prior to 0.95, the version line was 1. Test for “1” instead of “1.0” to distinguish. Prior to 0.9, this file didn’t exist. 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. 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
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 HandlersThese 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
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. Parameters
LoadMenuFile
Loads and parses the menu file NaturalDocs_Menu.txt. This will fill menu, title, subTitle, footer, and indexes. ReturnsThe array ( errors, filesInMenu, oldLockedTitles ).
SaveMenuFile
Saves the current menu to NaturalDocs_Menu.txt. WriteMenuEntries
A recursive function to write the contents of an arrayref of NaturalDocs::Menu::Entry objects to disk. Parameters
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. ReturnsThe array ( previousMenu, previousIndexes, previousFiles ).
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. SavePreviousMenuStateFile
Saves changes to NaturalDocs.m. WritePreviousMenuStateEntries
A recursive function to write the contents of an arrayref of NaturalDocs::Menu::Entry objects to disk. Parameters
HandleErrors
Handles errors appearing in the menu file. Parameters
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. Parameters
LockUserTitleChanges
Detects if the user manually changed any file titles, and if so, automatically locks them with MENU_FILE_NOAUTOTITLE. Parameters
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. 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
MatchDirectoriesAndGroups
Determines which groups files in certain directories should be placed in. ReturnsA 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. 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
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
ReturnsWhether the group was removed or not. 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. CreatePrefixSubGroups
Where possible, creates sub-groups based on name prefix for any long groups that have the MENU_GROUP_UPDATESTRUCTURE flag set. Clears the flag for any group that becomes short enough to not need any more sub-groups, but leaves it for the rest. ImportantThis function isn’t ready for prime time yet. While it works somewhat on its own, it needs to be improved and to integrate better with the directory sub-groups. Probably most importantly, AutoPlaceNewFiles() needs to be aware of it. DetectOrder
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. 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
GenerateAutoFileTitles
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
ResortGroups
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
CompareEntries
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. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||