@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2010
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2010,
+@c 2011, 2012, 2013 Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
-@page
@node Procedures
@section Procedures
* Compiled Procedures:: Scheme procedures can be compiled.
* Optional Arguments:: Handling keyword, optional and rest arguments.
* Case-lambda:: One function, multiple arities.
+* Higher-Order Functions:: Function that take or return functions.
* Procedure Properties:: Procedure properties and meta-information.
* Procedures with Setters:: Procedures with setters.
+* Inlinable Procedures:: Procedures that can be inlined.
@end menu
(@code{scm_c_make_gsubr}) and definition (@code{scm_define}).
@deftypefun SCM scm_c_make_gsubr (const char *name, int req, int opt, int rst, fcn)
-Register a C procedure @var{FCN} as a ``subr'' --- a primitive
+Register a C procedure @var{fcn} as a ``subr'' --- a primitive
subroutine that can be called from Scheme. It will be associated with
the given @var{name} but no environment binding will be created. The
arguments @var{req}, @var{opt} and @var{rst} specify the number of
@end deftypefun
@deftypefun SCM scm_c_define_gsubr (const char *name, int req, int opt, int rst, fcn)
-Register a C procedure @var{FCN}, as for @code{scm_c_make_gsubr}
+Register a C procedure @var{fcn}, as for @code{scm_c_make_gsubr}
above, and additionally create a top-level Scheme binding for the
procedure in the ``current environment'' using @code{scm_define}.
@code{scm_c_define_gsubr} returns a handle for the procedure in the
required.
@end deftypefun
-@code{scm_c_make_gsubr} and @code{scm_c_define_gsubr} automatically
-use @code{scm_c_make_subr} and also @code{scm_makcclo} if necessary.
-It is advisable to use the gsubr variants since they provide a
-slightly higher-level abstraction of the Guile implementation.
-
@node Compiled Procedures
@subsection 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.
+The evaluation strategy given in @ref{Lambda} describes how procedures
+are @dfn{interpreted}. Interpretation operates directly on expanded
+Scheme source code, recursively calling the evaluator to obtain the
+value of nested expressions.
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.
+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 files is the normal way that compiled procedures come to
being. If Guile sees that a file is uncompiled, or that its compiled
@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
@code{arity:start} and @code{arity:end} values.
@end deffn
-@deffn {Scheme Procedure} program-properties program
-Return the properties of a @code{program} as an association list,
-keyed by property name (a symbol).
+@deffn {Scheme Procedure} program-arguments-alist program [ip]
+Return an association list describing the arguments that @var{program} accepts, or
+@code{#f} if the information cannot be obtained.
-Some interesting properties include:
-@itemize
-@item @code{name}, the name of the procedure
-@item @code{documentation}, the procedure's docstring
-@end itemize
-@end deffn
+The alist keys that are currently defined are `required', `optional',
+`keyword', `allow-other-keys?', and `rest'. For example:
-@deffn {Scheme Procedure} program-property program name
-Access a program's property by name, returning @code{#f} if not found.
+@example
+(program-arguments-alist
+ (lambda* (a b #:optional c #:key (d 1) #:rest e)
+ #t)) @result{}
+((required . (a b))
+ (optional . (c))
+ (keyword . ((#:d . 4)))
+ (allow-other-keys? . #f)
+ (rest . d))
+@end example
@end deffn
-@deffn {Scheme Procedure} program-documentation program
-@deffnx {Scheme Procedure} program-name program
-Accessors for specific properties.
+@deffn {Scheme Procedure} program-lambda-list program [ip]
+Return a representation of the arguments of @var{program} as a lambda
+list, or @code{#f} if this information is not available.
+
+For example:
+
+@example
+(program-lambda-list
+ (lambda* (a b #:optional c #:key (d 1) #:rest e)
+ #t)) @result{}
+@end example
@end deffn
@node Optional Arguments
@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,
@code{let-optional*} binds them sequentially, consistent with @code{let}
and @code{let*} (@pxref{Local Bindings}).
-@deffn {library syntax} let-optional rest-arg (binding @dots{}) expr @dots{}
-@deffnx {library syntax} let-optional* rest-arg (binding @dots{}) expr @dots{}
+@deffn {library syntax} let-optional rest-arg (binding @dots{}) body1 body2 @dots{}
+@deffnx {library syntax} let-optional* rest-arg (binding @dots{}) body1 body2 @dots{}
These two macros give you an optional argument interface that is very
@dfn{Schemey} and introduces no fancy syntax. They are compatible with
the scsh macros of the same name, but are slightly extended. Each of
@code{#f} 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.
+After binding the variables, the expressions @var{body1} @var{body2} @dots{}
+are evaluated in order.
@end deffn
Similarly, @code{let-keywords} and @code{let-keywords*} extract values
from keyword style argument lists, binding local variables to those
values or to defaults.
-@deffn {library syntax} let-keywords args allow-other-keys? (binding @dots{}) body @dots{}
-@deffnx {library syntax} let-keywords* args allow-other-keys? (binding @dots{}) body @dots{}
+@deffn {library syntax} let-keywords args allow-other-keys? (binding @dots{}) body1 body2 @dots{}
+@deffnx {library syntax} let-keywords* args allow-other-keys? (binding @dots{}) body1 body2 @dots{}
@var{args} is evaluated and should give a list of the form
@code{(#:keyword1 value1 #:keyword2 value2 @dots{})}. The
-@var{binding}s 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,
+@var{binding}s are variables and default expressions, with the variables
+to be set (by name) from the keyword values. The @var{body1}
+@var{body2} @dots{} forms are then evaluated and the last is the
+result. An example will make the syntax clearest,
@example
(define args '(#:xyzzy "hello" #:foo "world"))
possibilities. The @code{-public} versions not only define the
procedures/macros, but also export them from the current module.
-@deffn {library syntax} define*-public formals body
+@deffn {library syntax} define*-public formals body1 body2 @dots{}
Like a mix of @code{define*} and @code{define-public}.
@end deffn
-@deffn {library syntax} defmacro* name formals body
-@deffnx {library syntax} defmacro*-public name formals body
+@deffn {library syntax} defmacro* name formals body1 body2 @dots{}
+@deffnx {library syntax} defmacro*-public name formals body1 body2 @dots{}
These are just like @code{defmacro} and @code{defmacro-public} except that they
take @code{lambda*}-style extended parameter lists, where @code{#:optional},
@code{#:key}, @code{#:allow-other-keys} and @code{#:rest} are allowed with the usual
semantics. Here is an example of a macro with an optional argument:
@lisp
-(defmacro* transmorgify (a #:optional b)
+(defmacro* transmogrify (a #:optional b)
(a 1))
@end lisp
@end deffn
@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
+
+@cindex higher-order functions
+
+As a functional programming language, Scheme allows the definition of
+@dfn{higher-order functions}, i.e., functions that take functions as
+arguments and/or return functions. Utilities to derive procedures from
+other procedures are provided and described below.
+
+@deffn {Scheme Procedure} const value
+Return a procedure that accepts any number of arguments and returns
+@var{value}.
+
+@lisp
+(procedure? (const 3)) @result{} #t
+((const 'hello)) @result{} hello
+((const 'hello) 'world) @result{} hello
+@end lisp
+@end deffn
+
+@deffn {Scheme Procedure} negate proc
+Return a procedure with the same arity as @var{proc} that returns the
+@code{not} of @var{proc}'s result.
+
+@lisp
+(procedure? (negate number?)) @result{} #t
+((negate odd?) 2) @result{} #t
+((negate real?) 'dream) @result{} #t
+((negate string-prefix?) "GNU" "GNU Guile")
+ @result{} #f
+(filter (negate number?) '(a 2 "b"))
+ @result{} (a "b")
+@end lisp
+@end deffn
+
+@deffn {Scheme Procedure} compose proc1 proc2 @dots{}
+Compose @var{proc1} with the procedures @var{proc2} @dots{} such that
+the last @var{proc} argument is applied first and @var{proc1} last, and
+return the resulting procedure. The given procedures must have
+compatible arity.
+
+@lisp
+(procedure? (compose 1+ 1-)) @result{} #t
+((compose sqrt 1+ 1+) 2) @result{} 2.0
+((compose 1+ sqrt) 3) @result{} 2.73205080756888
+(eq? (compose 1+) 1+) @result{} #t
+
+((compose zip unzip2) '((1 2) (a b)))
+ @result{} ((1 2) (a b))
+@end lisp
+@end deffn
+
+@deffn {Scheme Procedure} identity x
+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
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.
+respectively. @code{procedure?} is the most general predicates, it
+returns @code{#t} for any kind of procedure.
@rnindex procedure?
@deffn {Scheme Procedure} procedure? obj
Return @code{#t} if @var{obj} is a procedure.
@end deffn
-@deffn {Scheme Procedure} closure? obj
-@deffnx {C Function} scm_closure_p (obj)
-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
@deffnx {C Function} scm_thunk_p (obj)
-Return @code{#t} if @var{obj} is a thunk.
+Return @code{#t} if @var{obj} is a thunk---a procedure that does
+not accept arguments.
@end deffn
@cindex procedure properties
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}. Very deprecated.
-@end deffn
-
@deffn {Scheme Procedure} procedure-properties proc
@deffnx {C Function} scm_procedure_properties (proc)
Return the properties associated with @var{proc}, as an association
setter or an operator struct.
@end deffn
+@node Inlinable Procedures
+@subsection Inlinable Procedures
+
+@cindex inlining
+@cindex procedure inlining
+You can define an @dfn{inlinable procedure} by using
+@code{define-inlinable} instead of @code{define}. An inlinable
+procedure behaves the same as a regular procedure, but direct calls will
+result in the procedure body being inlined into the caller.
+
+@cindex partial evaluator
+Bear in mind that starting from version 2.0.3, Guile has a partial
+evaluator that can inline the body of inner procedures when deemed
+appropriate:
+
+@example
+scheme@@(guile-user)> ,optimize (define (foo x)
+ (define (bar) (+ x 3))
+ (* (bar) 2))
+$1 = (define foo
+ (lambda (#@{x 94@}#) (* (+ #@{x 94@}# 3) 2)))
+@end example
+
+@noindent
+The partial evaluator does not inline top-level bindings, though, so
+this is a situation where you may find it interesting to use
+@code{define-inlinable}.
+
+Procedures defined with @code{define-inlinable} are @emph{always}
+inlined, at all direct call sites. This eliminates function call
+overhead at the expense of an increase in code size. Additionally, the
+caller will not transparently use the new definition if the inline
+procedure is redefined. It is not possible to trace an inlined
+procedures or install a breakpoint in it (@pxref{Traps}). For these
+reasons, you should not make a procedure inlinable unless it
+demonstrably improves performance in a crucial way.
+
+In general, only small procedures should be considered for inlining, as
+making large procedures inlinable will probably result in an increase in
+code size. Additionally, the elimination of the call overhead rarely
+matters for large procedures.
+
+@deffn {Scheme Syntax} define-inlinable (name parameter @dots{}) body1 body2 @dots{}
+Define @var{name} as a procedure with parameters @var{parameter}s and
+bodies @var{body1}, @var{body2}, @enddots{}.
+@end deffn
@c Local Variables:
@c TeX-master: "guile.texi"
HCoop / bpt / guile.git / blobdiff