[list_begin arguments]
[arg_def string name]
The user-visible name of the command (hierarchy).

[arg_def script actions]
The specification of the subordinate commands. On the command line
these are the toplevel commands of the application using the
hierarchy. Please read [term [vset TITLE_DSL]], (section "Officers")
for the details.


[list_end][comment arguments]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr] [method interactive] [opt [arg enable]]]

This command globally (de)activates the interactive parts of the
framework, as per the value of [arg enable].

[arg_def cmdr::config context]
The instance command of the [package cmdr::private] instance the configuration
will belong to.

[arg_def script spec]

Tcl-script specifying the parameters in detail. Please read
[term [vset TITLE_DSL]] (section "Parameters") for the details.

[list_end][comment arguments]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::config] [method interactive] [opt [arg enable]]]

Class method to change the global interaction default for the

[include parts/definitions.inc]
[manpage_begin [vset PROJECT]_dsl [vset MAN_SECTION] [vset VERSION]]
[include parts/module.inc]
[titledesc [vset TITLE_DSL]]
[description]
[include parts/welcome.inc]

This document is for users of the cmdr framework. It describes the
domain-specific language for the specification of command hierarchies
with commands and their parameters (options, and inputs).

[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
[section {Introductory examples}]

Instead of immediately diving into the full syntax of the
specification language first a few examples to demonstrate the general
look and feel, plus basic features.

[comment ================================================]
[subsection {Basic setup, private with inputs}]
[include parts/ex_alias0.inc]

[comment ================================================]
[subsection {Basic setup, command nesting}]
[include parts/ex_alias1.inc]

[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
[section {Language Reference}]

With the examples behind us we can now go and specify the entire
specification language. If you have skipped here on first reading,
ignoring the examples, please go back and read them first.

[comment ================================================]
[subsection Officers]
[include parts/dsl_officer.inc]

[comment ================================================]
[subsection Privates]
[include parts/dsl_private.inc]

[comment ================================================]
[subsection Parameters]
[include parts/dsl_parameter.inc]

[include parts/related.inc]
[include parts/feedback.inc]
[manpage_end]

[include parts/definitions.inc]
[manpage_begin [vset PROJECT]_introduction [vset MAN_SECTION] [vset VERSION]]
[include parts/module.inc]
[titledesc [vset TITLE_INTRO]]
[description]
[include parts/welcome.inc]

The cmdr framework is a set of 12 related Tcl packages for the easy
specification of the interfaces of command line applications.

This means the declaration of the set of commands to be provided by an
application, and their parameters, be they options or positional
inputs.

At runtime the internals of the framework, guided by the chosen
specification, handle the bulk of processing [var \$::argv]. This
covers determining the requested command, mapping argument words to
command parameters, and validating them.

Additional features of the runtime are an integrated help system and
interactive command line shells with basic command and argument
completion.

[section {System Architecture}]

[comment { -- @EDIT Please edit to suit -- }]

[include parts/related.inc]
[include parts/feedback.inc]

The instance command of the actor (officer actually) which contains the new officer.

[arg_def string name]
The user-visible name of the command.

[arg_def script actions]
The specification of the officer's subordinates.
Please read [term [vset TITLE_DSL]] (section "Officers") for the details.

[list_end][comment arguments]
[list_end][comment definitions]

[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
[section {Instance API}]

The list of names specifying the route from this officer to the new
private. The last element is the name of the private command, while
the preceding names specify the intermediate officers.

[comment {--- TODO place into text block for inclusion --- see private - constructor}]
[arg_def script arguments]
The specification of the private's parameters.
Please read [term [vset TITLE_DSL]] (section "Parameters") for the details.

[arg_def cmd-prefix action]
The command prefix to invoke when this private is selected for
execution.  It takes a single argument, the instance command of the
hidden [package cmdr::config] container holding the private's
parameters. The result of the action, if there is any, is ignored by
the framework.

the set of subordinates known to this officer. This is the same type
of script as used during construction, except here we dynamically
extend the officer.

[list_begin arguments]
[arg_def script actions]
The specification of the officer's additional subordinates.
Please read [term [vset TITLE_DSL]] (section "Officers") for the details.

[list_end][comment arguments]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <officer>] [method lookup] [arg name]]

This method returns the instance command of the sub-ordinate with the

help, if not overridden by a [cmd label] declaration
(in [arg spec]).

[arg_def string description]
Human-readable help text for the parameter.

[arg_def script spec]

Tcl-script specifying the parameter in detail. Please read
[term [vset TITLE_DSL]] (section "Parameters") for the details.

[list_end][comment arguments]
[list_end][comment definitions]

[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
[section {Instance API}]

[arg_def string name]
The user-visible name of the command.

[comment {--- TODO place into text block for inclusion --- see officer - extend}]
[arg_def script arguments]
The specification of the private's parameters.
Please read [term [vset TITLE_DSL]] (section "Privates") for the details.

[arg_def cmd-prefix action]
The command prefix to invoke when this private is selected for
execution.  It takes a single argument, the instance command of the
hidden [package cmdr::config] container holding the private's
parameters. The result of the action, if there is any, is ignored by
the framework.

[comment { No tables in doctools, using an example to get a tabular formatting. }]
[comment { TODO doctools: table markup }]
[comment { TODO doctools: named TOCs for commands - embedded small TOCs}]

[example {
alias <name> = <name'>...            Declare an alternate name for a command path.
alias <name>                         Declare an alternate name for the previous command.
common <name> <script>               Declare a named shared code block.
default                              Set last command as default.
description <text>                   Set help text for the current ensemble.
ehandler <cmdprefix>                 Execution Interposition.
officer <name> <script>              Declare a nested ensemble = sub-officer
private <name> <script> <cmdprefix>  Declare a simple command  = private
undocumented                         Hide ensemble from help.
}]

[list_begin definitions]
[def "[cmd alias] [arg name] [const =] [arg name']..."]
[def "[cmd alias] [arg name]"]
[def "[cmd common] [arg name] [arg text]"]
[def "[cmd default]"]
[def "[cmd description] [arg text]"]
[def "[cmd ehandler] [arg cmdprefix]"]
[def "[cmd officer] [arg name] [arg script]"]
[def "[cmd private] [arg name] [arg script] [arg cmdprefix]"]
[def "[cmd undocumented]"]
[list_end]

[comment { No tables in doctools, using an example to get a tabular formatting. }]
[comment { TODO doctools: table markup }]
[comment { TODO doctools: named TOCs for commands - embedded small TOCs}]

[comment {


Command & Attribute & Input & Option & State & Notes

-- & name        & --  & --  & --  &
Parameter name, unique within the \cprivate.

-- & description & --  & --  & --  &
Help text.

-- & visible     & yes & yes & no  &
Parameter is (in)visible to \parsing.

-- & ordered     & yes & no  & n/a &
Access during \parsing is ordered.

label <text> & label &
\texttt{name} & \texttt{name} & n/a &
Name to use in the help, and as primary flag (for an \coption).

alias <name> & aliases & n/a & none & n/a &
Declare alternate flag for an \coption to be recognized by.
Multiple aliases are allowed.


optional & optionality & no & n/a (yes) & n/a (no) &
Declare \cinput as optional.

test & acceptance & threshold & n/a & n/a &
Control the matching of words to optional \cinputs
(\ra\ref{flow/optional}).

undocumented & undocumented & no & no & n/a (yes) &
Declare as hidden from help.



list & listness & no  & no  & no &
Declare as list-valued.

default <value> & default & $*$ & $*$ & $*$ &
Set constant default value.
Details in section \ref{para/reps}.

generate <cmdprefix> & generate & $*$ & $*$ & $*$ &
Set callback returning the default value.
Details in section \ref{para/reps}.

interact <?prompt?> & interact, prompt & $*$ & $*$ & $*$ &
Enable the interactive entry of the string value.
Default prompt derives from the \texttt{label}.
Details in section \ref{para/reps}.

defered & defered & no & no & yes &
Defer calculation of the internal representation until demanded.

immediate & defered & yes & yes & no &
Complement of \cdefered.
Calculate the internal representation during \completion.



presence & presence &
no & no & n/a &
Declare as boolean \coption without argument.
Implies \cdefault and \cvalidate settings.

validate <cmdprefix> & validate &
$*$ & $*$ & $*$ &
Declare validation type.
Details in section \ref{para/vtype}.



when-complete <cmdprefix> & when-complete &
none & none & none &
Set callback executed when the value becomes known.

when-set <cmdprefix> & when-set &
none & none & none &
Set callback executed when the string value becomes known.

}]

[example {
alias <name>              & Declare alternate flag for an option.
default <value>           & Set constant default value.
defered                   & Defer calculation of the internal representation until demanded.
generate <cmdprefix>      & Set callback returning the default value.
immediate                 & Complement of defered.
interact ?<prompt>?       & Enable the interactive entry of the string value.
label <text>              & Name to use in the help, and as primary flag (for an option).
list                      & Declare as list-valued.
optional                  & Declare input as optional.
presence                  & Declare as boolean option without argument.
test                      & Control the matching of words to optional inputs.
undocumented              & Declare as hidden from help.
validate <cmdprefix>      & Declare validation type.
when-complete <cmdprefix> & Set callback executed when the value becomes known.
when-set <cmdprefix>      & Set callback executed when the string value becomes known.
}]

[list_begin definitions]
[def "[cmd alias] [arg name]"]
[def "[cmd default] [arg value]"]
[def "[cmd defered]"]
[def "[cmd generate] [arg cmdprefix]"]
[def "[cmd immediate]"]
[def "[cmd interact] [opt [arg prompt]]"]
[def "[cmd label] [arg text]"]
[def "[cmd list]"]
[def "[cmd optional]"]
[def "[cmd presence]"]
[def "[cmd test]"]
[def "[cmd undocumented]"]
[def "[cmd validate] [arg cmdprefix]"]
[def "[cmd when-complete] [arg cmdprefix]"]
[def "[cmd when-set] [arg cmdprefix]"]
[list_end]

[comment { No tables in doctools, using an example to get a tabular formatting. }]
[comment { TODO doctools: table markup }]
[comment { TODO doctools: named TOCs for commands - embedded small TOCs}]

[example {
description <text>             Set help text for command.
input <name> <help> <script>   Declare a positional parameter.
interactive                    Allow interactive shell.
option <name> <help> <script>  Declare a named parameter.
state <name> <help> <script>   Declare a hidden parameter.
undocumented                   Hide command from help.
use <name>                     Execute the named common block here.
}]

[list_begin definitions]
[def "[cmd description] [arg text]"]
[def "[cmd input] [arg name] [arg help] [arg script]"]
[def "[cmd interactive]"]
[def "[cmd option] [arg name] [arg help] [arg script]"]
[def "[cmd state] [arg name] [arg help] [arg script]"]
[def "[cmd undocumented]"]
[def "[cmd use] [arg name]"]
[list_end]

[para] This example specifies a command line providing 3 commands for
the management of command aliases.

This is actually a slice of [syscmd stackato]'s interface, reduced and
modified to fit here.

While it does not have the necessary backend procedures required to
actually run the commands, it is enough to demonstrate basic features,
namely the declaration of "privates" with "input" parameters.

[para] "privates" are the actual commands, the leaves at the bottom of
the hierarchy. Their "inputs" are positional parameters, i.e. the
association of argument words on a command line to parameter is done
in order of occurence (on command line, and in the specification).

[example {
# -*- tcl -*
package require Tcl 8.5
package require cmdr
package require foo-backend

cmdr create ::foo foo {
    private alias+ {
	description {
	    Create a shortcut for a command (prefix).
	}
	input name {
	    The name of the new shortcut.
	} {
	    validate ::foo::backend::vt::notacommand
	}
	input command {
	    The command (prefix) the name will map to.
	} {
	    list
	}
    } ::foo::backend::alias::add

    private alias- {
	description {
	    Remove a shortcut by name.
	}
	input name {
	    The name of the shortcut to remove.
	} {
	    validate ::foo::backend::vt::aliasname
	}
    } ::foo::backend::alias::remove

    private alias? {
	description {
	    List the known aliases (shortcuts).
	}
    } ::foo::backend::alias::list
}

foo do {*}$argv
exit
}]

[para] At the bottom of the example, just above we can also see the
very simple Tcl command which invokes the command line processing for
a list of words, here coming from [var \$argv], i.e. the application's
command line.

[para] The decoupling of command names from their implementations seen
in the previous example makes it easy to re-arrange and re-label the
user visible commands without having to touch any other part of the
code.

[para] This is demonstrated in the example below, moving the 3
"privates" into an "officer" and renaming them, without changing the
actions. Note that the parameter specifications were removed for
clarity, as they were not changed compared to the original example.

[para] "officers" are named inner nodes in the command hierarchy. They
aggregate related commands, which may not only be "privates" as seen
here, but sub-officers as well.

[example {
...
cmdr create ::foo foo {
    officer alias {
	description {
	    A collection of commands to manage
	    user-specific shortcuts for command
	    entry
	}

	private add {
	    ...
	} ::foo::backend::alias::add

	private remove {
	    ...
	} ::foo::backend::alias::remove

	private list {
	    ...
	} ::foo::backend::alias::list
    }
}
...
}]