@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009
-@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 and Macros
-@section Procedures and Macros
+@node Procedures
+@section Procedures
@menu
* Lambda:: Basic procedure creation using lambda.
* 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.
-* Macros:: Lisp style macro definitions.
-* Syntax Rules:: Support for R5RS @code{syntax-rules}.
-* Syntax Case:: Support for the @code{syntax-case} system.
-* Internal Macros:: Guile's internal representation.
+* Inlinable Procedures:: Procedures that can be inlined.
@end menu
arguments, the environment enclosed in the procedure is extended by
binding the variables named in the formal argument list to new locations
and storing the actual arguments into these locations. Then the body of
-the @code{lambda} expression is evaluation sequentially. The result of
+the @code{lambda} expression is evaluated sequentially. The result of
the last expression in the procedure body is then the result of the
procedure invocation.
(@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
required, optional and ``rest'' arguments respectively. The total
number of these arguments should match the actual number of arguments
-to @var{fcn}. The number of rest arguments should be 0 or 1.
+to @var{fcn}, but may not exceed 10. The number of rest arguments should be 0 or 1.
@code{scm_c_make_gsubr} returns a value of type @code{SCM} which is a
``handle'' for the procedure.
@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.
-@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.
+Returns @code{#t} if @var{obj} is a compiled procedure, or @code{#f}
+otherwise.
@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-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-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.
+@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-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
@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
@deffn {Scheme Procedure} procedure proc
@deffnx {C Function} scm_procedure (proc)
-Return the procedure of @var{proc}, which must be either a
-procedure with setter, or an operator struct.
+Return the procedure of @var{proc}, which must be an
+applicable struct.
@end deffn
@deffn {Scheme Procedure} setter proc
setter or an operator struct.
@end deffn
+@node Inlinable Procedures
+@subsection Inlinable Procedures
-@node Macros
-@subsection Lisp Style Macro Definitions
-
-@cindex macros
-@cindex transformation
-Macros are objects which cause the expression that they appear in to be
-transformed in some way @emph{before} being evaluated. In expressions
-that are intended for macro transformation, the identifier that names
-the relevant macro must appear as the first element, like this:
-
-@lisp
-(@var{macro-name} @var{macro-args} @dots{})
-@end lisp
-
-In Lisp-like languages, the traditional way to define macros is very
-similar to procedure definitions. The key differences are that the
-macro definition body should return a list that describes the
-transformed expression, and that the definition is marked as a macro
-definition (rather than a procedure definition) by the use of a
-different definition keyword: in Lisp, @code{defmacro} rather than
-@code{defun}, and in Scheme, @code{define-macro} rather than
-@code{define}.
-
-@fnindex defmacro
-@fnindex define-macro
-Guile supports this style of macro definition using both @code{defmacro}
-and @code{define-macro}. The only difference between them is how the
-macro name and arguments are grouped together in the definition:
-
-@lisp
-(defmacro @var{name} (@var{args} @dots{}) @var{body} @dots{})
-@end lisp
-
-@noindent
-is the same as
+@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.
-@lisp
-(define-macro (@var{name} @var{args} @dots{}) @var{body} @dots{})
-@end lisp
-
-@noindent
-The difference is analogous to the corresponding difference between
-Lisp's @code{defun} and Scheme's @code{define}.
-
-@code{false-if-exception}, from the @file{boot-9.scm} file in the Guile
-distribution, is a good example of macro definition using
-@code{defmacro}:
-
-@lisp
-(defmacro false-if-exception (expr)
- `(catch #t
- (lambda () ,expr)
- (lambda args #f)))
-@end lisp
+@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:
-@noindent
-The effect of this definition is that expressions beginning with the
-identifier @code{false-if-exception} are automatically transformed into
-a @code{catch} expression following the macro definition specification.
-For example:
-
-@lisp
-(false-if-exception (open-input-file "may-not-exist"))
-@equiv{}
-(catch #t
- (lambda () (open-input-file "may-not-exist"))
- (lambda args #f))
-@end lisp
-
-
-@node Syntax Rules
-@subsection The R5RS @code{syntax-rules} System
-@cindex R5RS syntax-rules system
-
-R5RS defines an alternative system for macro and syntax transformations
-using the keywords @code{define-syntax}, @code{let-syntax},
-@code{letrec-syntax} and @code{syntax-rules}.
-
-The main difference between the R5RS system and the traditional macros
-of the previous section is how the transformation is specified. In
-R5RS, rather than permitting a macro definition to return an arbitrary
-expression, the transformation is specified in a pattern language that
-
-@itemize @bullet
-@item
-does not require complicated quoting and extraction of components of the
-source expression using @code{caddr} etc.
-
-@item
-is designed such that the bindings associated with identifiers in the
-transformed expression are well defined, and such that it is impossible
-for the transformed expression to construct new identifiers.
-@end itemize
-
-@noindent
-The last point is commonly referred to as being @dfn{hygienic}: the R5RS
-@code{syntax-case} system provides @dfn{hygienic macros}.
-
-For example, the R5RS pattern language for the @code{false-if-exception}
-example of the previous section looks like this:
-
-@lisp
-(syntax-rules ()
- ((_ expr)
- (catch #t
- (lambda () expr)
- (lambda args #f))))
-@end lisp
-
-@cindex @code{syncase}
-In Guile, the @code{syntax-rules} system is provided by the @code{(ice-9
-syncase)} module. To make these facilities available in your code,
-include the expression @code{(use-syntax (ice-9 syncase))} (@pxref{Using
-Guile Modules}) before the first usage of @code{define-syntax} etc. If
-you are writing a Scheme module, you can alternatively include the form
-@code{#:use-syntax (ice-9 syncase)} in your @code{define-module}
-declaration (@pxref{Creating Guile Modules}).
-
-@menu
-* Pattern Language:: The @code{syntax-rules} pattern language.
-* Define-Syntax:: Top level syntax definitions.
-* Let-Syntax:: Local syntax definitions.
-@end menu
-
-
-@node Pattern Language
-@subsubsection The @code{syntax-rules} Pattern Language
-
-
-@node Define-Syntax
-@subsubsection Top Level Syntax Definitions
-
-define-syntax: The gist is
-
- (define-syntax <keyword> <transformer-spec>)
-
-makes the <keyword> into a macro so that
-
- (<keyword> ...)
-
-expands at _compile_ or _read_ time (i.e. before any
-evaluation begins) into some expression that is
-given by the <transformer-spec>.
-
-
-@node Let-Syntax
-@subsubsection Local Syntax Definitions
-
-
-@node Syntax Case
-@subsection Support for the @code{syntax-case} System
-
-
-
-@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}.
-
-Given the expression
-
-@lisp
-(foo @dots{})
-@end lisp
+@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
-with @code{foo} being some flavor of macro, one of the following things
-will happen when the expression is evaluated.
-
-@itemize @bullet
-@item
-When @code{foo} has been defined to be an @dfn{acro}, the procedure used
-in the acro definition of @code{foo} is passed the whole expression and
-the current lexical environment, and whatever that procedure returns is
-the value of evaluating the expression. You can think of this a
-procedure that receives its argument as an unevaluated expression.
-
-@item
-When @code{foo} has been defined to be a @dfn{macro}, the procedure used
-in the macro definition of @code{foo} is passed the whole expression and
-the current lexical environment, and whatever that procedure returns is
-evaluated again. That is, the procedure should return a valid Scheme
-expression.
-
-@item
-When @code{foo} has been defined to be a @dfn{mmacro}, the procedure
-used in the mmacro definition of `foo' is passed the whole expression
-and the current lexical environment, and whatever that procedure returns
-replaces the original expression. Evaluation then starts over from the
-new expression that has just been returned.
-@end itemize
-
-The key difference between a @dfn{macro} and a @dfn{mmacro} is that the
-expression returned by a @dfn{mmacro} procedure is remembered (or
-@dfn{memoized}) so that the expansion does not need to be done again
-next time the containing code is evaluated.
-
-The primitives @code{procedure->syntax}, @code{procedure->macro} and
-@code{procedure->memoizing-macro} are used to construct acros, macros
-and mmacros respectively. However, if you do not have a very special
-reason to use one of these primitives, you should avoid them: they are
-very specific to Guile's current implementation and therefore likely to
-change. Use @code{defmacro}, @code{define-macro} (@pxref{Macros}) or
-@code{define-syntax} (@pxref{Syntax Rules}) instead. (In low level
-terms, @code{defmacro}, @code{define-macro} and @code{define-syntax} are
-all implemented as mmacros.)
-
-@deffn {Scheme Procedure} procedure->syntax code
-@deffnx {C Function} scm_makacro (code)
-Return a macro which, when a symbol defined to this value appears as the
-first symbol in an expression, returns the result of applying @var{code}
-to the expression and the environment.
-@end deffn
-
-@deffn {Scheme Procedure} procedure->macro code
-@deffnx {C Function} scm_makmacro (code)
-Return a macro which, when a symbol defined to this value appears as the
-first symbol in an expression, evaluates the result of applying
-@var{code} to the expression and the environment. For example:
-
-@lisp
-(define trace
- (procedure->macro
- (lambda (x env)
- `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))
-
-(trace @i{foo})
-@equiv{}
-(set! @i{foo} (tracef @i{foo} '@i{foo})).
-@end lisp
-@end deffn
-
-@deffn {Scheme Procedure} procedure->memoizing-macro code
-@deffnx {C Function} scm_makmmacro (code)
-Return a macro which, when a symbol defined to this value appears as the
-first symbol in an expression, evaluates the result of applying
-@var{code} to the expression and the environment.
-@code{procedure->memoizing-macro} is the same as
-@code{procedure->macro}, except that the expression returned by
-@var{code} replaces the original macro expression in the memoized form
-of the containing code.
-@end deffn
-
-In the following primitives, @dfn{acro} flavor macros are referred to
-as @dfn{syntax transformers}.
-
-@deffn {Scheme Procedure} macro? obj
-@deffnx {C Function} scm_macro_p (obj)
-Return @code{#t} if @var{obj} is a regular macro, a memoizing macro or a
-syntax transformer.
-@end deffn
-
-@deffn {Scheme Procedure} macro-type m
-@deffnx {C Function} scm_macro_type (m)
-Return one of the symbols @code{syntax}, @code{macro} or
-@code{macro!}, depending on whether @var{m} is a syntax
-transformer, a regular macro, or a memoizing macro,
-respectively. If @var{m} is not a macro, @code{#f} is
-returned.
-@end deffn
-
-@deffn {Scheme Procedure} macro-name m
-@deffnx {C Function} scm_macro_name (m)
-Return the name of the macro @var{m}.
-@end deffn
-
-@deffn {Scheme Procedure} macro-transformer m
-@deffnx {C Function} scm_macro_transformer (m)
-Return the transformer of the macro @var{m}.
-@end deffn
-
-@deffn {Scheme Procedure} cons-source xorig x y
-@deffnx {C Function} scm_cons_source (xorig, x, y)
-Create and return a new pair whose car and cdr are @var{x} and @var{y}.
-Any source properties associated with @var{xorig} are also associated
-with the new pair.
+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"
@c End:
HCoop / bpt / guile.git / blobdiff