[ 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

- ::cmdr::help::format::<foo> root width 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

## Copyright

Copyright © 2013-2016 Andreas Kupries
Copyright © 2013-2016 Documentation, Andreas Kupries