@deffn {Scheme Procedure} program? obj
@deffnx {C Function} scm_program_p (obj)
-Returns @code{#t} iff @var{obj} is a compiled procedure.
+Returns @code{#t} if @var{obj} is a compiled procedure, or @code{#f}
+otherwise.
@end deffn
-@deffn {Scheme Procedure} program-objcode program
-@deffnx {C Function} scm_program_objcode (program)
-Returns the object code associated with this program. @xref{Bytecode
-and Objcode}, for more information.
+@deffn {Scheme Procedure} program-code program
+@deffnx {C Function} scm_program_code (program)
+Returns the address of the program's entry, as an integer. This address
+is mostly useful to procedures in @code{(system vm debug)}.
@end deffn
-@deffn {Scheme Procedure} program-objects program
-@deffnx {C Function} scm_program_objects (program)
-Returns the ``object table'' associated with this program, as a
-vector. @xref{VM Programs}, for more information.
+@deffn {Scheme Procedure} program-num-free-variable program
+@deffnx {C Function} scm_program_num_free_variables (program)
+Return the number of free variables captured by this program.
@end deffn
-@deffn {Scheme Procedure} program-module program
-@deffnx {C Function} scm_program_module (program)
-Returns the module that was current when this program was created. Can
-return @code{#f} if the compiler could determine that this information
-was unnecessary.
-@end deffn
-
-@deffn {Scheme Procedure} program-free-variables program
-@deffnx {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
-@code{program-free-variables}.
-
-Some of the values captured are actually in variable ``boxes''.
-@xref{Variables and the VM}, for more information.
+@deffn {Scheme Procedure} program-free-variable-ref program n
+@deffnx {C Function} scm_program_free_variable-ref (program, n)
+@deffnx {Scheme Procedure} program-free-variable-set! program n val
+@deffnx {C Function} scm_program_free_variable_set_x (program, n, val)
+Accessors for a program's free variables. Some of the values captured
+are actually in variable ``boxes''. @xref{Variables and the VM}, for
+more information.
Users must not modify the returned value unless they think they're
really clever.
@end deffn
-@deffn {Scheme Procedure} program-meta program
-@deffnx {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:
-@code{(@var{bindings} @var{sources} @var{arities} . @var{properties})}. The format
-of each of these elements is discussed below.
-@end deffn
+@c FIXME
@deffn {Scheme Procedure} program-bindings program
@deffnx {Scheme Procedure} make-binding name boxed? index start end
For example:
@example
-(program-lambda-alist
+(program-lambda-list
(lambda* (a b #:optional c #:key (d 1) #:rest e)
#t)) @result{}
@end example
@code{lambda*} is like @code{lambda}, except with some extensions to
allow optional and keyword arguments.
-@deffn {library syntax} lambda* ([var@dots{}] @* [#:optional vardef@dots{}] @* [#:key vardef@dots{} [#:allow-other-keys]] @* [#:rest var | . var]) @* body
+@deffn {library syntax} lambda* ([var@dots{}] @* @
+ [#:optional vardef@dots{}] @* @
+ [#:key vardef@dots{} [#:allow-other-keys]] @* @
+ [#:rest var | . var]) @* @
+ body1 body2 @dots{}
@sp 1
Create a procedure which takes optional and/or keyword arguments
specified with @code{#:optional} and @code{#:key}. For example,
@example
@group
<case-lambda>
- --> (case-lambda <case-lambda-clause>)
+ --> (case-lambda <case-lambda-clause>*)
+ --> (case-lambda <docstring> <case-lambda-clause>*)
<case-lambda-clause>
--> (<formals> <definition-or-command>*)
<formals>
@lisp
(define plus
(case-lambda
+ "Return the sum of all arguments."
(() 0)
((a) a)
((a b) (+ a b))
required arguments, but are not too many for the optional and/or rest
arguments.
-Keyword arguments are possible with @code{case-lambda*}, but they do
-not contribute to the ``matching'' behavior. That is to say,
-@code{case-lambda*} 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.
+Keyword arguments are possible with @code{case-lambda*} as well, but
+they do not contribute to the ``matching'' behavior, and their
+interactions with required, optional, and rest arguments can be
+surprising.
+
+For the purposes of @code{case-lambda*} (and of @code{case-lambda}, as a
+special case), a clause @dfn{matches} if it has enough required
+arguments, and not too many positional arguments. The required
+arguments are any arguments before the @code{#:optional}, @code{#:key},
+and @code{#:rest} arguments. @dfn{Positional} arguments are the
+required arguments, together with the optional arguments.
+
+In the absence of @code{#:key} or @code{#:rest} arguments, it's easy to
+see how there could be too many positional arguments: you pass 5
+arguments to a function that only takes 4 arguments, including optional
+arguments. If there is a @code{#:rest} argument, there can never be too
+many positional arguments: any application with enough required
+arguments for a clause will match that clause, even if there are also
+@code{#:key} arguments.
+
+Otherwise, for applications to a clause with @code{#:key} arguments (and
+without a @code{#:rest} argument), a clause will match there only if
+there are enough required arguments and if the next argument after
+binding required and optional arguments, if any, is a keyword. For
+efficiency reasons, Guile is currently unable to include keyword
+arguments in the matching algorithm. Clauses match on positional
+arguments only, not by comparing a given keyword to the available set of
+keyword arguments that a function has.
+
+Some examples follow.
+
+@example
+(define f
+ (case-lambda*
+ ((a #:optional b) 'clause-1)
+ ((a #:optional b #:key c) 'clause-2)
+ ((a #:key d) 'clause-3)
+ ((#:key e #:rest f) 'clause-4)))
+
+(f) @result{} clause-4
+(f 1) @result{} clause-1
+(f) @result{} clause-4
+(f #:e 10) clause-1
+(f 1 #:foo) clause-1
+(f 1 #:c 2) clause-2
+(f #:a #:b #:c #:d #:e) clause-4
+
+;; clause-2 will match anything that clause-3 would match.
+(f 1 #:d 2) @result{} error: bad keyword args in clause 2
+@end example
+
+Don't forget that the clauses are matched in order, and the first
+matching clause will be taken. This can result in a keyword being bound
+to a required argument, as in the case of @code{f #:e 10}.
+
@node Higher-Order Functions
@subsection Higher-Order Functions
Return X.
@end deffn
+@deffn {Scheme Procedure} and=> value proc
+When @var{value} is @code{#f}, return @code{#f}. Otherwise, return
+@code{(@var{proc} @var{value})}.
+@end deffn
+
@node Procedure Properties
@subsection Procedure Properties and Meta-information
HCoop / bpt / guile.git / blobdiff