suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add #:usage-help option to command-line.

Browse Source 
This allows specifying additional help text at the
top of the auto-generated help, before the options
specification.
This commit is contained in:
Sam Tobin-Hochstadt 2013-10-16 09:25:03 -04:00
parent 4037bc23d6
commit ac1a6ecda7
2 changed files with 30 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
pkgs/racket-pkgs/racket-doc/scribblings/reference/cmdline.scrbl
View File

@ -17,6 +17,7 @@
(code:line #:once-each flag-spec ...) (code:line #:once-each flag-spec ...)
(code:line #:once-any flag-spec ...) (code:line #:once-any flag-spec ...)
(code:line #:final flag-spec ...) (code:line #:final flag-spec ...)
(code:line #:usage-help string ...)
(code:line #:help-labels string ...) (code:line #:help-labels string ...)
(code:line #:ps string ...)] (code:line #:ps string ...)]
[flag-spec (flags id ... help-spec body ...+) [flag-spec (flags id ... help-spec body ...+)
@ -140,6 +141,10 @@ handler procedure and help string list returned by
@racket[handler-expr] and @racket[help-expr] are used as in the @racket[handler-expr] and @racket[help-expr] are used as in the
@racket[_table] argument of @racket[parse-command-line]. @racket[_table] argument of @racket[parse-command-line].
A @racket[#:usage-help] clause inserts text lines immediately after
the usage line. Each string in the clause provides a separate line
of text.
A @racket[#:help-labels] clause inserts text lines into the help table A @racket[#:help-labels] clause inserts text lines into the help table
of command-line flags. Each string in the clause provides a separate of command-line flags. Each string in the clause provides a separate
line of text. line of text.
@ -265,12 +270,13 @@ A @racket[table] is a list of flag specification sets. Each set is
represented as a pair of two items: a mode symbol and a list of either represented as a pair of two items: a mode symbol and a list of either
help strings or flag specifications. A mode symbol is one of help strings or flag specifications. A mode symbol is one of
@racket['once-each], @racket['once-any], @racket['multi], @racket['once-each], @racket['once-any], @racket['multi],
@racket['final], @racket['help-labels], or @racket['ps] with the same meanings as @racket['final], @racket['help-labels], @racket['usage-help], or
the corresponding clause tags in @racket[command-line]. For the @racket['ps] with the same meanings as the corresponding clause tags
@racket['help-labels] or @racket['ps] mode, a list of help string is provided. For the in @racket[command-line]. For the @racket['help-labels],
other modes, a list of flag specifications is provided, where each @racket['usage-help] or @racket['ps] mode, a list of help strings is
specification maps a number of flags to a single handler procedure. A provided. For the other modes, a list of flag specifications is
specification is a list of three items: provided, where each specification maps a number of flags to a single
handler procedure. A specification is a list of three items:
@itemize[ @itemize[

22
racket/collects/racket/cmdline.rkt
View File

@ -64,6 +64,14 @@
(let ([a (syntax-e (car lst))] (let ([a (syntax-e (car lst))]
[pieces (up-to-next-keyword (cdr lst))]) [pieces (up-to-next-keyword (cdr lst))])
(case a (case a
[(#:usage-help)
(for ([x (in-list pieces)])
(unless (string? (syntax-e x))
(serror "#:usage-help clause contains non-string"
x)))
(loop (at-next-keyword (cdr lst))
(cons (list* #'list #`(quote usage-help) pieces)
accum))]
[(#:help-labels) [(#:help-labels)
(for ([x (in-list pieces)]) (for ([x (in-list pieces)])
(unless (string? (syntax-e x)) (unless (string? (syntax-e x))
@ -243,11 +251,11 @@
(for ([spec (in-list table)]) (for ([spec (in-list table)])
(unless (and (list? spec) (pair? spec)) (unless (and (list? spec) (pair? spec))
(bad-table "spec-set must be a non-empty list: ~a" spec)) (bad-table "spec-set must be a non-empty list: ~a" spec))
(unless (memq (car spec) '(once-any once-each multi final help-labels ps)) (unless (memq (car spec) '(once-any once-each multi final help-labels usage-help ps))
(bad-table "spec-set type must be 'once-any, 'once-each, 'multi, 'final, 'help-labels, or 'ps: ~a" (bad-table "spec-set type must be 'once-any, 'once-each, 'multi, 'final, 'help-labels, 'usage-help, or 'ps: ~a"
(car spec))) (car spec)))
(for ([line (in-list (cdr spec))]) (for ([line (in-list (cdr spec))])
(if (memq (car spec) '(help-labels ps)) (if (memq (car spec) '(help-labels ps usage-help))
(unless (string? line) (unless (string? line)
(bad-table "~a line must be a string: ~e" (car spec) line)) (bad-table "~a line must be a string: ~e" (car spec) line))
(begin (begin
@ -338,9 +346,13 @@
(let ([sp (open-output-string)]) (let ([sp (open-output-string)])
(fprintf sp "~a [ <option> ... ]" (program-name program)) (fprintf sp "~a [ <option> ... ]" (program-name program))
(print-args sp finish-help finish) (print-args sp finish-help finish)
(for ([set (in-list table)]
#:when (eq? (car set) 'usage-help))
(for ([line (in-list (cdr set))])
(fprintf sp "\n ~a" line)))
(fprintf sp "\n where <option> is one of\n") (fprintf sp "\n where <option> is one of\n")
(for ([set (in-list table)] ; the original table (for ([set (in-list table)] ; the original table
#:unless (eq? (car set) 'ps)) #:unless (memq (car set) '(ps usage-help)))
(if (eq? (car set) 'help-labels) (if (eq? (car set) 'help-labels)
(for ([line (in-list (cdr set))]) (for ([line (in-list (cdr set))])
(fprintf sp " ~a\n" line)) (fprintf sp " ~a\n" line))
@ -398,6 +410,8 @@
(cdr spec)))] (cdr spec)))]
[(eq? (car spec) 'once-any) [(eq? (car spec) 'once-any)
(once-spec-set (cdr spec))] (once-spec-set (cdr spec))]
[(eq? (car spec) 'usage-help)
null]
[(eq? (car spec) 'help-labels) [(eq? (car spec) 'help-labels)
null] null]
[(eq? (car spec) 'multi) [(eq? (car spec) 'multi)