cmdr-user-helpformats - Cmdr - Writing custom help formats
Welcome to the Cmdr project, written by Andreas Kupries.
For availability please read Cmdr - How To Get The Sources.
This document describes the API expected of help formats to make them usable within the Cmdr framework, and how to write a custom help format.
Readers interested in the standard help formats of the framework should read Cmdr - (Internal) Utilities for help text formatting and setup.
Help formats are Cmdr's way of converting in-memory information about a command hierarchy into something usable for human consumption and obviating the need for writing separate documentation, which may easily get out of sync with the specification.
The system was made extensible for while the standard formats listed in Cmdr - (Internal) Utilities for help text formatting and setup should cover the common cases, and the json format of Cmdr - Formatting help as JSON object is a general export, it is always possible to run into unprediced non-standard situations not covered as is.
For the framework to automatically pick up a new help format foo the package implementing it has to specify a single command ::cmdr::help::format::<foo>, and this package has to be loaded before the command hierarchy you want to use it for is specified.
In more detail:
This command, having access to the root actor of a command hierarchy, the number of columns to format the help towards, and a help data structure itself, has to return a string, the formatted help generated from the arguments.
The root officer of the command hierarchy. With the exception of by-category the standard formats do not use this argument. By providing it the format has access to the toplevel common blocks, allowing for the transfer of custom information from the specifiction to the format.
by-category for example looks for and uses the block *category-order* for when the user wishes to override the natural (alphabetical) order of display for the toplevel sections.
The number of columns to format the help towards.
A dictonary holding the help information to format. For more details see section Help Dictionary.
The help information generated by various places of the framework is a dictionary containing the following keys:
A list of strings, the names of the command arguments, in order. These names are keys into the parameters sub-dictionary.
The command's description, i.e. help text.
A dictionary mapping option flags to option names. These names are keys into the parameters sub-dictionary.
A dictionary mapping option names to their descriptions.
A dictionary mapping parameter names to their definition. Each definition is a dictionary containing the keys below. See also package cmdr::parameter.
Output of method cmdline.
Output of method code.
Output of method default.
Output of method defered.
Output of method description.
Output of method documented.
A dictionary mapping flag names to flag types, i.e. primary, alias, or inverted.
Output of method generator.
Output of method interactive.
Output of method isbool.
Output of method label.
Output of method list.
Output of method ordered.
Output of method presence.
Output of method prompt.
Output of method required.
Output of method threshold.
Output of method type.
Output of method validator.
A list of sections the command belongs to. Each section name is a list itself, the path of the section and sub-sections.
A list of strings, the names of the command's hidden state parameters. These names are keys into the parameters sub-dictionary.
As an example the implementation of the standard help format list is shown here.
# Entrypoint
proc ::cmdr::help::format::list {root width help} {
set result {}
dict for {cmd desc} $help {
lappend result [List $width $cmd $desc]
}
return [join $result \n]
}
# Main work procedure for commands
proc ::cmdr::help::format::List {width name command} {
dict with command {} ; # -> desc, options, arguments, parameters
# Short line.
lappend lines [string trimright " [join $name] [HasOptions $options][Arguments $arguments $parameters]"]
return [join $lines \n]
}
# Support procedures
proc ::cmdr::help::format::HasOptions {options} {
if {[dict size $options]} {
return "\[OPTIONS\] "
} else {
return {}
}
}
proc ::cmdr::help::format::Arguments {arguments parameters} {
set result {}
foreach a $arguments {
set v [dict get $parameters $a]
dict with v {} ; # -> code, desc, label
switch -exact -- $code {
+ { set text "<$label>" }
? { set text "\[<${label}>\]" }
+* { set text "<${label}>..." }
?* { set text "\[<${label}>...\]" }
}
lappend result $text
}
return [join $result]
}
Both the package(s) and this documentation will undoubtedly contain bugs and other problems. Please report such at Cmdr Tickets.
Please also report any ideas you may have for enhancements of either package(s) and/or documentation.
arguments, command hierarchy, command line completion, command line handling, command tree, editing command line, help for command line, hierarchy of commands, interactive command shell, optional arguments, options, parameters, processing command line, tree of commands
Copyright © 2013-2016 Andreas Kupries
Copyright © 2013-2016 Documentation, Andreas Kupries