Reinstate `scm_protects', for backward compatibility.

[bpt/guile.git] / doc / ref / api-procedures.texi

@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 See the file guile.texi for copying conditions.

@page
@node Procedures and Macros
@section Procedures and Macros

@menu
* Lambda::                      Basic procedure creation using lambda.
* 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.
* Syntax Rules::                Support for R5RS @code{syntax-rules}.
* Syntax Case::                 Support for the @code{syntax-case} system.
* Internal Macros::             Guile's internal representation.
@end menu


@node Lambda
@subsection Lambda: Basic Procedure Creation
@cindex lambda

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
@dfn{closure} (@pxref{About Closure}).

When a procedure created by @code{lambda} is called with some actual
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 evaluated sequentially.  The result of
the last expression in the procedure body is then the result of the
procedure invocation.

The following examples will show how procedures can be created using
@code{lambda}, and what you can do with these procedures.

@lisp
(lambda (x) (+ x x))       @result{} @r{a procedure}
((lambda (x) (+ x x)) 4)   @result{} 8
@end lisp

The fact that the environment in effect when creating a procedure is
enclosed in the procedure is shown with this example:

@lisp
(define add4
  (let ((x 4))
    (lambda (y) (+ x y))))
(add4 6)                   @result{} 10
@end lisp


@deffn syntax lambda formals body
@var{formals} should be a formal argument list as described in the
following table.

@table @code
@item (@var{variable1} @dots{})
The procedure takes a fixed number of arguments; when the procedure is
called, the arguments will be stored into the newly created location for
the formal variables.
@item @var{variable}
The procedure takes any number of arguments; when the procedure is
called, the sequence of actual arguments will converted into a list and
stored into the newly created location for the formal variable.
@item (@var{variable1} @dots{} @var{variablen} . @var{variablen+1})
If a space-delimited period precedes the last variable, then the
procedure takes @var{n} or more variables where @var{n} is the number
of formal arguments before the period.  There must be at least one
argument before the period.  The first @var{n} actual arguments will be
stored into the newly allocated locations for the first @var{n} formal
arguments and the sequence of the remaining actual arguments is
converted into a list and the stored into the location for the last
formal argument.  If there are exactly @var{n} actual arguments, the
empty list is stored into the location of the last formal argument.
@end table

The list in @var{variable} or @var{variablen+1} is always newly
created and the procedure can modify it if desired.  This is the case
even when the procedure is invoked via @code{apply}, the required part
of the list argument there will be copied (@pxref{Fly Evaluation,,
Procedures for On the Fly Evaluation}).

@var{body} is a sequence of Scheme expressions which are evaluated in
order when the procedure is invoked.
@end deffn

@node Primitive Procedures
@subsection Primitive Procedures
@cindex primitives
@cindex primitive procedures

Procedures written in C can be registered for use from Scheme,
provided they take only arguments of type @code{SCM} and return
@code{SCM} values.  @code{scm_c_define_gsubr} is likely to be the most
useful mechanism, combining the process of registration
(@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
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.
@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}
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
same way as @code{scm_c_make_gsubr}, which is usually not further
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.

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 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
more accessors for low-level details on programs.

Most people won't need to use the routines described in this section,
but it's good to have them documented. You'll have to include the
appropriate module first, though:

@example
(use-modules (system vm program))
@end example

@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.
@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.
@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.

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

@deffn {Scheme Procedure} program-bindings program
@deffnx {Scheme Procedure} make-binding name boxed? index start end
@deffnx {Scheme Procedure} binding:name binding
@deffnx {Scheme Procedure} binding:boxed? binding
@deffnx {Scheme Procedure} binding:index binding
@deffnx {Scheme Procedure} binding:start binding
@deffnx {Scheme Procedure} binding:end binding
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. @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
impose a runtime performance penalty.
@end deffn

@deffn {Scheme Procedure} program-sources program
@deffnx {Scheme Procedure} source:addr source
@deffnx {Scheme Procedure} source:line source
@deffnx {Scheme Procedure} source:column source
@deffnx {Scheme Procedure} source:file source
Source location annotations for programs, along with their accessors.

Source location information propagates through the compiler and ends
up being serialized to the program's metadata. This information is
keyed by the offset of the instruction pointer within the object code
of the program. Specifically, it is keyed on the @code{ip} @emph{just
following} an instruction, so that backtraces can find the source
location of a call that is in progress.
@end deffn

@deffn {Scheme Procedure} program-arities program
@deffnx {C Function} scm_program_arities (program)
@deffnx {Scheme Procedure} program-arity program ip
@deffnx {Scheme Procedure} arity:start arity
@deffnx {Scheme Procedure} arity:end arity
@deffnx {Scheme Procedure} arity:nreq arity
@deffnx {Scheme Procedure} arity:nopt arity
@deffnx {Scheme Procedure} arity:rest? arity
@deffnx {Scheme Procedure} arity:kw arity
@deffnx {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,
@code{(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.

@code{arity:kw} returns a list of @code{(@var{kw} . @var{idx})} pairs,
if the procedure has keyword arguments. The @var{idx} refers to the
@var{idx}th 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
@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). 

Some interesting properties include:
@itemize
@item @code{name}, the name of the procedure
@item @code{documentation}, the procedure's docstring
@end itemize
@end deffn

@deffn {Scheme Procedure} program-property program name
Access a program's property by name, returning @code{#f} if not found.
@end deffn

@deffn {Scheme Procedure} program-documentation program
@deffnx {Scheme Procedure} program-name program
Accessors for specific properties.
@end deffn

@node Optional Arguments
@subsection Optional Arguments

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 arguments, but the remaining
(optional) arguments can be only referenced as a list of values
(@pxref{Lambda}).

For this reason, Guile provides an extension to @code{lambda},
@code{lambda*}, 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
* lambda* and define*::         Creating advanced argument handling procedures.
* ice-9 optargs::               (ice-9 optargs) provides some utilities.
@end menu


@node lambda* and define*
@subsubsection lambda* and define*.

@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
@sp 1
Create a procedure which takes optional and/or keyword arguments
specified with @code{#:optional} and @code{#:key}.  For example,

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

is a procedure with fixed arguments @var{a} and @var{b}, optional
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}.

@fnindex define*
Likewise, @code{define*} is syntactic sugar for defining procedures
using @code{lambda*}.

@code{lambda*} can also make procedures with keyword arguments. For
example, a procedure defined like this:

@lisp
(define* (sir-yes-sir #:key action how-high)
  (list action how-high))
@end lisp

can be called as @code{(sir-yes-sir #:action 'jump)},
@code{(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
(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
default value 42, and baz is a keyword argument with default value 73.
Default value expressions are not evaluated unless they are needed,
and until the procedure is called.

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

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

@lisp
(define* (flips #:key (heads 0) (tails 0))
  (display (list heads tails)))

(flips #:heads 37 #:tails 42 #:heads 99)
@print{} (99 42)
@end lisp

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

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

@lisp
((lambda* (#:key (x 0) #:allow-other-keys #:rest r)
   (display r))
 #:x 123 #:y 456)
@print{} (#:x 123 #:y 456)
@end lisp

@code{#:optional} and @code{#:key} establish their bindings
successively, from left to right. This means default expressions can
refer back to prior parameters, for example

@lisp
(lambda* (start #:optional (end (+ 10 start)))
  (do ((i start (1+ i)))
      ((> 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


@node ice-9 optargs
@subsubsection (ice-9 optargs)

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.

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.

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
@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{}
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
@var{binding} may be of one of the forms @var{var} or @code{(@var{var}
@var{default-value})}. @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
@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.
@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{}
@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,

@example
(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))
@print{} world, defaultforbar
@end example

The binding for @code{foo} comes from the @code{#:foo} keyword in
@code{args}.  But the binding for @code{bar} is the default in the
@code{let-keywords}, since there's no @code{#:bar} in the args.

@var{allow-other-keys?} 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.
@end deffn

@code{(ice-9 optargs)} also provides some more @code{define*} sugar,
which is not so useful with modern Guile coding, but still supported:
@code{define*-public} is the @code{lambda*} version of
@code{define-public}; @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.

@deffn {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
@deffnx {library syntax} defmacro*-public name formals body
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)
  (a 1))
@end lisp
@end deffn

@node Case-lambda
@subsection Case-lambda
@cindex SRFI-16
@cindex variable arity
@cindex 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.

@fnindex 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:

@lisp
(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
@end 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}).

@example
@group
<case-lambda>
   --> (case-lambda <case-lambda-clause>)
<case-lambda-clause>
   --> (<formals> <definition-or-command>*)
<formals>
   --> (<identifier>*)
     | (<identifier>* . <identifier>)
     | <identifier>
@end group
@end example

Rest lists can be useful with @code{case-lambda}:

@lisp
(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
@end lisp

@fnindex 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.

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.

@node Procedure Properties
@subsection Procedure Properties and Meta-information

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.

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
@deffnx {C Function} scm_procedure_p (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.
@end deffn

@cindex procedure properties
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
@deffnx {C Function} scm_procedure_name (proc)
Return the name of the procedure @var{proc}
@end deffn

@deffn {Scheme Procedure} procedure-source proc
@deffnx {C Function} scm_procedure_source (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}. 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
list.
@end deffn

@deffn {Scheme Procedure} procedure-property proc key
@deffnx {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{proc}'s property list to @var{alist}.
@end deffn

@deffn {Scheme Procedure} set-procedure-property! proc key value
@deffnx {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

@cindex procedure documentation
Documentation for a procedure can be accessed with the procedure
@code{procedure-documentation}.

@deffn {Scheme Procedure} procedure-documentation proc
@deffnx {C Function} scm_procedure_documentation (proc)
Return the documentation string associated with @code{proc}.  By
convention, if a procedure contains more than one expression and the
first expression is a string constant, that string is assumed to contain
documentation for that procedure.
@end deffn


@node Procedures with Setters
@subsection Procedures with Setters

@c FIXME::martin: Review me!

@c FIXME::martin: Document `operator struct'.

