getopts: new feature: cumulative options.

An option declared as (cumul <type>) indicates that it is of
type <type>, and that multiple occurrences of the option
produce values that are accumulated into a list.
The accumulation is in reverse order: the rightmost
occurrence ends up the first in the list.

* lisplib.c (getopts_set_entries): Add cumul to list of
interned symbols, so that the getopts.tl code isn't mistakenly
working with sys:cumul.

* share/txr/stdlib/getopts.tl (opt-parsed): New slot, cumul.
(opt-desc basic-type p, opt-desc list-type-p,  opt-desc
cumul-type-p): New methods.
(opt-desc check): Rework type validity check using the new
methods.
(opt-parsed convert-type): Support 'cumul type by
instantiating an opt-parsed object for the wrapped type,
and stealing its converted argument into the current object,
and setting the cumul flag.
(opts add-opt, option-base add-opt): Support options that have
the cumul flag set by accumulating list values. The code is
different due to different amounts of encapsulation. The opts
structure stores the raw opt-parsed objects, whereas
option-base just takes the decoded values.
(opthelp): Parse through the (cumul ...) type syntax, so
cumulative options are printed in the help text the same way
as if they were non-cumulative.

* txr.1: Documented.

1 files changed, 35 insertions, 1 deletions

diff --git a/txr.1 b/txr.1
index fec2dcd9..9875d439 100644
--- a/txr.1
+++ b/txr.1
@@ -57203,7 +57203,41 @@ and converted accordingly. The option's argument is then a list object
 whose elements are the converted pieces. For instance
 .code "(list :dec)"
 will convert a list of comma-separated decimal integer tokens into
-a list of integer objects.
+a list of integer objects. The
+.code list
+option type does not nest.
+.meIP (cumul << type )
+If the type is specified as a compound form headed by the
+.code cumul
+symbol, it indicates that if the option is specified multiple times,
+the values coming from the multiple occurrences are accumulated into a list.
+The
+.meta type
+argument may be a
+.code list
+type, exemplified by
+.code "(cumul (list :dec))"
+or a basic type, such as
+.codn "(cumul :str)" .
+However, this type specifier does not nest. Combinations such as
+.code "(cumul (cumul ...)"
+and
+.code "(list (cumul ...))"
+are invalid.
+The option values are accumulated in reverse order, so that the rightmost
+repetition becomes the first item in the list. For instance, if the
+.code -x
+option has type
+.codn "(cumul :dec)" ,
+and the arguments presented for parsing are
+.codn "(\(dq-x\(dq \(dq1\(dq \(dq-x\(dq \(dq2\(dq)" ,
+then the option's value will be
+.codn "(2 1)" .
+If a
+.codn list -typed
+option is cumulative, then the option value will be a list of lists.
+Each repetition of the option produces a list, and the lists are accumulated.
+
 .RE
 
 .IP