[Guile-commits] GNU Guile branch, master, updated. release_1-9-4-49-gf916cbc

[Andy Wingo]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GNU Guile".

http://git.savannah.gnu.org/cgit/guile.git/commit/?id=f916cbc4b17165491e7bfe64be4b56913fdacce6

The branch, master has been updated
       via  f916cbc4b17165491e7bfe64be4b56913fdacce6 (commit)
      from  24bf130fd15afbc8b3a2ccdc50a027f9b6c9e623 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit f916cbc4b17165491e7bfe64be4b56913fdacce6
Author: Andy Wingo <address@hidden>
Date:   Tue Oct 27 00:08:20 2009 +0100

    update procedure docs for programs, lambda*, case-lambda
    
    * module/system/vm/program.scm: Export the arity things again, and
      program-arity. Why not.
    
    * doc/ref/api-procedures.texi (Compiled Procedures): Update for current
      API.
      (Optional Arguments): Update to assume lambda* and define* are always
      available, and (ice-9 optargs) is now the ghetto.
      (Case-lambda): Now here, moved from SRFI-16 docs. Also docs
      case-lambda*.
    
    * doc/ref/srfi-modules.texi: Point to core case-lambda docs.

-----------------------------------------------------------------------

Summary of changes:
 doc/ref/api-procedures.texi  |  558 +++++++++++++++++++++++-------------------
 doc/ref/srfi-modules.texi    |   63 +-----
 module/system/vm/program.scm |    9 +-
 3 files changed, 317 insertions(+), 313 deletions(-)

diff --git a/doc/ref/api-procedures.texi b/doc/ref/api-procedures.texi
index 8098b4f..972ce2e 100644
--- a/doc/ref/api-procedures.texi
+++ b/doc/ref/api-procedures.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
address@hidden Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
address@hidden Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009
 @c   Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
@@ -13,6 +13,7 @@
 * Primitive Procedures::        Procedures defined in C.
 * Compiled Procedures::         Scheme procedures can be compiled.
 * Optional Arguments::          Handling keyword, optional and rest arguments.
+* Case-lambda::                 One function, multiple arities.
 * Procedure Properties::        Procedure properties and meta-information.
 * Procedures with Setters::     Procedures with setters.
 * Macros::                      Lisp style macro definitions.
@@ -26,8 +27,6 @@
 @subsection Lambda: Basic Procedure Creation
 @cindex lambda
 
address@hidden FIXME::martin: Review me!
-
 A @code{lambda} expression evaluates to a procedure.  The environment
 which is in effect when a @code{lambda} expression is evaluated is
 enclosed in the newly created procedure, this is referred to as a
@@ -135,15 +134,21 @@ slightly higher-level abstraction of the Guile 
implementation.
 @node Compiled Procedures
 @subsection Compiled Procedures
 
-Procedures that were created when loading a compiled file are
-themselves compiled. (In contrast, procedures that are defined by
-loading a Scheme source file are interpreted, and often not as fast as
-compiled procedures.)
+In Guile, procedures can be executed by directly interpreting their
+source code. Scheme source code is a set of nested lists, after all,
+with each list representing a procedure call.
+
+Most procedures are compiled, however. This means that Guile has done
+some pre-computation on the procedure, to determine what it will need
+to do each time the procedure runs. Compiled procedures run faster
+than interpreted procedures.
 
-Loading compiled files is the normal way that compiled procedures come
-to being, though procedures can be compiled at runtime as well.
address@hidden/Load/Eval/Compile}, for more information on runtime
-compilation.
+Loading files is the normal way that compiled procedures come to
+being. If Guile sees that a file is uncompiled, or that its compiled
+file is out of date, it will attempt to compile the file when it is
+loaded, and save the result to disk. Procedures can be compiled at
+runtime as well. @xref{Read/Load/Eval/Compile}, for more information
+on runtime compilation.
 
 Compiled procedures, also known as @dfn{programs}, respond all
 procedures that operate on procedures. In addition, there are a few
@@ -181,56 +186,34 @@ return @code{#f} if the compiler could determine that 
this information
 was unnecessary.
 @end deffn
 
address@hidden {Scheme Procedure} program-external program
address@hidden {C Function} scm_program_external (program)
-Returns the set of heap-allocated variables that this program captures
-in its closure, as a list. If a closure is code with data, you can get
-the code from @code{program-bytecode}, and the data via
address@hidden
address@hidden {Scheme Procedure} program-free-variables program
address@hidden {C Function} scm_program_free_variables (program)
+Returns the set of free variables that this program captures in its
+closure, as a vector. If a closure is code with data, you can get the
+code from @code{program-objcode}, and the data via
address@hidden
+
+Some of the values captured are actually in variable ``boxes''.
address@hidden and the VM}, for more information.
 
 Users must not modify the returned value unless they think they're
 really clever.
 @end deffn
 
