Help is given as structure listing command and their parameters in a
short/compressed form.

help        = dict (name -> command)
name        = string
command     = list (description options arguments)
description = string
options     = list (option...)
option      = dict (name -> description)
arguments   = list (argument...)
argument    = list (code name description)
code in {
     +		<=> required
     ?		<=> optional
     +*		<=> required splat
     ?* 	<=> optional splat
}

The conversion of this form into a help text, or other structure is
outside of the scope of xo/cmdr

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

::kt source xo_main.tests      ; # Entrypoints.
::kt source xo_officer.tests   ; # Action DSL
::kt source xo_private.tests   ; # Parameter DSL, collection
::kt source xo_parameter.tests ; # Parameter DSL, details
::kt source xo_runtime.tests   ; # Runtime command line parsing
::kt source xo_help.tests      ; # Help structures

# TODO: keys, get (super chain)

# # ## ### ##### ######## ############# #####################
cleanupTests
return

# -*- tcl -*- Include file for xo.test.
# # ## ### ##### ######## ############# #####################
## Help structure generation.

test xo-help-1.0 {help structure} -body {
    xo create x foo {
	description TEST
	officer bar {
	    private aloha {
		description hawaii
		option lulu loop {}
		input yoyo height
		input jump gate { optional }
		input run lane { list }
	    } ::hula
	}
	default
	alias snafu
	officer tool {
	    officer pliers {}
	    officer hammer {
		private nail {
		    description workbench
		    option driver force { validate adouble ; default 0 ; list ; alias force }
		    state  context orientation
		    input supply magazine { list ; optional }
		} ::wall
	    }
	    default hammer
	}
	alias hammer = tool hammer
    }
    x help
} -cleanup {
    x destroy
} -result {{bar aloha} {hawaii {--lulu loop --no-lulu loop} {{+ yoyo height} {? jump gate} {+* run lane}}} {snafu aloha} {hawaii {--lulu loop --no-lulu loop} {{+ yoyo height} {? jump gate} {+* run lane}}} {tool hammer nail} {workbench {--driver force --force force} {{?* supply magazine}}} {hammer nail} {workbench {--driver force --force force} {{?* supply magazine}}}}

# # ## ### ##### ######## ############# #####################
return

	set mypq [struct::queue P] ;# actual parameters
	if {[llength $myargs]} {
	    set myaq [struct::queue A] ;# formal argument parameters
	}
	return
    }

    method help {} {
	# command =          list (description options arguments)
	# Here we are responsible for -> list (options arguments)
	# options   = list (option...)
	# option    = dict (name -> description)
	# arguments = list (argument...)
	# argument  = list (code name description)
	# code in {
	#     +		<=> required
	#     ?		<=> optional
	#     +*	<=> required splat
	#     ?* 	<=> optional splat
	# }

	set options {}
	dict for {o para} $myoption {
	    dict set options $o [$para description]
	}

	set arguments {}
	foreach a $myargs {
	    set arg [dict get $mymap $a]
	    lappend arguments [list [$arg code] $a [$arg description]]
	}

	return [list $options $arguments]
    }


    method eoptions  {} { return $myfullopt }
    method names     {} { return [dict keys $mymap] }
    method arguments {} { return $myargs }
    method options   {} { return [dict keys $myoption] }

    method lookup {name} {

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

    method help {} {
	my Setup
	# Query each subordinate for their help and use it to piece ours together.
	# Note: Result is not finally formatted text, but nested dict structure.
	# Same is expected from the sub-ordinates

	# help = dict (name -> command)
	set help {}
	foreach c [my known] {
	    dict for {cmd h} [[my lookup $c] help] {
		dict set help [list $c {*}$cmd] $h
	    }
	}
	return $help
    }

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

    variable myinit myactions mymap mycommands mychildren

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

	set myconfig $theconfig
	interp alias {} [self namespace]::config {} $theconfig
	return
    }

    # # ## ### ##### ######## #############
    ## API: Property accessors...

    method code {} {
	# code in {
	#     +		<=> required
	#     ?		<=> optional
	#     +*	<=> required splat
	#     ?* 	<=> optional splat
	# }
	my Assert {$myiscmdline} {State parameter "@" has no help (coding)}
	append code [expr {$myisrequired ? "+" : "?"}]
	append code [expr {$myislist     ? "*" : ""}]
	return $code
    }

    # Identification and help. Add context name into it?
    method name        {} { return $myname }
    method description {} { return $mydescription }

    # Core classification properties
    method ordered      {} { return $myisordered }

	# Call actual command, hand it the filled configuration.
	{*}$mycmd $myconfig 
    }

    method help {} {
	my Setup
	# help    = dict (name -> command)
	# command = list (description options arguments)
	# caller supplies/extends name, in context (might be alias!)
	return [dict create {} [list [my description] {*}[config help]]]
    }

    # Redirect anything not known to the parameter collection.
    method unknown {m args} {
	config $m {*}$args
    }