[ Home | Main Table Of Contents | Table Of Contents | Keyword Index ]

cmdr-user-helpformats(n) 1.2 doc "Cmdr, a framework for command line parsing and dispatch"

Name

cmdr-user-helpformats - Cmdr - Writing custom help formats

Table Of Contents

Synopsis

  • package require cmdr::help

Description

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.

Background

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.

API

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:

::cmdr::help::format::<foo> root width help

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.

cmdr::officer root

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.

integer width

The number of columns to format the help towards.

dictionary help

A dictonary holding the help information to format. For more details see section Help Dictionary.

Help Dictionary

The help information generated by various places of the framework is a dictionary containing the following keys:

arguments

A list of strings, the names of the command arguments, in order. These names are keys into the parameters sub-dictionary.

desc

The command's description, i.e. help text.

opt2para

A dictionary mapping option flags to option names. These names are keys into the parameters sub-dictionary.

options

A dictionary mapping option names to their descriptions.

parameters

A dictionary mapping parameter names to their definition. Each definition is a dictionary containing the keys below. See also package cmdr::parameter.

cmdline

Output of method cmdline.

code

Output of method code.

default

Output of method default.

defered

Output of method defered.

description

Output of method description.

documented

Output of method documented.

flags

A dictionary mapping flag names to flag types, i.e. primary, alias, or inverted.

generator

Output of method generator.

interactive

Output of method interactive.

isbool

Output of method isbool.

label

Output of method label.

list

Output of method list.

ordered

Output of method ordered.

presence

Output of method presence.

prompt

Output of method prompt.

required

Output of method required.

threshold

Output of method threshold.

type

Output of method type.

validator

Output of method validator.

sections

A list of sections the command belongs to. Each section name is a list itself, the path of the section and sub-sections.

states

A list of strings, the names of the command's hidden state parameters. These names are keys into the parameters sub-dictionary.

Example

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]
}

Bugs, Ideas, Feedback

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.

Keywords

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