address@hidden {Scheme Procedure} program-external-set! program external
address@hidden {C Function} scm_program_external_set_x (program, external)
-Set @var{external} as the set of closure variables on @var{program}.
-
-The Guile maintainers will not be held responsible for side effects of
-calling this function, including but not limited to replacement of
-shampoo with hair dye, and a slight salty taste in tomorrow's dinner.
address@hidden deffn
-
address@hidden {Scheme Procedure} program-arity program
address@hidden {C Function} scm_program_arity (program)
address@hidden {Scheme Procedure} arity:nargs arity
address@hidden {Scheme Procedure} arity:nrest arity
address@hidden {Scheme Procedure} arity:nlocs arity
address@hidden {Scheme Procedure} arity:nexts arity
-Accessors for a representation of the ``arity'' of a program.
-
address@hidden is the number of arguments to the procedure, and
address@hidden will be non-zero if the last argument is a rest argument.
-
-The other two accessors determine the number of local and external
-(heap-allocated) variables that this procedure will need to have
-allocated.
address@hidden deffn
-
 @deffn {Scheme Procedure} program-meta program
address@hidden scm_program_meta (program)
address@hidden {C Function} scm_program_meta (program)
 Return the metadata thunk of @var{program}, or @code{#f} if it has no
 metadata.
 
 When called, a metadata thunk returns a list of the following form:
address@hidden(@var{bindings} @var{sources} . @var{properties})}. The format
address@hidden(@var{bindings} @var{sources} @var{arities} . @var{properties})}. 
The format
 of each of these elements is discussed below.
 @end deffn
 
 @deffn {Scheme Procedure} program-bindings program
address@hidden {Scheme Procedure} make-binding name extp index start end
address@hidden {Scheme Procedure} make-binding name boxed? index start end
 @deffnx {Scheme Procedure} binding:name binding
address@hidden {Scheme Procedure} binding:extp binding
address@hidden {Scheme Procedure} binding:boxed? binding
 @deffnx {Scheme Procedure} binding:index binding
 @deffnx {Scheme Procedure} binding:start binding
 @deffnx {Scheme Procedure} binding:end binding
@@ -238,9 +221,7 @@ Bindings annotations for programs, along with their 
accessors.
 
 Bindings declare names and liveness extents for block-local variables.
 The best way to see what these are is to play around with them at a
-REPL. The only tricky bit is that @var{extp} is a boolean, declaring
-whether the binding is heap-allocated or not. @xref{VM Concepts}, for
-more information.
+REPL. @xref{VM Concepts}, for more information.
 
 Note that bindings information is stored in a program as part of its
 metadata thunk, so including it in the generated object code does not
@@ -262,6 +243,40 @@ following} an instruction, so that backtraces can find the 
source
 location of a call that is in progress.
 @end deffn
 
address@hidden {Scheme Procedure} program-arities program
address@hidden {C Function} scm_program_arities (program)
address@hidden {Scheme Procedure} program-arity program ip
address@hidden {Scheme Procedure} arity:start arity
address@hidden {Scheme Procedure} arity:end arity
address@hidden {Scheme Procedure} arity:nreq arity
address@hidden {Scheme Procedure} arity:nopt arity
address@hidden {Scheme Procedure} arity:rest? arity
address@hidden {Scheme Procedure} arity:kw arity
address@hidden {Scheme Procedure} arity:allow-other-keys? arity
+Accessors for a representation of the ``arity'' of a program.
+
+The normal case is that a procedure has one arity. For example,
address@hidden(lambda (x) x)}, takes one required argument, and that's it. One
+could access that number of required arguments via @code{(arity:nreq
+(program-arities (lambda (x) x)))}. Similarly, @code{arity:nopt} gets
+the number of optional arguments, and @code{arity:rest?} returns a true
+value if the procedure has a rest arg.
+
address@hidden:kw} returns a list of @code{(@var{kw} . @var{idx})} pairs,
+if the procedure has keyword arguments. The @var{idx} refers to the
address@hidden local variable; @xref{Variables and the VM}, for more
+information. Finally @code{arity:allow-other-keys?} returns a true
+value if other keys are allowed. @xref{Optional Arguments}, for more
+information.
+
+So what about @code{arity:start} and @code{arity:end}, then? They
+return the range of bytes in the program's bytecode for which a given
+arity is valid. You see, a procedure can actually have more than one
+arity. The question, ``what is a procedure's arity'' only really makes
+sense at certain points in the program, delimited by these
address@hidden:start} and @code{arity:end} values.
address@hidden deffn
+
 @deffn {Scheme Procedure} program-properties program
 Return the properties of a @code{program} as an association list,
 keyed by property name (a symbol). 
