doc lambda* polish

This is a bit of polish for the lambda* docs.  I found the bnf at the
start hard to follow, and think #:allow-other-keys can just be
described how it works now, not relative to how it used to be.  I
added a bit at the end about #:rest with #:key as per a bug report,
and about let* style for the bindings.



5.8.3.3 lambda* Reference
.........................

When using optional and keyword argument lists, `lambda' for creating a
procedure then `let-optional' or `let-keywords' is a bit lengthy.
`lambda*' combines the features of those macros into a single
convenient syntax.

 -- library syntax: lambda* ([var...]
          [#:optional vardef...]
          [#:key vardef... [#:allow-other-keys]]
          [#:rest var | . var])
          body

     Create a procedure that takes optional and/or keyword arguments
     specified with `#:optional' and `#:key'.  For example,

          (lambda* (a b #:optional c d . e) '())

     is a procedure with fixed arguments A and B, optional arguments C
     and D, and rest argument E.  If the optional arguments are omitted
     in a call, the variables for them are bound to `#f'.

     `lambda*' can also take keyword arguments.  For example, a
     procedure defined like this:

          (lambda* (#:key xyzzy larch) '())

     can be called with any of the argument lists `(#:xyzzy 11)',
     `(#:larch 13)', `(#:larch 42 #:xyzzy 19)', `()'.  Whichever
     arguments are given as keywords are bound to values (and those not
     given are `#f').

     Optional and keyword arguments can also have default values to take
     when not present in a call, by giving a two-item list of variable
     name and expression.  For example in

          (lambda* (foo #:optional (bar 42) #:key (baz 73))
               (list foo bar baz))

     FOO is a fixed argument, BAR is an optional argument with default
     value 42, and baz is a keyword argument with default value 73.
     Default value expressions are not evaluated unless they are needed
     and until the procedure is called.

     Normally it's an error if a call has keywords other than those
     specified by `#:key', but adding `#:allow-other-keys' to the
     definition (after the keyword argument declarations) will ignore
     unknown keywords.

     If a call has a keyword given twice, the last value is used.  For
     example,

          ((lambda* (#:key (heads 0) (tails 0))
             (display (list heads tails)))
           #:heads 37 #:tails 42 #:heads 99)
          -| (99 42)

     `#:rest' is a synonym for the dotted syntax rest argument.  The
     argument lists `(a . b)' and `(a #:rest b)' are equivalent in all
     respects.  This is provided for more similarity to DSSSL,
     MIT-Scheme and Kawa among others, as well as for refugees from
     other Lisp dialects.

     When `#:key' is used together with a rest argument, the keyword
     parameters in a call all remain in the rest list.  This is the
     same as Common Lisp.  For example,

          ((lambda* (#:key (x 0) #:allow-other-keys #:rest r)
             (display r))
           #:x 123 #:y 456)
          -| (#:x 123 #:y 456)

     `#:optional' and `#:key' establish their bindings successively,
     from left to right, as per `let-optional*' and `let-keywords*'.
     This means default expressions can refer back to prior parameters,
     for example

          (lambda* (start #:optional (end (+ 10 start)))
            (do ((i start (1+ i)))
                ((> i end))
              (display i)))



_______________________________________________
Guile-devel mailing list
Guile-devel@xxxxxxx
http://lists.gnu.org/mailman/listinfo/guile-devel