cmdr
Check-in [f41f44de14]
Not logged in
Bounty program for improvements to Tcl and certain Tcl packages.

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

Overview
Comment:Moved handling of option arguments in help to separate proc. Reworked the handling of global options to show arguments as well. Fixed sorting of section display when seeing options with arguments.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: f41f44de14b06cc430c68f2716202e8e259be6b5
User & Date: andreask 2014-09-10 20:21:12
Context
2014-09-10
20:35
Move handling of global option to before checking for a command. We can now enter a main shell with global options set. Bump version numbers. check-in: 2bfa8d5785 user: andreask tags: trunk
20:21
Moved handling of option arguments in help to separate proc. Reworked the handling of global options to show arguments as well. Fixed sorting of section display when seeing options with arguments. check-in: f41f44de14 user: andreask tags: trunk
2014-08-29
20:19
cmdr::parameter - Extended spec with description of option argument, if any. cmdr::help - Modified to make use of the new information in help texts. check-in: 463519edc6 user: andreask tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to help.tcl.

232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
...
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
...
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
...
505
506
507
508
509
510
511
512
513
514
515
516
517

518
519
520
521
522
523
524
...
526
527
528
529
530
531
532






















533
534
535
536
537
538
539
    }

    # plus per-option descriptions (sort by flag name)
    if {[dict size $options]} {
	set onames {}
	set odefs  {}
	foreach {oname ohelp} [::cmdr util dictsort $options] {
	    # Inspect the parameter and determine of the option
	    # requires an argument. If yes, suitably extend the
	    # definition key of the option list.
	    set pname [dict get $opt2para $oname]
	    set vt    [dict get $parameters $pname validator]
	    if {$vt ne "::cmdr::validate::boolean"} {
		if {[dict exists $parameters $pname arglabel]} {
		    set plabel [dict get $parameters $pname arglabel]
		} else {
		    set plabel [dict get $parameters $pname label]
		}
		append oname " [string toupper $plabel]"
	    }

	    lappend onames $oname
	    lappend odefs  $ohelp
	}
	DefList $width $onames $odefs
    }

    # plus per-argument descriptions (keep in cmdline order)
................................................................................

    # Get the commands in the category, preliminary formatting
    # (labels, descriptions).

    set names {}
    set descs {}
    if {[dict exists $cmds $path]} {
	foreach def [lsort -dict -unique [dict get $cmds $path]] {
	    lassign $def syntax desc
	    lappend names $syntax
	    lappend descs $desc
	}
    }
    set labels [cmdr util padr $names]

................................................................................
	    continue
	}

	# Exclude officers from the categorized help. They can only be
	# a source of shared options. Shared options are collected in
	# a separate structure.
	if {![info exists action] && [dict size $options]} {
	    set opts($name) $options
	    continue
	}


	if {![llength $sections]} {
	    lappend sections Miscellaneous
	}
................................................................................
	}
    }

    # Options for the root => global options, put into the section tree.
    # We are ignoring deeper shared options.

    if {[info exists opts($root)]} {
	set options $opts($root)

	set category {Global Options}
	lappend sections $category
	set category [::list $category]
	foreach {o d} $options {

	    lappend cmds($category) [::list $o [string trim $d]]
	    LinkParent $category
	}

	unset opts($root)
    }

................................................................................
    # parray subc
    # parray cmds
    # parray opts
    # puts ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    ::list [array get subc] [array get cmds]
}























proc ::cmdr::help::format::LinkParent {category} {
    if {![llength $category]} return
    upvar 1 subc subc
    set parent [lreverse [lassign [lreverse $category] leaf]]
    lappend subc($parent) $leaf
    LinkParent $parent






|
<
<
<
<
<
<
<
<
<
<
<
<
<







 







|







 







|







 







|




|
>







 







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







232
233
234
235
236
237
238
239













240
241
242
243
244
245
246
...
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
...
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
...
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
...
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
    }

    # plus per-option descriptions (sort by flag name)
    if {[dict size $options]} {
	set onames {}
	set odefs  {}
	foreach {oname ohelp} [::cmdr util dictsort $options] {
	    set oname [OptionName $oname parameters opt2para]













	    lappend onames $oname
	    lappend odefs  $ohelp
	}
	DefList $width $onames $odefs
    }

    # plus per-argument descriptions (keep in cmdline order)
................................................................................

    # Get the commands in the category, preliminary formatting
    # (labels, descriptions).

    set names {}
    set descs {}
    if {[dict exists $cmds $path]} {
	foreach def [lsort -dict -unique -index 0 [dict get $cmds $path]] {
	    lassign $def syntax desc
	    lappend names $syntax
	    lappend descs $desc
	}
    }
    set labels [cmdr util padr $names]

................................................................................
	    continue
	}

	# Exclude officers from the categorized help. They can only be
	# a source of shared options. Shared options are collected in
	# a separate structure.
	if {![info exists action] && [dict size $options]} {
	    set opts($name) [::list $options $parameters $opt2para]
	    continue
	}


	if {![llength $sections]} {
	    lappend sections Miscellaneous
	}
................................................................................
	}
    }

    # Options for the root => global options, put into the section tree.
    # We are ignoring deeper shared options.

    if {[info exists opts($root)]} {
	lassign $opts($root) options parameters opt2para

	set category {Global Options}
	lappend sections $category
	set category [::list $category]
	foreach {o d} [::cmdr util dictsort $options] {
	    set o [OptionName $o parameters opt2para]
	    lappend cmds($category) [::list $o [string trim $d]]
	    LinkParent $category
	}

	unset opts($root)
    }

................................................................................
    # parray subc
    # parray cmds
    # parray opts
    # puts ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    ::list [array get subc] [array get cmds]
}

proc ::cmdr::help::format::OptionName {oname pv ov} {
    upvar 1 $pv parameters $ov opt2para

    # Inspect the parameter and determine of the option
    # requires an argument. If yes, suitably extend the
    # definition key of the option list.

    set pname [dict get $opt2para $oname]
    set vt    [dict get $parameters $pname validator]

    if {$vt ne "::cmdr::validate::boolean"} {
	if {[dict exists $parameters $pname arglabel]} {
	    set plabel [dict get $parameters $pname arglabel]
	} else {
	    set plabel [dict get $parameters $pname label]
	}
	append oname " [string toupper $plabel]"
    }

    return $oname
}

proc ::cmdr::help::format::LinkParent {category} {
    if {![llength $category]} return
    upvar 1 subc subc
    set parent [lreverse [lassign [lreverse $category] leaf]]
    lappend subc($parent) $leaf
    LinkParent $parent