@@ -285,146 +300,33 @@ Accessors for specific properties.
 @node Optional Arguments
 @subsection Optional Arguments
 
address@hidden FIXME::martin: Review me!
-
 Scheme procedures, as defined in R5RS, can either handle a fixed number
 of actual arguments, or a fixed number of actual arguments followed by
 arbitrarily many additional arguments.  Writing procedures of variable
 arity can be useful, but unfortunately, the syntactic means for handling
 argument lists of varying length is a bit inconvenient.  It is possible
-to give names to the fixed number of argument, but the remaining
+to give names to the fixed number of arguments, but the remaining
 (optional) arguments can be only referenced as a list of values
 (@pxref{Lambda}).
 
-Guile comes with the module @code{(ice-9 optargs)}, which makes using
-optional arguments much more convenient.  In addition, this module
-provides syntax for handling keywords in argument lists
-(@pxref{Keywords}).
-
-Before using any of the procedures or macros defined in this section,
-you have to load the module @code{(ice-9 optargs)} with the statement:
-
address@hidden @code{optargs}
address@hidden
-(use-modules (ice-9 optargs))
address@hidden lisp
+For this reason, Guile provides an extension to @code{lambda},
address@hidden, which allows the user to define procedures with
+optional and keyword arguments. In addition, Guile's virtual machine
+has low-level support for optional and keyword argument dispatch.
+Calls to procedures with optional and keyword arguments can be made
+cheaply, without allocating a rest list.
 
 @menu
-* let-optional Reference::      Locally binding optional arguments.
-* let-keywords Reference::      Locally binding keywords arguments.
-* lambda* Reference::           Creating advanced argument handling procedures.
-* define* Reference::           Defining procedures and macros.
+* lambda* and define*::         Creating advanced argument handling procedures.
+* ice-9 optargs::               (ice-9 optargs) provides some utilities.
 @end menu
 
 
address@hidden let-optional Reference
address@hidden let-optional Reference
-
address@hidden FIXME::martin: Review me!
-
-The syntax @code{let-optional} and @code{let-optional*} are for
-destructuring rest argument lists and giving names to the various list
-elements.  @code{let-optional} binds all variables simultaneously, while
address@hidden binds them sequentially, consistent with @code{let}
-and @code{let*} (@pxref{Local Bindings}).
-
address@hidden {library syntax} let-optional rest-arg (binding @dots{}) expr 
@dots{}
address@hidden {library syntax} let-optional* rest-arg (binding @dots{}) expr 
@dots{}
-These two macros give you an optional argument interface that is very
address@hidden and introduces no fancy syntax. They are compatible with
-the scsh macros of the same name, but are slightly extended. Each of
address@hidden may be of one of the forms @var{var} or @code{(@var{var}
address@hidden)}. @var{rest-arg} should be the rest-argument of the
-procedures these are used from.  The items in @var{rest-arg} are
-sequentially bound to the variable names are given. When @var{rest-arg}
-runs out, the remaining vars are bound either to the default values or
address@hidden if no default value was specified. @var{rest-arg} remains
-bound to whatever may have been left of @var{rest-arg}.
-
-After binding the variables, the expressions @var{expr} @dots{} are
-evaluated in order.
address@hidden deffn
-
-
address@hidden let-keywords Reference
address@hidden let-keywords Reference
-
address@hidden and @code{let-keywords*} extract values from
-keyword style argument lists, binding local variables to those values
-or to defaults.
-
address@hidden {library syntax} let-keywords args allow-other-keys? (binding 
@dots{})  body @dots{}
address@hidden {library syntax} let-keywords* args allow-other-keys? (binding 
@dots{})  body @dots{}
address@hidden is evaluated and should give a list of the form
address@hidden(#:keyword1 value1 #:keyword2 value2 @dots{})}.  The
address@hidden are variables and default expressions, with the
-variables to be set (by name) from the keyword values.  The @var{body}
-forms are then evaluated and the last is the result.  An example will
-make the syntax clearest,
-
address@hidden
-(define args '(#:xyzzy "hello" #:foo "world"))
-
-(let-keywords args #t
-      ((foo  "default for foo")
-       (bar  (string-append "default" "for" "bar")))
-  (display foo)
-  (display ", ")
-  (display bar))
address@hidden world, defaultforbar
address@hidden example
-
-The binding for @code{foo} comes from the @code{#:foo} keyword in
address@hidden  But the binding for @code{bar} is the default in the
address@hidden, since there's no @code{#:bar} in the args.
-
address@hidden is evaluated and controls whether unknown
-keywords are allowed in the @var{args} list.  When true other keys are
-ignored (such as @code{#:xyzzy} in the example), when @code{#f} an
-error is thrown for anything unknown.
-
address@hidden is like @code{let} (@pxref{Local Bindings}) in
-that all bindings are made at once, the defaults expressions are
-evaluated (if needed) outside the scope of the @code{let-keywords}.
-
address@hidden is like @code{let*}, each binding is made
-successively, and the default expressions see the bindings previously
-made.  This is the style used by @code{lambda*} keywords
-(@pxref{lambda* Reference}).  For example,
-
address@hidden
-(define args '(#:foo 3))
-
-(let-keywords* args #f
-      ((foo  99)
-       (bar  (+ foo 6)))
-  (display bar))
address@hidden 9
address@hidden example
-
-The expression for each default is only evaluated if it's needed,
-ie. if the keyword doesn't appear in @var{args}.  So one way to make a
-keyword mandatory is to throw an error of some sort as the default.
-
address@hidden
-(define args '(#:start 7 #:finish 13))
-
-(let-keywords* args #t
-      ((start 0)
-       (stop  (error "missing #:stop argument")))
-  ...)
address@hidden ERROR: missing #:stop argument
address@hidden example
address@hidden deffn
-
-
address@hidden lambda* Reference
address@hidden lambda* Reference
address@hidden lambda* and define*
address@hidden lambda* and define*.
 
-When using optional and keyword argument lists, @code{lambda} for
-creating a procedure then @code{let-optional} or @code{let-keywords}
-is a bit lengthy.  @code{lambda*} combines the features of those
-macros into a single convenient syntax.
address@hidden is like @code{lambda}, except with some extensions to
+allow optional and keyword arguments.
 
 @deffn {library syntax} lambda* (address@hidden @* [#:optional address@hidden 
@* [#:key  address@hidden [#:allow-other-keys]] @* [#:rest var | . var]) @* body
 @sp 1
@@ -440,25 +342,31 @@ arguments @var{c} and @var{d}, and rest argument @var{e}. 
 If the
 optional arguments are omitted in a call, the variables for them are
 bound to @code{#f}.
 
address@hidden can also take keyword arguments.  For example, a procedure
-defined like this:
address@hidden define*
+Likewise, @code{define*} is syntactic sugar for defining procedures
+using @code{lambda*}.
+
address@hidden can also make procedures with keyword arguments. For
+example, a procedure defined like this:
 
 @lisp
-(lambda* (#:key xyzzy larch) '())
+(define* (sir-yes-sir #:key action how-high)
+  (list action how-high))
 @end lisp
 
-can be called with any of the argument lists @code{(#:xyzzy 11)},
address@hidden(#:larch 13)}, @code{(#:larch 42 #:xyzzy 19)}, @code{()}.
-Whichever arguments are given as keywords are bound to values (and
-those not given are @code{#f}).
+can be called as @code{(sir-yes-sir #:action 'jump)},
address@hidden(sir-yes-sir #:how-high 13)}, @code{(sir-yes-sir #:action
+'lay-down #:how-high 0)}, or just @code{(sir-yes-sir)}. Whichever
+arguments are given as keywords are bound to values (and those not
+given are @code{#f}).
 
 Optional and keyword arguments can also have default values to take
 when not present in a call, by giving a two-element list of variable
 name and expression.  For example in
 
 @lisp
-(lambda* (foo #:optional (bar 42) #:key (baz 73))
-     (list foo bar baz))
+(define* (frob foo #:optional (bar 42) #:key (baz 73))
+  (list foo bar baz))
 @end lisp
 
 @var{foo} is a fixed argument, @var{bar} is an optional argument with
@@ -475,9 +383,10 @@ If a call has a keyword given twice, the last value is 
used.  For
 example,
 
 @lisp
-((lambda* (#:key (heads 0) (tails 0))
-   (display (list heads tails)))
- #:heads 37 #:tails 42 #:heads 99)
+(define* (flips #:key (heads 0) (tails 0))
+  (display (list heads tails)))
+
+(flips #:heads 37 #:tails 42 #:heads 99)
 @print{} (99 42)
 @end lisp
 
@@ -499,9 +408,8 @@ Common Lisp.  For example,
 @end lisp
 
 @code{#:optional} and @code{#:key} establish their bindings
-successively, from left to right, as per @code{let-optional*} and
address@hidden  This means default expressions can refer back
-to prior parameters, for example
+successively, from left to right. This means default expressions can
+refer back to prior parameters, for example
 
 @lisp
 (lambda* (start #:optional (end (+ 10 start)))
@@ -509,48 +417,95 @@ to prior parameters, for example
       ((> i end))
     (display i)))
 @end lisp
+
+The exception to this left-to-right scoping rule is the rest argument.
+If there is a rest argument, it is bound after the optional arguments,
+but before the keyword arguments.
 @end deffn
 
 
address@hidden define* Reference
address@hidden define* Reference
address@hidden ice-9 optargs
address@hidden (ice-9 optargs)
 
address@hidden FIXME::martin: Review me!
+Before Guile 2.0, @code{lambda*} and @code{define*} were implemented
+using macros that processed rest list arguments. This was not optimal,
+as calling procedures with optional arguments had to allocate rest
+lists at every procedure invocation. Guile 2.0 improved this
+situation by bringing optional and keyword arguments into Guile's
+core.
 
-Just like @code{define} has a shorthand notation for defining procedures
-(@pxref{Lambda Alternatives}), @code{define*} is provided as an
-abbreviation of the combination of @code{define} and @code{lambda*}.
+However there are occasions in which you have a list and want to parse
+it for optional or keyword arguments. Guile's @code{(ice-9 optargs)}
+provides some macros to help with that task.
 
address@hidden is the @code{lambda*} version of
address@hidden; @code{defmacro*} and @code{defmacro*-public} exist
-for defining macros with the improved argument list handling
-possibilities.  The @code{-public} versions not only define the
-procedures/macros, but also export them from the current module.
+The syntax @code{let-optional} and @code{let-optional*} are for
+destructuring rest argument lists and giving names to the various list
+elements.  @code{let-optional} binds all variables simultaneously, while
address@hidden binds them sequentially, consistent with @code{let}
+and @code{let*} (@pxref{Local Bindings}).
+
address@hidden {library syntax} let-optional rest-arg (binding @dots{}) expr 
@dots{}
address@hidden {library syntax} let-optional* rest-arg (binding @dots{}) expr 
@dots{}
+These two macros give you an optional argument interface that is very
address@hidden and introduces no fancy syntax. They are compatible with
+the scsh macros of the same name, but are slightly extended. Each of
address@hidden may be of one of the forms @var{var} or @code{(@var{var}
address@hidden)}. @var{rest-arg} should be the rest-argument of the
+procedures these are used from.  The items in @var{rest-arg} are
+sequentially bound to the variable names are given. When @var{rest-arg}
+runs out, the remaining vars are bound either to the default values or
address@hidden if no default value was specified. @var{rest-arg} remains
+bound to whatever may have been left of @var{rest-arg}.
 
address@hidden {library syntax} define* formals body
address@hidden {library syntax} define*-public formals body
address@hidden and @code{define*-public} support optional arguments with
-a similar syntax to @code{lambda*}. They also support arbitrary-depth
-currying, just like Guile's define. Some examples:
+After binding the variables, the expressions @var{expr} @dots{} are
+evaluated in order.
address@hidden deffn
 
address@hidden
-(define* (x y #:optional a (z 3) #:key w . u)
-   (display (list y z u)))
address@hidden lisp
-defines a procedure @code{x} with a fixed argument @var{y}, an optional
-argument @var{a}, another optional argument @var{z} with default value 3,
-a keyword argument @var{w}, and a rest argument @var{u}.
+Similarly, @code{let-keywords} and @code{let-keywords*} extract values
+from keyword style argument lists, binding local variables to those
+values or to defaults.
 
address@hidden
-(define-public* ((foo #:optional bar) #:optional baz) '())
address@hidden lisp
address@hidden {library syntax} let-keywords args allow-other-keys? (binding 
@dots{})  body @dots{}
address@hidden {library syntax} let-keywords* args allow-other-keys? (binding 
@dots{})  body @dots{}
address@hidden is evaluated and should give a list of the form
address@hidden(#:keyword1 value1 #:keyword2 value2 @dots{})}.  The
address@hidden are variables and default expressions, with the
+variables to be set (by name) from the keyword values.  The @var{body}
+forms are then evaluated and the last is the result.  An example will
+make the syntax clearest,
 
-This illustrates currying. A procedure @code{foo} is defined, which,
-when called with an optional argument @var{bar}, returns a procedure
-that takes an optional argument @var{baz}.
address@hidden
+(define args '(#:xyzzy "hello" #:foo "world"))
 
-Of course, @code{define*[-public]} also supports @code{#:rest} and
address@hidden:allow-other-keys} in the same way as @code{lambda*}.
+(let-keywords args #t
+      ((foo  "default for foo")
+       (bar  (string-append "default" "for" "bar")))
+  (display foo)
+  (display ", ")
+  (display bar))
address@hidden world, defaultforbar
address@hidden example
+
+The binding for @code{foo} comes from the @code{#:foo} keyword in
address@hidden  But the binding for @code{bar} is the default in the
address@hidden, since there's no @code{#:bar} in the args.
+
address@hidden is evaluated and controls whether unknown
+keywords are allowed in the @var{args} list.  When true other keys are
+ignored (such as @code{#:xyzzy} in the example), when @code{#f} an
+error is thrown for anything unknown.
address@hidden deffn
+
address@hidden(ice-9 optargs)} also provides some more @code{define*} sugar,
+which is not so useful with modern Guile coding, but still supported:
address@hidden is the @code{lambda*} version of
address@hidden; @code{defmacro*} and @code{defmacro*-public}
+exist for defining macros with the improved argument list handling
+possibilities. The @code{-public} versions not only define the
+procedures/macros, but also export them from the current module.
+
address@hidden {library syntax} define*-public formals body
+Like a mix of @code{define*} and @code{define-public}.
 @end deffn
 
 @deffn {library syntax} defmacro* name formals body
@@ -562,29 +517,124 @@ semantics. Here is an example of a macro with an 
optional argument:
 
 @lisp
 (defmacro* transmorgify (a #:optional b)
-    (a 1))
+  (a 1))
 @end lisp
 @end deffn
 
address@hidden Case-lambda
address@hidden Case-lambda
address@hidden SRFI-16
address@hidden variable arity
address@hidden arity, variable
+
+R5RS's rest arguments are indeed useful and very general, but they
+often aren't the most appropriate or efficient means to get the job
+done. For example, @code{lambda*} is a much better solution to the
+optional argument problem than @code{lambda} with rest arguments.
+
address@hidden case-lambda
+Likewise, @code{case-lambda} works well for when you want one
+procedure to do double duty (or triple, or ...), without the penalty
+of consing a rest list.
+
+For example:
+
address@hidden
+(define (make-accum n)
+  (case-lambda
+    (() n)
+    ((m) (set! n (+ n m)) n)))
+
+(define a (make-accum 20))
+(a) @result{} 20
+(a 10) @result{} 30
+(a) @result{} 30
address@hidden lisp
+
+The value returned by a @code{case-lambda} form is a procedure which
+matches the number of actual arguments against the formals in the
+various clauses, in order. The first matching clause is selected, the
+corresponding values from the actual parameter list are bound to the
+variable names in the clauses and the body of the clause is evaluated.
+If no clause matches, an error is signalled.
+
+The syntax of the @code{case-lambda} form is defined in the following
+EBNF grammar. @dfn{Formals} means a formal argument list just like
+with @code{lambda} (@pxref{Lambda}).
+
address@hidden
address@hidden
+<case-lambda>
+   --> (case-lambda <case-lambda-clause>)
+<case-lambda-clause>
+   --> (<formals> <definition-or-command>*)
+<formals>
+   --> (<identifier>*)
+     | (<identifier>* . <identifier>)
+     | <identifier>
address@hidden group
address@hidden example
+
+Rest lists can be useful with @code{case-lambda}:
+
address@hidden
+(define plus
+  (case-lambda
+    (() 0)
+    ((a) a)
+    ((a b) (+ a b))
+    ((a b . rest) (apply plus (+ a b) rest))))
+(plus 1 2 3) @result{} 6
address@hidden lisp
+
address@hidden case-lambda*
+Also, for completeness. Guile defines @code{case-lambda*} as well,
+which is like @code{case-lambda}, except with @code{lambda*} clauses.
+A @code{case-lambda*} clause matches if the arguments fill the
+required arguments, but are not too many for the optional and/or rest
+arguments.
+
address@hidden is particularly useful in combination with an
+obscure @code{lambda*} feature, @code{#:predicate}. @code{lambda*}
+argument lists may contain a @code{#:predicate @var{expr}} clause at
+the end -- before the rest argument, if any. This expression is
+evaluated in the context of all of the arguments, and if false, causes
+the @code{case-lambda*} expression not to match. This can be used to
+make a simple form of type dispatch:
+
address@hidden
+(define type-of
+  (case-lambda*
+    ((a #:predicate (symbol? a)) 'symbol)
+    ((a #:predicate (string? a)) 'string)
+    ((a) 'unknown)))
+(type-of 'foo) @result{} symbol
+(type-of "foo") @result{} string
+(type-of '(foo)) @result{} unknown
address@hidden lisp
+
+Keyword arguments are possible with @code{case-lambda*}, but they do
+not contribute to the ``matching'' behavior. That is to say,
address@hidden matches only on required, optional, and rest
+arguments, and on the predicate; keyword arguments may be present but
+do not contribute to the ``success'' of a match. In fact a bad keyword
+argument list may cause an error to be raised.
 
 @node Procedure Properties
 @subsection Procedure Properties and Meta-information
 
address@hidden FIXME::martin: Review me!
+In addition to the information that is strictly necessary to run,
+procedures may have other associated information. For example, the
+name of a procedure is information not for the procedure, but about
+the procedure. This meta-information can be accessed via the procedure
+properties interface.
 
-Procedures always have attached the environment in which they were
-created and information about how to apply them to actual arguments.  In
-addition to that, properties and meta-information can be stored with
-procedures.  The procedures in this section can be used to test whether
-a given procedure satisfies a condition; and to access and set a
-procedure's property.
-
-The first group of procedures are predicates to test whether a Scheme
-object is a procedure, or a special procedure, respectively.
address@hidden is the most general predicates, it returns @code{#t}
-for any kind of procedure.  @code{closure?} does not return @code{#t}
-for primitive procedures, and @code{thunk?} only returns @code{#t} for
-procedures which do not accept any arguments.
+The first group of procedures in this meta-interface are predicates to
+test whether a Scheme object is a procedure, or a special procedure,
+respectively. @code{procedure?} is the most general predicates, it
+returns @code{#t} for any kind of procedure. @code{closure?} does not
+return @code{#t} for primitive procedures, and @code{thunk?} only
+returns @code{#t} for procedures which do not accept any arguments.
 
 @rnindex procedure?
 @deffn {Scheme Procedure} procedure? obj
@@ -594,7 +644,11 @@ Return @code{#t} if @var{obj} is a procedure.
 
 @deffn {Scheme Procedure} closure? obj
 @deffnx {C Function} scm_closure_p (obj)
-Return @code{#t} if @var{obj} is a closure.
+Return @code{#t} if @var{obj} is a closure. This category somewhat
+misnamed, actually, as it applies only to interpreted procedures, not
+compiled procedures. But since it has historically been used more to
+select on implementation details than on essence (closure or not), we
+keep it here for compatibility. Don't use it in new code, though.
 @end deffn
 
 @deffn {Scheme Procedure} thunk? obj
@@ -602,10 +656,9 @@ Return @code{#t} if @var{obj} is a closure.
 Return @code{#t} if @var{obj} is a thunk.
 @end deffn
 
address@hidden FIXME::martin: Is that true?
 @cindex procedure properties
-Procedure properties are general properties to be attached to
-procedures.  These can be the name of a procedure or other relevant
+Procedure properties are general properties associated with
+procedures. These can be the name of a procedure or other relevant
 information, such as debug hints.
 
 @deffn {Scheme Procedure} procedure-name proc
@@ -615,32 +668,34 @@ Return the name of the procedure @var{proc}
 
 @deffn {Scheme Procedure} procedure-source proc
 @deffnx {C Function} scm_procedure_source (proc)
-Return the source of the procedure @var{proc}.
+Return the source of the procedure @var{proc}. Returns @code{#f} if
+the source code is not available.
 @end deffn
 
 @deffn {Scheme Procedure} procedure-environment proc
 @deffnx {C Function} scm_procedure_environment (proc)
-Return the environment of the procedure @var{proc}.
+Return the environment of the procedure @var{proc}. Very deprecated.
 @end deffn
 
 @deffn {Scheme Procedure} procedure-properties proc
 @deffnx {C Function} scm_procedure_properties (proc)
-Return @var{obj}'s property list.
+Return the properties associated with @var{proc}, as an association
+list.
 @end deffn
 
address@hidden {Scheme Procedure} procedure-property obj key
address@hidden {C Function} scm_procedure_property (obj, key)
-Return the property of @var{obj} with name @var{key}.
address@hidden {Scheme Procedure} procedure-property proc key
address@hidden {C Function} scm_procedure_property (proc, key)
+Return the property of @var{proc} with name @var{key}.
 @end deffn
 
 @deffn {Scheme Procedure} set-procedure-properties! proc alist
 @deffnx {C Function} scm_set_procedure_properties_x (proc, alist)
-Set @var{obj}'s property list to @var{alist}.
+Set @var{proc}'s property list to @var{alist}.
 @end deffn
 
address@hidden {Scheme Procedure} set-procedure-property! obj key value
address@hidden {C Function} scm_set_procedure_property_x (obj, key, value)
-In @var{obj}'s property list, set the property named @var{key} to
address@hidden {Scheme Procedure} set-procedure-property! proc key value
address@hidden {C Function} scm_set_procedure_property_x (proc, key, value)
+In @var{proc}'s property list, set the property named @var{key} to
 @var{value}.
 @end deffn
 
@@ -899,6 +954,9 @@ given by the <transformer-spec>.
 @node Internal Macros
 @subsection Internal Representation of Macros and Syntax
 
+[FIXME: used to be true. Isn't any more. Use syntax-rules or
+syntax-case please :)]
+
 Internally, Guile uses three different flavors of macros.  The three
 flavors are called @dfn{acro} (or @dfn{syntax}), @dfn{macro} and
 @dfn{mmacro}.
diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi
index fbba7c5..5e8d762 100644
--- a/doc/ref/srfi-modules.texi
+++ b/doc/ref/srfi-modules.texi
@@ -1577,66 +1577,9 @@ The SRFI-14 data type and procedures are always 
available,
 @cindex variable arity
 @cindex arity, variable
 
address@hidden FIXME::martin: Review me!
-
address@hidden case-lambda
-The syntactic form @code{case-lambda} creates procedures, just like
address@hidden, but has syntactic extensions for writing procedures of
-varying arity easier.
-
-The syntax of the @code{case-lambda} form is defined in the following
-EBNF grammar.
-
address@hidden
address@hidden
-<case-lambda>
-   --> (case-lambda <case-lambda-clause>)
-<case-lambda-clause>
-   --> (<formals> <definition-or-command>*)
-<formals>
-   --> (<identifier>*)
-     | (<identifier>* . <identifier>)
-     | <identifier>
address@hidden group
address@hidden example
-
-The value returned by a @code{case-lambda} form is a procedure which
-matches the number of actual arguments against the formals in the
-various clauses, in order.  @dfn{Formals} means a formal argument list
-just like with @code{lambda} (@pxref{Lambda}). The first matching clause
-is selected, the corresponding values from the actual parameter list are
-bound to the variable names in the clauses and the body of the clause is
-evaluated.  If no clause matches, an error is signalled.
-
-The following (silly) definition creates a procedure @var{foo} which
-acts differently, depending on the number of actual arguments.  If one
-argument is given, the constant @code{#t} is returned, two arguments are
-added and if more arguments are passed, their product is calculated.
-
address@hidden
-(define foo (case-lambda
-              ((x) #t)
-              ((x y) (+ x y))
-              (z
-                (apply * z))))
-(foo 'bar)
address@hidden
-#t
-(foo 2 4)
address@hidden
-6
-(foo 3 3 3)
address@hidden
-27
-(foo)
address@hidden
-1
address@hidden lisp
-
-The last expression evaluates to 1 because the last clause is matched,
address@hidden is bound to the empty list and the following multiplication,
-applied to zero arguments, yields 1.
-
+SRFI-16 defines a variable-arity @code{lambda} form,
address@hidden This form is available in the default Guile
+environment. @xref{Case-lambda}, for more information.
 
 @node SRFI-17
 @subsection SRFI-17 - Generalized set!
diff --git a/module/system/vm/program.scm b/module/system/vm/program.scm
index 68ebb84..f02fbe6 100644
--- a/module/system/vm/program.scm
+++ b/module/system/vm/program.scm
@@ -32,8 +32,12 @@
             program-name
 
             program-bindings program-bindings-by-index program-bindings-for-ip
-            program-arities program-arguments program-lambda-list
-           
+            program-arities program-arity arity:start arity:end
+
+            arity:nreq arity:nopt arity:rest? arity:kw arity:allow-other-keys?
+
+            program-arguments program-lambda-list
+            
             program-meta
             program-objcode program? program-objects
             program-module program-base program-free-variables))
@@ -112,7 +116,6 @@
 (define (arity:allow-other-keys? a)
   (pmatch a ((_ _ ,nreq ,nopt ,rest? (,aok . ,kw)) aok) (else #f)))
 
-;; not exported; should it be?
 (define (program-arity prog ip)
   (let ((arities (program-arities prog)))
     (and arities


hooks/post-receive
-- 
GNU Guile