diff options
| -rw-r--r-- | stdlib/getopts.tl | 135 | ||||
| -rw-r--r-- | txr.1 | 18 |
2 files changed, 79 insertions, 74 deletions
diff --git a/stdlib/getopts.tl b/stdlib/getopts.tl index e448c130..65b6e4dc 100644 --- a/stdlib/getopts.tl +++ b/stdlib/getopts.tl @@ -269,7 +269,7 @@ (opr (new sys:opt-processor od-list opt-desc-list opts opts))) opr.(parse-opts args))) -(defun opthelp (opt-desc-list : (stream *stdout*)) +(defun opthelp (opt-desc-list : (stream *stdout*) (incnotes t)) (let ((sorted [nsort (copy-list (remove-if (op null @1.helptext) opt-desc-list)) : (do if @1.long @1.long @1.short)]) @@ -308,71 +308,72 @@ (each ((line (sys:wdwrap undoc-str 75))) (put-line ` @line` stream))) (put-line : stream)) - (put-line "Notes:\n" stream) - (let* ((have-short (some sorted (usl short))) - (have-long (some sorted (usl long))) - (have-arg-p (some sorted (usl arg-p))) - (have-bool (some sorted (op eq @1.type :bool))) - (texts (list (if have-short - "Short options can be invoked with long syntax: \ \ - for example, --a can be used when -a exists.\ \ - Short no-argument options can be clumped into\ \ - one argument as exemplified by -xyz.") - (if have-bool + (when incnotes + (put-line "Notes:\n" stream) + (let* ((have-short (some sorted (usl short))) + (have-long (some sorted (usl long))) + (have-arg-p (some sorted (usl arg-p))) + (have-bool (some sorted (op eq @1.type :bool))) + (texts (list (if have-short + "Short options can be invoked with long syntax: \ \ + for example, --a can be used when -a exists.\ \ + Short no-argument options can be clumped into\ \ + one argument as exemplified by -xyz.") + (if have-bool + (if have-arg-p + "Options that take no argument are Boolean:" + (if undocumented + "All documented options are Boolean:" + "All options are Boolean:"))) + (if have-bool + "they are true when present, false when absent.") + (if (and have-bool have-arg-p) + "The --no- prefix can explicitly specify \ \ + Boolean options as false: if a Boolean option\ \ + X exists,\ \ + --no-X specifies it as false. This is useful\ \ + for making false those options which default\ \ + to true. " + "The --no- prefix can explicitly specify \ \ + options as false: if an X option exists,\ \ + --no-X specifies it as false. This is useful\ \ + for making false those options which default\ \ + to true. ") + (if (not have-long) + "Note the double dash on --no.") + (if (and have-short have-long) + "The --no- prefix can be applied to a short\ \ + or long option name.") (if have-arg-p - "Options that take no argument are Boolean:" - (if undocumented - "All documented options are Boolean:" - "All options are Boolean:"))) - (if have-bool - "they are true when present, false when absent.") - (if (and have-bool have-arg-p) - "The --no- prefix can explicitly specify \ \ - Boolean options as false: if a Boolean option\ \ - X exists,\ \ - --no-X specifies it as false. This is useful\ \ - for making false those options which default\ \ - to true. " - "The --no- prefix can explicitly specify \ \ - options as false: if an X option exists,\ \ - --no-X specifies it as false. This is useful\ \ - for making false those options which default\ \ - to true. ") - (if (not have-long) - "Note the double dash on --no.") - (if (and have-short have-long) - "The --no- prefix can be applied to a short\ \ - or long option name.") - (if have-arg-p - "The argument to a long option can be given in one\ \ - argument as --option=arg or as a separate\ \ - argument using --option arg.") - "The special argument -- can be used where an option\ \ - may appear. It means \"end of options\": the\ \ - arguments which follow are not treated as options\ \ - even if they look like options."))) - (mapdo (do put-line ` @1` stream) - (sys:wdwrap `@{(flatten texts)}` 77))) - (put-line : stream) - (whenlet ((types (keep-if [andf keywordp (op neq :bool)] - (uniq (mapcar (usl type) sorted))))) - (put-line "Type legend:\n" stream) - (each ((ty types)) - (iflet ((ln (caseql ty - (:dec " DEC - Decimal integer: -123, 0, 5, +73") - (:hex " HEX - Hexadecimal integer -EF, 2D0, +9A") - (:oct " OCT - Octal integer: -773, 5677, +326") - (:cint " CINT - C-style integer: leading 0 octal,\ - \ leading 0x hex, else decimal;\n\ - \ leading sign allowed: -0777, 0xFDC, +123") - (:float " FLOAT - Floating-point: -1.3e+03, +5, 3.3,\ - \ 3., .5, .12e9, 53.e-3, 3e-015") - (:str " STR - String with embedded escapes, valid\ - \ as TXR Lisp string literals\n\ - \ syntax: foo, foo\\tbar, abc\\nxyz") - (:text " TEXT - Unprocessed text")))) - (put-line ln stream))) - (put-line : stream)))) + "The argument to a long option can be given in one\ \ + argument as --option=arg or as a separate\ \ + argument using --option arg.") + "The special argument -- can be used where an option\ \ + may appear. It means \"end of options\": the\ \ + arguments which follow are not treated as options\ \ + even if they look like options."))) + (mapdo (do put-line ` @1` stream) + (sys:wdwrap `@{(flatten texts)}` 77))) + (put-line : stream) + (whenlet ((types (keep-if [andf keywordp (op neq :bool)] + (uniq (mapcar (usl type) sorted))))) + (put-line "Type legend:\n" stream) + (each ((ty types)) + (iflet ((ln (caseql ty + (:dec " DEC - Decimal integer: -123, 0, 5, +73") + (:hex " HEX - Hexadecimal integer -EF, 2D0, +9A") + (:oct " OCT - Octal integer: -773, 5677, +326") + (:cint " CINT - C-style integer: leading 0 octal,\ + \ leading 0x hex, else decimal;\n\ + \ leading sign allowed: -0777, 0xFDC, +123") + (:float " FLOAT - Floating-point: -1.3e+03, +5, 3.3,\ + \ 3., .5, .12e9, 53.e-3, 3e-015") + (:str " STR - String with embedded escapes, valid\ + \ as TXR Lisp string literals\n\ + \ syntax: foo, foo\\tbar, abc\\nxyz") + (:text " TEXT - Unprocessed text")))) + (put-line ln stream))) + (put-line : stream))))) (defstruct sys:option-base nil in-args @@ -389,8 +390,8 @@ (set me.in-args args me.out-args args) (let ((opr (new sys:opt-processor od-list me.opt-desc-list opts me))) opr.(parse-opts args))) - (:method opthelp (me : (stream *stdout*)) - (opthelp me.opt-desc-list stream))) + (:method opthelp (me : (stream *stdout*) (incnotes t)) + (opthelp me.opt-desc-list stream incnotes))) (defmacro define-option-struct (name super-spec . opts) (let* ((slots (mapcar (tb ((short long . rest)) @@ -68160,8 +68160,9 @@ arguments. The .code opthelp -function takes a list of option descriptors and an output stream, -and generates help text on that stream. A program supporting a +function takes a list of option descriptors, an output stream, and an arg +indicating whether to print extra notes on command line conventions. +It then generates help text on that stream. A program supporting a .code --help option can use this to generate that portion of its help text which describes the available options, as well as the conventions that they use. @@ -68653,7 +68654,7 @@ arguments. .coNP Function @ opthelp .synb -.mets (opthelp < opt-desc-list <> [ stream ]) +.mets (opthelp < opt-desc-list <> [ stream ] <> [ inchelp ]) .syne .desc The @@ -68663,9 +68664,11 @@ function processes the list of structures .meta opt-desc-list and compiles a customized body of help text describing all of the -options, as well as general description of the command-line option -conventions to guide the user in in the correct use of command -line options. +options. If +.meta inchelp +is non-nil then a general description of the command-line option +conventions will also be printed to guide the user in in the correct +use of command line options. The text is formatted to fit within 79 columns, and begins and ends with a blank line. Its format consists of headings which begin in the first column, @@ -68749,7 +68752,8 @@ When the argument list is successfully processed. The .code opthelp -method takes an optional stream argument. +method takes an optional stream argument, and an argument to indicate whether +or not to include general notes on command line conventions. Note: to encode the option names .str "t" |