cmdr
Check-in [b5f9a41322]
Not logged in
Myself Home DocumentationDownloads Tickets | Timeline Branches Tags Wiki Login
Bounty program for improvements to Tcl and certain Tcl packages.

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Specified structure for help information. Implemented its generation, filling the placeholder help methods. Added test.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: b5f9a413228b8a68e314de361f7d963f04c03b4f
User & Date: aku 2013-03-08 07:47:18
Context
2013-03-08
17:22
Extended actor with (not)documented attribute, for help (non)generation check-in: 08623165ff user: andreask tags: trunk
07:47
Specified structure for help information. Implemented its generation, filling the placeholder help methods. Added test. check-in: b5f9a41322 user: aku tags: trunk
07:45
Extended documentation, added overview of class relations check-in: ad01c89027 user: aku tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Added doc/notes_help.txt. 












































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

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

Changes to tests/xo.test. 

27
28
29
30
31
32
33

34
35
36
37
38
39

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

::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


# TODO: keys, get (super chain)

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







>







27
28
29
30
31
32
33
34
35
36
37
38
39
40

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

::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

Added tests/xo_help.tests. 
















































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

# -*- 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

Changes to xo_config.tcl. 

52
53
54
55
56
57
58





























59
60
61
62
63
64
65

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






























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

    method lookup {name} {







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>








52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

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

Changes to xo_officer.tcl. 

354
355
356
357
358
359
360
361








362
363
364
365
366
367
368
369
370
371
372
373
374

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

    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
	# XXX spec the structure.








	return
    }

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

    variable myinit myactions mymap mycommands mychildren

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

# # ## ### ##### ######## ############# #####################
## Ready
package provide xo::officer 0.1







<
>
>
>
>
>
>
>
>
|













354
355
356
357
358
359
360

361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381

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

    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

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

# # ## ### ##### ######## ############# #####################
## Ready
package provide xo::officer 0.1

Changes to xo_parameter.tcl. 

66
67
68
69
70
71
72













73
74
75
76
77
78
79

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

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














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

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







>
>
>
>
>
>
>
>
>
>
>
>
>








66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

	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 }

Changes to xo_private.tcl. 

66
67
68
69
70
71
72
73



74
75
76
77
78
79
80

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

    method help {} {
	my Setup
	return



    }

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








|
>
>
>








66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83

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

This page was generated in about 0.013s by Fossil 2.10 [eb804dc674] 2019-09-19 14:14:14