@cindex procedure with setter
@cindex setter
A @dfn{procedure with setter} is a special kind of procedure which
normally behaves like any accessor procedure, that is a procedure which
accesses a data structure.  The difference is that this kind of
procedure has a so-called @dfn{setter} attached, which is a procedure
for storing something into a data structure.

Procedures with setters are treated specially when the procedure appears
in the special form @code{set!} (REFFIXME).  How it works is best shown
by example.

Suppose we have a procedure called @code{foo-ref}, which accepts two
arguments, a value of type @code{foo} and an integer.  The procedure
returns the value stored at the given index in the @code{foo} object.
Let @code{f} be a variable containing such a @code{foo} data
structure.@footnote{Working definitions would be:
@lisp
(define foo-ref vector-ref)
(define foo-set! vector-set!)
(define f (make-vector 2 #f))
@end lisp
}

@lisp
(foo-ref f 0)       @result{} bar
(foo-ref f 1)       @result{} braz
@end lisp

Also suppose that a corresponding setter procedure called
@code{foo-set!} does exist.

@lisp
(foo-set! f 0 'bla)
(foo-ref f 0)       @result{} bla
@end lisp

Now we could create a new procedure called @code{foo}, which is a
procedure with setter, by calling @code{make-procedure-with-setter} with
the accessor and setter procedures @code{foo-ref} and @code{foo-set!}.
Let us call this new procedure @code{foo}.

@lisp
(define foo (make-procedure-with-setter foo-ref foo-set!))
@end lisp

@code{foo} can from now an be used to either read from the data
structure stored in @code{f}, or to write into the structure.

@lisp
(set! (foo f 0) 'dum)
(foo f 0)          @result{} dum
@end lisp

@deffn {Scheme Procedure} make-procedure-with-setter procedure setter
@deffnx {C Function} scm_make_procedure_with_setter (procedure, setter)
Create a new procedure which behaves like @var{procedure}, but
with the associated setter @var{setter}.
@end deffn

@deffn {Scheme Procedure} procedure-with-setter? obj
@deffnx {C Function} scm_procedure_with_setter_p (obj)
Return @code{#t} if @var{obj} is a procedure with an
associated setter procedure.
@end deffn

@deffn {Scheme Procedure} procedure proc
@deffnx {C Function} scm_procedure (proc)
Return the procedure of @var{proc}, which must be an
applicable struct.
@end deffn

@deffn {Scheme Procedure} setter proc
Return the setter of @var{proc}, which must be either a procedure with
setter or an operator struct.
@end deffn


@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

@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

@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

@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, a
syntax transformer, or a syntax-case macro.
@end deffn

@deffn {Scheme Procedure} macro-type m
@deffnx {C Function} scm_macro_type (m)
Return one of the symbols @code{syntax}, @code{macro},
@code{macro!}, or @code{syntax-case}, depending on whether
@var{m} is a syntax transformer, a regular macro, a memoizing
macro, or a syntax-case 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.
@end deffn


@c Local Variables:
@c TeX-master: "guile.texi"
@c End: