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.

[list_end][comment arguments]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <officer>] [method find] [arg path]]

This method returns the instance command of the sub-ordinate with the
given [arg path] of names. An error is thrown if such a sub-ordinate
does not exist. See also method [method has].

[list_begin arguments]
[arg_def string path] The path of names to the sub-ordinate to look for.
[list_end]

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

This method returns a boolean value indicating if this officer has a
sub-ordinate of the given [arg name] ([const true]), or not
([const false]). See also method [method lookup].

prefix has to execute this script in its caller's context. The script
will parse words for the private,m and perform its action. The command
prefix then has the responsbility to perform any custom cleanup action
required by the application using the framework to prevent leakage of
data between multiple commands executed one after the other (i.e. in
an interactive shell run by the framework).
[list_end][comment arguments]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <private>] [method find] [arg path]]

This method returns the instance command of the sub-ordinate with the
given [arg path] of names. An error is thrown if such a sub-ordinate
does not exist, i.e. always, as a private has no sub-ordinates,
ever. See also method [method find] of [package cdmr::officer] for the
high-end of the recursion which may end in this method.

[list_begin arguments]
[arg_def string path] The path of names to the sub-ordinate to look for.
[list_end]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd <private>] [method help] [opt [arg prefix]]]

This method returns the help information for the private and its
parameters. The [arg prefix], if specified provides the name of the
private within the help data. It defaults to the empty string.

.sp
\fB<officer>\fR \fBehandler\fR \fIcmd\fR
.sp
\fB<officer>\fR \fBexit\fR
.sp
\fB<officer>\fR \fBextend\fR \fIpath\fR \fIarguments\fR \fIaction\fR
.sp
\fB<officer>\fR \fBfind\fR \fIpath\fR
.sp
\fB<officer>\fR \fBhas\fR \fIname\fR
.sp
\fB<officer>\fR \fBhasdefault\fR
.sp
\fB<officer>\fR \fBhelp\fR ?\fIprefix\fR?
.sp
\fB<officer>\fR \fBknown\fR

cmd-prefix \fIaction\fR
The command prefix to invoke when this private is selected for
execution\&.  It takes a single argument, the instance command of the
hidden \fBcmdr::config\fR container holding the private's
parameters\&. The result of the action, if there is any, is ignored by
the framework\&.
.RE
.TP
\fB<officer>\fR \fBfind\fR \fIpath\fR
This method returns the instance command of the sub-ordinate with the
given \fIpath\fR of names\&. An error is thrown if such a sub-ordinate
does not exist\&. See also method \fBhas\fR\&.
.RS
.TP
string \fIpath\fR
The path of names to the sub-ordinate to look for\&.
.RE
.TP
\fB<officer>\fR \fBhas\fR \fIname\fR
This method returns a boolean value indicating if this officer has a
sub-ordinate of the given \fIname\fR (\fBtrue\fR), or not
(\fBfalse\fR)\&. See also method \fBlookup\fR\&.
.RS
.TP

\fB::cmdr::private\fR \fBcreate\fR \fIobj\fR \fIsuper\fR \fIname\fR \fIarguments\fR \fIaction\fR
.sp
\fB<private>\fR \fBcomplete-words\fR \fIparse\fR
.sp
\fB<private>\fR \fBdo\fR ?\fIword\fR\&.\&.\&.?
.sp
\fB<private>\fR \fBehandler\fR \fIcmd\fR
.sp
\fB<private>\fR \fBfind\fR \fIpath\fR
.sp
\fB<private>\fR \fBhelp\fR ?\fIprefix\fR?
.sp
\fB<private>\fR \fBunknown\fR \fIm\fR ?\fIword\fR\&.\&.\&.?
.sp
.BE
.SH DESCRIPTION

prefix has to execute this script in its caller's context\&. The script
will parse words for the private,m and perform its action\&. The command
prefix then has the responsbility to perform any custom cleanup action
required by the application using the framework to prevent leakage of
data between multiple commands executed one after the other (i\&.e\&. in
an interactive shell run by the framework)\&.
.RE
.TP
\fB<private>\fR \fBfind\fR \fIpath\fR
This method returns the instance command of the sub-ordinate with the
given \fIpath\fR of names\&. An error is thrown if such a sub-ordinate
does not exist, i\&.e\&. always, as a private has no sub-ordinates,
ever\&. See also method \fBfind\fR of \fBcdmr::officer\fR for the
high-end of the recursion which may end in this method\&.
.RS
.TP
string \fIpath\fR
The path of names to the sub-ordinate to look for\&.
.RE
.TP
\fB<private>\fR \fBhelp\fR ?\fIprefix\fR?
This method returns the help information for the private and its
parameters\&. The \fIprefix\fR, if specified provides the name of the
private within the help data\&. It defaults to the empty string\&.
The result of the command is a structure of the form
described in section \fBHelp Information\fR\&.

<li><a href="#6"><b class="cmd">&lt;officer&gt;</b> <b class="method">continued</b> <i class="arg">line</i></a></li>
<li><a href="#7"><b class="cmd">&lt;officer&gt;</b> <b class="method">default</b></a></li>
<li><a href="#8"><b class="cmd">&lt;officer&gt;</b> <b class="method">dispatch</b> <i class="arg">cmd</i></a></li>
<li><a href="#9"><b class="cmd">&lt;officer&gt;</b> <b class="method">do</b> <span class="opt">?<i class="arg">word</i>...?</span></a></li>
<li><a href="#10"><b class="cmd">&lt;officer&gt;</b> <b class="method">ehandler</b> <i class="arg">cmd</i></a></li>
<li><a href="#11"><b class="cmd">&lt;officer&gt;</b> <b class="method">exit</b></a></li>
<li><a href="#12"><b class="cmd">&lt;officer&gt;</b> <b class="method">extend</b> <i class="arg">path</i> <i class="arg">arguments</i> <i class="arg">action</i></a></li>
<li><a href="#13"><b class="cmd">&lt;officer&gt;</b> <b class="method">find</b> <i class="arg">path</i></a></li>
<li><a href="#14"><b class="cmd">&lt;officer&gt;</b> <b class="method">has</b> <i class="arg">name</i></a></li>
<li><a href="#15"><b class="cmd">&lt;officer&gt;</b> <b class="method">hasdefault</b></a></li>
<li><a href="#16"><b class="cmd">&lt;officer&gt;</b> <b class="method">help</b> <span class="opt">?<i class="arg">prefix</i>?</span></a></li>
<li><a href="#17"><b class="cmd">&lt;officer&gt;</b> <b class="method">known</b></a></li>
<li><a href="#18"><b class="cmd">&lt;officer&gt;</b> <b class="method">learn</b> <i class="arg">script</i></a></li>
<li><a href="#19"><b class="cmd">&lt;officer&gt;</b> <b class="method">lookup</b> <i class="arg">name</i></a></li>
<li><a href="#20"><b class="cmd">&lt;officer&gt;</b> <b class="method">prompt1</b></a></li>
<li><a href="#21"><b class="cmd">&lt;officer&gt;</b> <b class="method">prompt2</b></a></li>
<li><a href="#22"><b class="cmd">&lt;officer&gt;</b> <b class="method">report</b> <i class="arg">what</i> <i class="arg">data</i></a></li>
<li><a href="#23"><b class="cmd">&lt;officer&gt;</b> <b class="method">shell-exit</b> <i class="arg">config</i></a></li>
</ul>
</div>
</div>
<div id="section1" class="section"><h2><a name="section1">Description</a></h2>
<p>Welcome to the Cmdr project, written by Andreas Kupries.</p>
<p>For availability please read <i class="term"><a href="cmdr_howto_get_sources.html">Cmdr - How To Get The Sources</a></i>.</p>
<p>This package implements <em>officers</em>, the inner nodes of command

<dt>cmd-prefix <i class="arg">action</i></dt>
<dd><p>The command prefix to invoke when this private is selected for
execution.  It takes a single argument, the instance command of the
hidden <b class="package"><a href="cmdr_config.html">cmdr::config</a></b> container holding the private's
parameters. The result of the action, if there is any, is ignored by
the framework.</p></dd>
</dl></dd>
<dt><a name="13"><b class="cmd">&lt;officer&gt;</b> <b class="method">find</b> <i class="arg">path</i></a></dt>
<dd><p>This method returns the instance command of the sub-ordinate with the
given <i class="arg">path</i> of names. An error is thrown if such a sub-ordinate
does not exist. See also method <b class="method">has</b>.</p>
<dl class="arguments">
<dt>string <i class="arg">path</i></dt>
<dd><p>The path of names to the sub-ordinate to look for.</p></dd>
</dl></dd>
<dt><a name="14"><b class="cmd">&lt;officer&gt;</b> <b class="method">has</b> <i class="arg">name</i></a></dt>
<dd><p>This method returns a boolean value indicating if this officer has a
sub-ordinate of the given <i class="arg">name</i> (<b class="const">true</b>), or not
(<b class="const">false</b>). See also method <b class="method">lookup</b>.</p>
<dl class="arguments">
<dt>string <i class="arg">name</i></dt>
<dd><p>The name of the sub-ordinate to look for.</p></dd>
</dl></dd>
<dt><a name="15"><b class="cmd">&lt;officer&gt;</b> <b class="method">hasdefault</b></a></dt>
<dd><p>This method returns a boolean value indicating if this officer has a
default sub-ordinate (<b class="const">true</b>), or not (<b class="const">false</b>). See also
method <b class="method">default</b>.</p></dd>
<dt><a name="16"><b class="cmd">&lt;officer&gt;</b> <b class="method">help</b> <span class="opt">?<i class="arg">prefix</i>?</span></a></dt>
<dd><p>This method returns the help information for the officer and its
subordinates. The <i class="arg">prefix</i>, if specified provides the name of the
officer within the help data. It defaults to the empty string.
The result of the command is a structure of the form
described in section <span class="sectref"><a href="#section4">Help Information</a></span>.</p>
<dl class="arguments">
<dt>string <i class="arg">prefix</i></dt>
<dd><p>The name to use for the officer within the generated help.</p></dd>
</dl></dd>
<dt><a name="17"><b class="cmd">&lt;officer&gt;</b> <b class="method">known</b></a></dt>
<dd><p>This method returns a list containing the names of the subordinate
actors managed by this officer.
See also method <b class="method">children</b> which returns a list of instance
commands.
See also method <b class="method">lookup</b> to map names to instance commands.</p></dd>
<dt><a name="18"><b class="cmd">&lt;officer&gt;</b> <b class="method">learn</b> <i class="arg">script</i></a></dt>
<dd><p>This method takes a regular specification script and uses it to extend
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.</p>
<dl class="arguments">
<dt>script <i class="arg">actions</i></dt>
<dd><p>The specification of the officer's additional subordinates.
Please read <i class="term"><a href="cmdr_dsl_officer.html">Cmdr - Officer Specification Language</a></i> for the details.</p></dd>
</dl></dd>
<dt><a name="19"><b class="cmd">&lt;officer&gt;</b> <b class="method">lookup</b> <i class="arg">name</i></a></dt>
<dd><p>This method returns the instance command of the sub-ordinate with the
given <i class="arg">name</i>. An error is thrown if such a sub-ordinate does not
exist. See also method <b class="method">has</b>.</p>
<dl class="arguments">
<dt>string <i class="arg">name</i></dt>
<dd><p>The name of the sub-ordinate to look for.</p></dd>
</dl></dd>
<dt><a name="20"><b class="cmd">&lt;officer&gt;</b> <b class="method">prompt1</b></a></dt>
<dd><p>This hook-method for the main shell returns the primary prompt string
to use.</p></dd>
<dt><a name="21"><b class="cmd">&lt;officer&gt;</b> <b class="method">prompt2</b></a></dt>
<dd><p>This hook-method for the main shell returns the secondary prompt
string for use within a continuation. As the main shell does not
support continuation lines it should not be invoked ever, and thus
always throws an error should it be invoked.</p></dd>
<dt><a name="22"><b class="cmd">&lt;officer&gt;</b> <b class="method">report</b> <i class="arg">what</i> <i class="arg">data</i></a></dt>
<dd><p>This hook-method for the main shell is responsible for the reporting
of the command results.</p>
<p>Its result is the empty string.</p>
<dl class="arguments">
<dt>enum <i class="arg">what</i></dt>
<dd><p>The result code of the command, one of <b class="const">ok</b>, or <b class="const">fail</b>.</p></dd>
<dt>any <i class="arg">data</i></dt>
<dd><p>The result of the command, or an error message in case of failure.</p></dd>
</dl></dd>
<dt><a name="23"><b class="cmd">&lt;officer&gt;</b> <b class="method">shell-exit</b> <i class="arg">config</i></a></dt>
<dd><p>This is the backend for a private ending the main shell,
be it automatically created by the pacge, or by a user.</p>
<p>The argument is the <b class="package"><a href="cmdr_config.html">cmdr::config</a></b>
instance holding the parameters. The method does not
expect any and ignore it.</p></dd>
</dl>
</div>

</ul>
<ul class="syntax">
<li><a href="#1"><b class="cmd">::cmdr::private</b> <b class="method">new</b> <i class="arg">super</i> <i class="arg">name</i> <i class="arg">arguments</i> <i class="arg">action</i></a></li>
<li><a href="#2"><b class="cmd">::cmdr::private</b> <b class="method">create</b> <i class="arg">obj</i> <i class="arg">super</i> <i class="arg">name</i> <i class="arg">arguments</i> <i class="arg">action</i></a></li>
<li><a href="#3"><b class="cmd">&lt;private&gt;</b> <b class="method">complete-words</b> <i class="arg">parse</i></a></li>
<li><a href="#4"><b class="cmd">&lt;private&gt;</b> <b class="method">do</b> <span class="opt">?<i class="arg">word</i>...?</span></a></li>
<li><a href="#5"><b class="cmd">&lt;private&gt;</b> <b class="method">ehandler</b> <i class="arg">cmd</i></a></li>
<li><a href="#6"><b class="cmd">&lt;private&gt;</b> <b class="method">find</b> <i class="arg">path</i></a></li>
<li><a href="#7"><b class="cmd">&lt;private&gt;</b> <b class="method">help</b> <span class="opt">?<i class="arg">prefix</i>?</span></a></li>
<li><a href="#8"><b class="cmd">&lt;private&gt;</b> <b class="method">unknown</b> <i class="arg">m</i> <span class="opt">?<i class="arg">word</i>...?</span></a></li>
</ul>
</div>
</div>
<div id="section1" class="section"><h2><a name="section1">Description</a></h2>
<p>Welcome to the Cmdr project, written by Andreas Kupries.</p>
<p>For availability please read <i class="term"><a href="cmdr_howto_get_sources.html">Cmdr - How To Get The Sources</a></i>.</p>
<p>This package implements <em>privates</em>, the leaves of command

prefix has to execute this script in its caller's context. The script
will parse words for the private,m and perform its action. The command
prefix then has the responsbility to perform any custom cleanup action
required by the application using the framework to prevent leakage of
data between multiple commands executed one after the other (i.e. in
an interactive shell run by the framework).</p></dd>
</dl></dd>
<dt><a name="6"><b class="cmd">&lt;private&gt;</b> <b class="method">find</b> <i class="arg">path</i></a></dt>
<dd><p>This method returns the instance command of the sub-ordinate with the
given <i class="arg">path</i> of names. An error is thrown if such a sub-ordinate
does not exist, i.e. always, as a private has no sub-ordinates,
ever. See also method <b class="method">find</b> of <b class="package">cdmr::officer</b> for the
high-end of the recursion which may end in this method.</p>
<dl class="arguments">
<dt>string <i class="arg">path</i></dt>
<dd><p>The path of names to the sub-ordinate to look for.</p></dd>
</dl></dd>
<dt><a name="7"><b class="cmd">&lt;private&gt;</b> <b class="method">help</b> <span class="opt">?<i class="arg">prefix</i>?</span></a></dt>
<dd><p>This method returns the help information for the private and its
parameters. The <i class="arg">prefix</i>, if specified provides the name of the
private within the help data. It defaults to the empty string.
The result of the command is a structure of the form
described in section <span class="sectref"><a href="#section4">Help Information</a></span>.</p>
<dl class="arguments">
<dt>string <i class="arg">prefix</i></dt>
<dd><p>The name to use for the private within the generated help.</p></dd>
</dl></dd>
<dt><a name="8"><b class="cmd">&lt;private&gt;</b> <b class="method">unknown</b> <i class="arg">m</i> <span class="opt">?<i class="arg">word</i>...?</span></a></dt>
<dd><p>This method overrides the standard behaviour for unknown methods.
Instead of throwing an error they are routed to the hidden container
of the private's parameters, of class <b class="package"><a href="cmdr_config.html">cmdr::config</a></b>.</p>
<dl class="arguments">
<dt>string <i class="arg">m</i></dt>
<dd><p>The name of the unknown method.</p></dd>
<dt>string <i class="arg">word</i></dt>

namespace eval ::cmdr {
    namespace export help
    namespace ensemble create
}

namespace eval ::cmdr::help {
    namespace export query format auto
    namespace ensemble create
}

# # ## ### ##### ######## ############# #####################

proc ::cmdr::help::query {actor words} {
    debug.cmdr/help {}
    # Resolve chain of words (command name path) to the actor
    # responsible for that command, starting from the specified actor.
    # This is very much a convenience command.

    set root   [$actor root]
    set prefix $words

    if {![$root exists *in-shell*] ||
	![$root get    *in-shell*]} {
	# Not in the shell, put executable's name into the prefix.
	set prefix [linsert $prefix 0 [$root name]]
    }

    return [[$actor find $words] help $prefix]

























}

# # ## ### ##### ######## ############# #####################

proc ::cmdr::help::auto {actor} {
    debug.cmdr/help {}
    # Generate a standard help command for any actor, and add it dynamically.

    debug.cmdr/help {}

    set width  [$config @width]
    set words  [$config @cmdname]
    set format [$config @format]

    if {$format eq {}} {
	# Default depends on the presence of additional arguments,
	# i.e. if a specific command is asked for, or not.
	if {[llength $words]} {
	    set format full
	} else {
	    set format by-category
	}
    }

    puts [format $format \
	      [$actor root] \
	      $width \
	      [cmdr util dictsort \
		   [query $actor $words]]]
    return
}

# # ## ### ##### ######## ############# #####################

namespace eval ::cmdr::help::format {
    namespace export full list short by-category
    namespace ensemble create



}

# Alternate formats:
# List
# Short
# By-Category
# ... entirely different formats (json, .rst, docopts, ...)

    return $categories
}


# # ## ### ##### ######## ############# #####################
## Ready
package provide cmdr::help 1.1

	if {![dict exists $mymap a,$name]} {
	    return -code error \
		-errorcode [list CMDR ACTION UNKNOWN $name] \
		"Expected action name, got \"$name\""
	}
	return [dict get $mymap a,$name]
    }

    method find {words} {
	# Resolve chain of words (command name path) to the actor
	# responsible for that command, starting from the current
	# actor.  This is very much a convenience method built on top
	# of lookup (see above).

	my _find $words {}
    }

    method _find {words prefix} {
	set word [lindex $words 0]
	if {[llength $words] <= 1} {
	    return [my lookup $word]
	}

	[my lookup $word] _find \
	    [lrange $words 1 end] \
	    [linsert $prefix end $word]
    }

    method has {name} {
	debug.cmdr/officer {}
	my Setup
	return [dict exists $mymap a,$name]
    }

	myreplexit myhandler

    # # ## ### ##### ######## #############
}

# # ## ### ##### ######## ############# #####################
## Ready
package provide cmdr::officer 1.1

	set myinit      0
	set myhandler   {}
	return
    }

    # # ## ### ##### ######## #############

    method find {words} {
	my _find $words {}
    }

    method _find {words prefix} {
	# Privates do not have subordinates to look up.
	# We now have a bad command name argument to help.
	set word  [lindex $words 0]
	return -code error \
	    -errorcode [list CMDR ACTION BAD $word] \
	    "The command \"$prefix\" has no sub-commands, unexpected word \"$word\""
    }

    # # ## ### ##### ######## #############

    method ehandler {cmd} {
	debug.cmdr/private {}
	set myhandler $cmd
	return
    }

    # # ## ### ##### ######## #############

    variable myarguments mycmd myinit myconfig myhandler

    # # ## ### ##### ######## #############
}

# # ## ### ##### ######## ############# #####################
## Ready
package provide cmdr::private 1.1