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

@page
@node Macros
@section Macros

At its best, programming in Lisp is an iterative process of building up a
language appropriate to the problem at hand, and then solving the problem in
that language. Defining new procedures is part of that, but Lisp also allows
the user to extend its syntax, with its famous @dfn{macros}.

@cindex macros
@cindex transformation
Macros are syntactic extensions 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

@cindex macro expansion
Macro expansion is a separate phase of evaluation, run before code is
interpreted or compiled. A macro is a program that runs on programs, translating
an embedded language into core Scheme.

@menu
* Defining Macros::             Binding macros, globally and locally.
* Syntax Rules::                Pattern-driven macros.
* Syntax Case::                 Procedural, hygienic macros.
* Defmacros::                   Lisp-style macros.
* Identifier Macros::           Identifier macros.
* Eval When::                   Affecting the expand-time environment.
* Internal Macros::             Macros as first-class values.
@end menu

@node Defining Macros
@subsection Defining Macros

A macro is a binding between a keyword and a syntax transformer. Since it's
difficult to discuss @code{define-syntax} without discussing the format of
transformers, consider the following example macro definition:

@example
(define-syntax when
  (syntax-rules ()
    ((when condition exp ...)
     (if condition
         (begin exp ...)))))

(when #t
  (display "hey ho\n")
  (display "let's go\n"))
@print{} hey ho
@print{} let's go
@end example

In this example, the @code{when} binding is bound with @code{define-syntax}.
Syntax transformers are discussed in more depth in @ref{Syntax Rules} and
@ref{Syntax Case}.

@deffn {Syntax} define-syntax keyword transformer
Bind @var{keyword} to the syntax transformer obtained by evaluating
@var{transformer}.

After a macro has been defined, further instances of @var{keyword} in Scheme
source code will invoke the syntax transformer defined by @var{transformer}.
@end deffn

One can also establish local syntactic bindings with @code{let-syntax}.

@deffn {Syntax} let-syntax ((keyword transformer) ...) exp...
Bind @var{keyword...} to @var{transformer...} while expanding @var{exp...}.

A @code{let-syntax} binding only exists at expansion-time.

@example
(let-syntax ((unless
              (syntax-rules ()
                ((unless condition exp ...)
                 (if (not condition)
                     (begin exp ...))))))
  (unless #t
    (primitive-exit 1))
  "rock rock rock")
@result{} "rock rock rock"
@end example
@end deffn

A @code{define-syntax} form is valid anywhere a definition may appear: at the
top-level, or locally. Just as a local @code{define} expands out to an instance
of @code{letrec}, a local @code{define-syntax} expands out to
@code{letrec-syntax}.

@deffn {Syntax} letrec-syntax ((keyword transformer) ...) exp...
Bind @var{keyword...} to @var{transformer...} while expanding @var{exp...}.

In the spirit of @code{letrec} versus @code{let}, an expansion produced by
@var{transformer} may reference a @var{keyword} bound by the
same @var{letrec-syntax}.

@example
(letrec-syntax ((my-or
                 (syntax-rules ()
                   ((my-or)
                    #t)
                   ((my-or exp)
                    exp)
                   ((my-or exp rest ...)
                    (let ((t exp))
                      (if exp
                          exp
                          (my-or rest ...)))))))
  (my-or #f "rockaway beach"))
@result{} "rockaway beach"
@end example
@end deffn

@node Syntax Rules
@subsection Syntax-rules Macros

@code{syntax-rules} macros are simple, pattern-driven syntax transformers, with
a beauty worthy of Scheme.

@deffn {Syntax} syntax-rules literals (pattern template)...
Create a syntax transformer that will rewrite an expression using the rules
embodied in the @var{pattern} and @var{template} clauses.
@end deffn

A @code{syntax-rules} macro consists of three parts: the literals (if any), the
patterns, and as many templates as there are patterns.

When the syntax expander sees the invocation of a @code{syntax-rules} macro, it
matches the expression against the patterns, in order, and rewrites the
expression using the template from the first matching pattern. If no pattern
matches, a syntax error is signalled.

@subsubsection Patterns

We have already seen some examples of patterns in the previous section:
@code{(unless condition exp ...)}, @code{(my-or exp)}, and so on. A pattern is
structured like the expression that it is to match. It can have nested structure
as well, like @code{(let ((var val) ...) exp exp* ...)}. Broadly speaking,
patterns are made of lists, improper lists, vectors, identifiers, and datums.
Users can match a sequence of patterns using the ellipsis (@code{...}).

Identifiers in a pattern are called @dfn{literals} if they are present in the
@code{syntax-rules} literals list, and @dfn{pattern variables} otherwise. When
building up the macro output, the expander replaces instances of a pattern
variable in the template with the matched subexpression.

@example
(define-syntax kwote
  (syntax-rules ()
    ((kwote exp)
     (quote exp))))
(kwote (foo . bar))
@result{} (foo . bar)
@end example

An improper list of patterns matches as rest arguments do:

@example
(define-syntax let1
  (syntax-rules ()
    ((_ (var val) . exps)
     (let ((var val)) . exps))))
@end example

However this definition of @code{let1} probably isn't what you want, as the tail
pattern @var{exps} will match non-lists, like @code{(let1 (foo 'bar) . baz)}. So
often instead of using improper lists as patterns, ellipsized patterns are
better. Instances of a pattern variable in the template must be followed by an
ellipsis.

@example
(define-syntax let1
  (syntax-rules ()
    ((_ (var val) exp ...)
     (let ((var val)) exp ...))))
@end example

This @code{let1} probably still doesn't do what we want, because the body
matches sequences of zero expressions, like @code{(let1 (foo 'bar))}. In this
case we need to assert we have at least one body expression. A common idiom for
this is to name the ellipsized pattern variable with an asterisk:

@example
(define-syntax let1
  (syntax-rules ()
    ((_ (var val) exp exp* ...)
     (let ((var val)) exp exp* ...))))
@end example

A vector of patterns matches a vector whose contents match the patterns,
including ellipsizing and tail patterns.

@example
(define-syntax letv
  (syntax-rules ()
    ((_ #((var val) ...) exp exp* ...)
     (let ((var val) ...) exp exp* ...))))
(letv #((foo 'bar)) foo)
@result{} foo
@end example

Literals are used to match specific datums in an expression, like the use of
@code{=>} and @code{else} in @code{cond} expressions.

@example
(define-syntax cond1
  (syntax-rules (=> else)
    ((cond1 test => fun)
     (let ((exp test))
       (if exp (fun exp) #f)))
    ((cond1 test exp exp* ...)
     (if test (begin exp exp* ...)))
    ((cond1 else exp exp* ...)
     (begin exp exp* ...))))

(define (square x) (* x x))
(cond1 10 => square)
@result{} 100
(let ((=> #t))
  (cond1 10 => square))
@result{} #<procedure square (x)>
@end example

A literal matches an input expression if the input expression is an identifier
with the same name as the literal, and both are unbound@footnote{Language
lawyers probably see the need here for use of @code{literal-identifier=?} rather
than @code{free-identifier=?}, and would probably be correct. Patches
accepted.}.

If a pattern is not a list, vector, or an identifier, it matches as a literal,
with @code{equal?}.

@example
(define-syntax define-matcher-macro
  (syntax-rules ()
    ((_ name lit)
     (define-syntax name
       (syntax-rules ()
        ((_ lit) #t)
        ((_ else) #f))))))

(define-matcher-macro is-literal-foo? "foo")

(is-literal-foo? "foo")
@result{} #t
(is-literal-foo? "bar")
@result{} #f
(let ((foo "foo"))
  (is-literal-foo? foo))
@result{} #f
@end example

The last example indicates that matching happens at expansion-time, not
at run-time.

Syntax-rules macros are always used as @code{(@var{macro} . @var{args})}, and
the @var{macro} will always be a symbol. Correspondingly, a @code{syntax-rules}
pattern must be a list (proper or improper), and the first pattern in that list
must be an identifier. Incidentally it can be any identifier -- it doesn't have
to actually be the name of the macro. Thus the following three are equivalent:

@example
(define-syntax when
  (syntax-rules ()
    ((when c e ...)
     (if c (begin e ...)))))

(define-syntax when
  (syntax-rules ()
    ((_ c e ...)
     (if c (begin e ...)))))

(define-syntax when
  (syntax-rules ()
    ((something-else-entirely c e ...)
     (if c (begin e ...)))))
@end example

For clarity, use one of the first two variants. Also note that since the pattern
variable will always match the macro itself (e.g., @code{cond1}), it is actually
left unbound in the template.

@subsubsection Hygiene

@code{syntax-rules} macros have a magical property: they preserve referential
transparency. When you read a macro definition, any free bindings in that macro
are resolved relative to the macro definition; and when you read a macro
instantiation, all free bindings in that expression are resolved relative to the
expression.

This property is sometimes known as @dfn{hygiene}, and it does aid in code
cleanliness. In your macro definitions, you can feel free to introduce temporary
variables, without worrying about inadvertantly introducing bindings into the
macro expansion.

Consider the definition of @code{my-or} from the previous section:

@example
(define-syntax my-or
  (syntax-rules ()
    ((my-or)
     #t)
    ((my-or exp)
     exp)
    ((my-or exp rest ...)
     (let ((t exp))
       (if exp
           exp
           (my-or rest ...))))))
@end example

A naive expansion of @code{(let ((t #t)) (my-or #f t))} would yield:

@example
(let ((t #t))
  (let ((t #f))
    (if t t t)))
@result{} #f
@end example

@noindent
Which clearly is not what we want. Somehow the @code{t} in the definition is
distinct from the @code{t} at the site of use; and it is indeed this distinction
that is maintained by the syntax expander, when expanding hygienic macros.

This discussion is mostly relevant in the context of traditional Lisp macros
(@pxref{Defmacros}), which do not preserve referential transparency. Hygiene
adds to the expressive power of Scheme.

@subsubsection Further Information

For a formal definition of @code{syntax-rules} and its pattern language, see
@xref{Macros, , Macros, r5rs, Revised(5) Report on the Algorithmic Language
Scheme}.

@code{syntax-rules} macros are simple and clean, but do they have limitations.
They do not lend themselves to expressive error messages: patterns either match
or they don't. Their ability to generate code is limited to template-driven
expansion; often one needs to define a number of helper macros to get real work
done. Sometimes one wants to introduce a binding into the lexical context of the
generated code; this is impossible with @code{syntax-rules}. Relatedly, they
cannot programmatically generate identifiers.

The solution to all of these problems is to use @code{syntax-case} if you need
its features. But if for some reason you're stuck with @code{syntax-rules}, you
might enjoy Joe Marshall's
@uref{http://sites.google.com/site/evalapply/eccentric.txt,@code{syntax-rules}
Primer for the Merely Eccentric}.

@node Syntax Case
@subsection Support for the @code{syntax-case} System

@code{syntax-case} macros are procedural syntax transformers, with a power
worthy of Scheme.

@deffn {Syntax} syntax-case syntax literals (pattern [guard] exp)...
Match the syntax object @var{syntax} against the given patterns, in order. If a
@var{pattern} matches, return the result of evaluating the associated @var{exp}.
@end deffn

Compare the following definitions of @code{when}:

@example
(define-syntax when
  (syntax-rules ()
    ((_ test e e* ...)
     (if test (begin e e* ...)))))

(define-syntax when
  (lambda (x)
    (syntax-case x ()
      ((_ test e e* ...)
       #'(if test (begin e e* ...))))))
@end example

Clearly, the @code{syntax-case} definition is similar to its @code{syntax-rules}
counterpart, and equally clearly there are some differences. The
@code{syntax-case} definition is wrapped in a @code{lambda}, a function of one
argument; that argument is passed to the @code{syntax-case} invocation; and the
``return value'' of the macro has a @code{#'} prefix.

All of these differences stem from the fact that @code{syntax-case} does not
define a syntax transformer itself -- instead, @code{syntax-case} expressions
provide a way to destructure a @dfn{syntax object}, and to rebuild syntax
objects as output.

So the @code{lambda} wrapper is simply a leaky implementation detail, that
syntax transformers are just functions that transform syntax to syntax. This
should not be surprising, given that we have already described macros as
``programs that write programs''. @code{syntax-case} is simply a way to take
apart and put together program text, and to be a valid syntax transformer it
needs to be wrapped in a procedure.

Unlike traditional Lisp macros (@pxref{Defmacros}), @code{syntax-case} macros
transform syntax objects, not raw Scheme forms. Recall the naive expansion of
@code{my-or} given in the previous section:

@example
(let ((t #t))
  (my-or #f t))
;; naive expansion:
(let ((t #t))
  (let ((t #f))
    (if t t t)))
@end example

Raw Scheme forms simply don't have enough information to distinguish the first
two @code{t} instances in @code{(if t t t)} from the third @code{t}. So instead
of representing identifiers as symbols, the syntax expander represents
identifiers as annotated syntax objects, attaching such information to those
syntax objects as is needed to maintain referential transparency.

@deffn {Syntax} syntax form
Create a syntax object wrapping @var{form} within the current lexical context.
@end deffn

Syntax objects are typically created internally to the process of expansion, but
it is possible to create them outside of syntax expansion:

@example
(syntax (foo bar baz))
@result{} #<some representation of that syntax>
@end example

@noindent
However it is more common, and useful, to create syntax objects when building
output from a @code{syntax-case} expression.

@example
(define-syntax add1
  (lambda (x)
    (syntax-case x ()
      ((_ exp)
       (syntax (+ exp 1))))))
@end example

It is not strictly necessary for a @code{syntax-case} expression to return a
syntax object, because @code{syntax-case} expressions can be used in helper
functions, or otherwise used outside of syntax expansion itself. However a
syntax transformer procedure  must return a syntax object, so most uses of
@code{syntax-case} do end up returning syntax objects.

Here in this case, the form that built the return value was @code{(syntax (+ exp
1))}. The interesting thing about this is that within a @code{syntax}
expression, any appearance of a pattern variable is substitued into the
resulting syntax object, carrying with it all relevant metadata from the source
expression, such as lexical identity and source location.

Indeed, a pattern variable may only be referenced from inside a @code{syntax}
form. The syntax expander would raise an error when defining @code{add1} if it
found @var{exp} referenced outside a @code{syntax} form.

Since @code{syntax} appears frequently in macro-heavy code, it has a special
reader macro: @code{#'}. @code{#'foo} is transformed by the reader into
@code{(syntax foo)}, just as @code{'foo} is tranformed into @code{(quote foo)}.

The pattern language used by @code{syntax-case} is conveniently the same
language used by @code{syntax-rules}. Given this, Guile actually defines
@code{syntax-rules} in terms of @code{syntax-case}:

@example
(define-syntax syntax-rules
  (lambda (x)
    (syntax-case x ()
      ((_ (k ...) ((keyword . pattern) template) ...)
       #'(lambda (x)
           (syntax-case x (k ...)
             ((dummy . pattern) #'template)
             ...))))))
@end example

And that's that.

@subsubsection Why @code{syntax-case}?

The examples we have shown thus far could just as well have been expressed with
@code{syntax-rules}, and have just shown that @code{syntax-case} is more
verbose, which is true. But there is a difference: @code{syntax-case} creates
@emph{procedural} macros, giving the full power of Scheme to the macro expander.
This has many practical applications.

A common desire is to be able to match a form only if it is an identifier. This
is impossible with @code{syntax-rules}, given the datum matching forms. But with
@code{syntax-case} it is easy:

@deffn {Scheme Procedure} identifier? syntax-object
Returns @code{#t} iff @var{syntax-object} is an identifier.
@end deffn

@example
(define-syntax add1!
  (lambda (x)
    (syntax-case x ()
      ((_ var) (identifier? #'var)
       #'(set! var (add1 var))))))

(define foo 0)
(add1! foo)
foo @result{} 1
(add1! "not-an-identifier") @result{} error
@end example

With @code{syntax-rules}, the error for @code{(add1! "not-an-identifier")} would
be something like ``invalid @code{set!}''. With @code{syntax-case}, it will say
something like ``invalid @code{add1!}'', because we attach the @dfn{guard
clause} to the pattern: @code{(identifier? #'var)}. This becomes more important
with more complicated macros. It is necessary to use @code{identifier?}, because
to the expander, an identifier is more than a bare symbol.

Note that even in the guard clause, we reference the @var{var} pattern variable
within a @code{syntax} form, via @code{#'var}.

Another common desire is to introduce bindings into the lexical context of the
output expression. One example would be in the so-called ``anaphoric macros'',
like @code{aif}. Anaphoric macros bind some expression to a well-known
identifier, often @code{it}, within their bodies. For example, in @code{(aif
(foo) (bar it))}, @code{it} would be bound to the result of @code{(foo)}.

To begin with, we should mention a solution that doesn't work:

@example
;; doesn't work
(define-syntax aif
  (lambda (x)
    (syntax-case x ()
      ((_ test then else)
       #'(let ((it test))
           (if it then else))))))
@end example

The reason that this doesn't work is that, by default, the expander will
preserve referential transparency; the @var{then} and @var{else} expressions
won't have access to the binding of @code{it}.

But they can, if we explicitly introduce a binding via @code{datum->syntax}.

@deffn {Scheme Procedure} datum->syntax for-syntax datum
Create a syntax object that wraps @var{datum}, within the lexical context
corresponding to the syntax object @var{for-syntax}.
@end deffn

For completeness, we should mention that it is possible to strip the metadata
from a syntax object, returning a raw Scheme datum:

@deffn {Scheme Procedure} syntax->datum syntax-object
Strip the metadata from @var{syntax-object}, returning its contents as a raw
Scheme datum.
@end deffn

In this case we want to introduce @code{it} in the context of the whole
expression, so we can create a syntax object as @code{(datum->syntax x 'it)},
where @code{x} is the whole expression, as passed to the transformer procedure.

Here's another solution that doesn't work:

@example
;; doesn't work either
(define-syntax aif
  (lambda (x)
    (syntax-case x ()
      ((_ test then else)
       (let ((it (datum->syntax x 'it)))
         #'(let ((it test))
             (if it then else)))))))
@end example

The reason that this one doesn't work is that there are really two environments
at work here -- the environment of pattern variables, as bound by
@code{syntax-case}, and the environment of lexical variables, as bound by normal
Scheme. Here we need to introduce a piece of Scheme's environment into that of
the syntax expander, and we can do so using @code{syntax-case} itself:

@example
;; works, but is obtuse
(define-syntax aif
  (lambda (x)
    (syntax-case x ()
      ((_ test then else)
       ;; invoking syntax-case on the generated
       ;; syntax object to expose it to `syntax'
       (syntax-case (datum->syntax x 'it) ()
         (it
           #'(let ((it test))
               (if it then else))))))))

(aif (getuid) (display it) (display "none")) (newline)
@print{} 500
@end example

However there are easier ways to write this. @code{with-syntax} is often
convenient:

@deffn {Syntax} with-syntax ((pat val)...) exp...
Bind patterns @var{pat} from their corresponding values @var{val}, within the
lexical context of @var{exp...}.

@example
;; better
(define-syntax aif
  (lambda (x)
    (syntax-case x ()
      ((_ test then else)
       (with-syntax ((it (datum->syntax x 'it)))
         #'(let ((it test))
             (if it then else)))))))
@end example
@end deffn

As you might imagine, @code{with-syntax} is defined in terms of
@code{syntax-case}. But even that might be off-putting to you if you are an old
Lisp macro hacker, used to building macro output with @code{quasiquote}. The
issue is that @code{with-syntax} creates a separation between the point of
definition of a value and its point of substitution.

@pindex quasisyntax
@pindex unsyntax
@pindex unsyntax-splicing
So for cases in which a @code{quasiquote} style makes more sense,
@code{syntax-case} also defines @code{quasisyntax}, and the related
@code{unsyntax} and @code{unsyntax-splicing}, abbreviated by the reader as
@code{#`}, @code{#,}, and @code{#,@@}, respectively.

For example, to define a macro that inserts a compile-time timestamp into a
source file, one may write:

@example
(define-syntax display-compile-timestamp
  (lambda (x)
    (syntax-case x ()
      ((_)
       #`(begin
          (display "The compile timestamp was: ")
          (display #,(current-time))
          (newline))))))
@end example

Finally, we should mention the following helper procedures defined by the core
of @code{syntax-case}:

@deffn {Scheme Procedure} bound-identifier=? a b
Returns @code{#t} iff the syntax objects @var{a} and @var{b} refer to the same
lexically-bound identifier.
@end deffn

@deffn {Scheme Procedure} free-identifier=? a b
Returns @code{#t} iff the syntax objects @var{a} and @var{b} refer to the same
free identifier.
@end deffn

@deffn {Scheme Procedure} generate-temporaries ls
Return a list of temporary identifiers as long as @var{ls} is long.
@end deffn

Readers interested in further information on @code{syntax-case} macros should
see R. Kent Dybvig's excellent @cite{The Scheme Programming Language}, either
edition 3 or 4, in the chapter on syntax. Dybvig was the primary author of the
@code{syntax-case} system. The book itself is available online at
@uref{http://scheme.com/tspl4/}.

@node Defmacros
@subsection Lisp-style Macro Definitions

The traditional way to define macros in Lisp 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}.

Having read the previous section on @code{syntax-case}, it's probably clear that
Guile actually implements defmacros in terms of @code{syntax-case}, applying the
transformer on the expression between invocations of @code{syntax->datum} and
@code{datum->syntax}. This realization leads us to the problem with defmacros,
that they do not preserve referential transparency. One can be careful to not
introduce bindings into expanded code, via liberal use of @code{gensym}, but
there is no getting around the lack of referential transparency for free
bindings in the macro itself.

Even a macro as simple as our @code{when} from before is difficult to get right:

@example
(define-macro (when cond exp . rest)
  `(if ,cond
       (begin ,exp . ,rest)))

(when #f (display "Launching missiles!\n"))
@result{} #f

(let ((if list))
  (when #f (display "Launching missiles!\n")))
@print{} Launching missiles!
@result{} (#f #<unspecified>)
@end example

Guile's perspective is that defmacros have had a good run, but that modern
macros should be written with @code{syntax-rules} or @code{syntax-case}. There
are still many uses of defmacros within Guile itself, but we will be phasing
them out over time. Of course we won't take away @code{defmacro} or
@code{define-macro} themselves, as there is lots of code out there that uses
them.

@node Identifier Macros
@subsection Identifier Macros

When the syntax expander sees a form in which the first element is a macro, the
whole form gets passed to the macro's syntax transformer. One may visualize this
as:

@example
(define-syntax foo foo-transformer)
(foo @var{arg}...)
;; expands via
(foo-transformer #'(foo @var{arg}...))
@end example

If, on the other hand, a macro is referenced in some other part of a form, the
syntax transformer is invoked with only the macro reference, not the whole form.

@example
(define-syntax foo foo-transformer)
foo
;; expands via
(foo-transformer #'foo)
@end example

This allows bare identifier references to be replaced programmatically via a
macro. @code{syntax-rules} provides some syntax to effect this transformation
more easily.

@deffn {Syntax} identifier-syntax exp
Returns a macro transformer that will replace occurences of the macro with
@var{exp}.
@end deffn

For example, if you are importing external code written in terms of @code{fx+},
the fixnum addition operator, but Guile doesn't have @code{fx+}, you may use the
following to replace @code{fx+} with @code{+}:

@example
(define-syntax fx+ (identifier-syntax +))
@end example

There is also special support for recognizing identifiers on the
left-hand side of a @code{set!} expression, as in the following:

@example
(define-syntax foo foo-transformer)
(set! foo @var{val})
;; expands via
(foo-transformer #'(set! foo @var{val}))
;; iff foo-transformer is a "variable transformer"
@end example

As the example notes, the transformer procedure must be explicitly
marked as being a ``variable transformer'', as most macros aren't
written to discriminate on the form in the operand position.

@deffn {Scheme Procedure} make-variable-transformer transformer
Mark the @var{transformer} procedure as being a ``variable
transformer''. In practice this means that, when bound to a syntactic
keyword, it may detect references to that keyword on the left-hand-side
of a @code{set!}.

@example
(define bar 10)
(define-syntax bar-alias
  (make-variable-transformer
   (lambda (x)
     (syntax-case x (set!)
       ((set! var val) #'(set! bar val))
       ((var arg ...) #'(bar arg ...))
       (var (identifier? #'var) #'bar)))))

bar-alias @result{} 10
(set! bar-alias 20)
bar @result{} 20
(set! bar 30)
bar-alias @result{} 30
@end example
@end deffn

There is an extension to identifer-syntax which allows it to handle the
@code{set!} case as well:

@deffn {Syntax} identifier-syntax (var exp1) ((set! var val) exp2)
Create a variable transformer. The first clause is used for references
to the variable in operator or operand position, and the second for
appearances of the variable on the left-hand-side of an assignment.

For example, the previous @code{bar-alias} example could be expressed
more succinctly like this:

@example
(define-syntax bar-alias
  (identifier-syntax
    (var bar)
    ((set! var val) (set! bar val))))
@end example

@noindent
As before, the templates in @code{identifier-syntax} forms do not need
wrapping in @code{#'} syntax forms.
@end deffn

@node Eval When
@subsection Eval-when

As @code{syntax-case} macros have the whole power of Scheme available to them,
they present a problem regarding time: when a macro runs, what parts of the
program are available for the macro to use?

The default answer to this question is that when you import a module (via
@code{define-module} or @code{use-modules}), that module will be loaded up at
expansion-time, as well as at run-time. Additionally, top-level syntactic
definitions within one compilation unit made by @code{define-syntax} are also
evaluated at expansion time, in the order that they appear in the compilation
unit (file).

But if a syntactic definition needs to call out to a normal procedure at
expansion-time, it might well need need special declarations to indicate that
the procedure should be made available at expansion-time.

For example, the following code will work at a REPL, but not in a file:

@example
;; incorrect
(use-modules (srfi srfi-19))
(define (date) (date->string (current-date)))
(define-syntax %date (identifier-syntax (date)))
(define *compilation-date* %date)
@end example

It works at a REPL because the expressions are evaluated one-by-one, in order,
but if placed in a file, the expressions are expanded one-by-one, but not
evaluated until the compiled file is loaded.

The fix is to use @code{eval-when}.

@example
;; correct: using eval-when
(use-modules (srfi srfi-19))
(eval-when (compile load eval)
  (define (date) (date->string (current-date))))
(define-syntax %date (identifier-syntax (date)))
(define *compilation-date* %date)
@end example

@deffn {Syntax} eval-when conditions exp...
Evaluate @var{exp...} under the given @var{conditions}. Valid conditions include
@code{eval}, @code{load}, and @code{compile}. If you need to use
@code{eval-when}, use it with all three conditions, as in the above example.
Other uses of @code{eval-when} may void your warranty or poison your cat.
@end deffn

@node Internal Macros
@subsection Internal Macros

@deffn {Scheme Procedure} make-syntax-transformer name type binding
Construct a syntax transformer object. This is part of Guile's low-level support
for syntax-case.
@end deffn

@deffn {Scheme Procedure} macro? obj
@deffnx {C Function} scm_macro_p (obj)
Return @code{#t} iff @var{obj} is a syntax transformer.

Note that it's a bit difficult to actually get a macro as a first-class object;
simply naming it (like @code{case}) will produce a syntax error. But it is
possible to get these objects using @code{module-ref}:

@example
(macro? (module-ref (current-module) 'case))
@result{} #t
@end example
@end deffn

@deffn {Scheme Procedure} macro-type m
@deffnx {C Function} scm_macro_type (m)
Return the @var{type} that was given when @var{m} was constructed, via
@code{make-syntax-transformer}.
@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-binding m
@deffnx {C Function} scm_macro_binding (m)
Return the binding 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}. This will return a procedure, for
which one may ask the docstring. That's the whole reason this section is
documented. Actually a part of the result of @code{macro-binding}.
@end deffn

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


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

@node Memory Management
@section Memory Management and Garbage Collection

Guile uses a @emph{garbage collector} to manage most of its objects.
While the garbage collector is designed to be mostly invisible, you
sometimes need to interact with it explicitly.

See @ref{Garbage Collection} for a general discussion of how garbage
collection relates to using Guile from C.

@menu
* Garbage Collection Functions::
* Memory Blocks::
* Weak References::
* Guardians::
@end menu

@node Garbage Collection Functions
@subsection Function related to Garbage Collection

@deffn {Scheme Procedure} gc
@deffnx {C Function} scm_gc ()
Scans all of SCM objects and reclaims for further use those that are
no longer accessible.  You normally don't need to call this function
explicitly.  It is called automatically when appropriate.
@end deffn

@deftypefn {C Function} SCM scm_gc_protect_object (SCM @var{obj})
Protects @var{obj} from being freed by the garbage collector, when it
otherwise might be.  When you are done with the object, call
@code{scm_gc_unprotect_object} on the object. Calls to
@code{scm_gc_protect}/@code{scm_gc_unprotect_object} can be nested, and
the object remains protected until it has been unprotected as many times
as it was protected. It is an error to unprotect an object more times
than it has been protected. Returns the SCM object it was passed.

Note that storing @var{obj} in a C global variable has the same
effect@footnote{In Guile up to version 1.8, C global variables were not
scanned by the garbage collector; hence, @code{scm_gc_protect_object}
was the only way in C to prevent a Scheme object from being freed.}.
@end deftypefn

@deftypefn {C Function} SCM scm_gc_unprotect_object (SCM @var{obj})

Unprotects an object from the garbage collector which was protected by
@code{scm_gc_unprotect_object}. Returns the SCM object it was passed.
@end deftypefn

@deftypefn {C Function} SCM scm_permanent_object (SCM @var{obj})

Similar to @code{scm_gc_protect_object} in that it causes the
collector to always mark the object, except that it should not be
nested (only call @code{scm_permanent_object} on an object once), and
it has no corresponding unpermanent function. Once an object is
declared permanent, it will never be freed. Returns the SCM object it
was passed.
@end deftypefn

@c  NOTE: The varargs scm_remember_upto_here is deliberately not
@c  documented, because we don't think it can be implemented as a nice
@c  inline compiler directive or asm block.  New _3, _4 or whatever
@c  forms could certainly be added though, if needed.

@deftypefn {C Macro} void scm_remember_upto_here_1 (SCM obj)
@deftypefnx {C Macro} void scm_remember_upto_here_2 (SCM obj1, SCM obj2)
Create a reference to the given object or objects, so they're certain
to be present on the stack or in a register and hence will not be
freed by the garbage collector before this point.

Note that these functions can only be applied to ordinary C local
variables (ie.@: ``automatics'').  Objects held in global or static
variables or some malloced block or the like cannot be protected with
this mechanism.
@end deftypefn

@deffn {Scheme Procedure} gc-stats
@deffnx {C Function} scm_gc_stats ()
Return an association list of statistics about Guile's current
use of storage.
@end deffn

@deffn {Scheme Procedure} gc-live-object-stats
@deffnx {C Function} scm_gc_live_object_stats ()
Return an alist of statistics of the current live objects.
@end deffn

@deftypefun void scm_gc_mark (SCM @var{x})
Mark the object @var{x}, and recurse on any objects @var{x} refers to.
If @var{x}'s mark bit is already set, return immediately.  This function
must only be called during the mark-phase of garbage collection,
typically from a smob @emph{mark} function.
@end deftypefun

@node Memory Blocks
@subsection Memory Blocks

@cindex automatically-managed memory
@cindex GC-managed memory
@cindex conservative garbage collection

In C programs, dynamic management of memory blocks is normally done
with the functions malloc, realloc, and free.  Guile has additional
functions for dynamic memory allocation that are integrated into the
garbage collector and the error reporting system.

Memory blocks that are associated with Scheme objects (for example a
smob) should be allocated with @code{scm_gc_malloc} or
@code{scm_gc_malloc_pointerless}.  These two functions will either
return a valid pointer or signal an error.  Memory blocks allocated this
way can be freed with @code{scm_gc_free}; however, this is not strictly
needed: memory allocated with @code{scm_gc_malloc} or
@code{scm_gc_malloc_pointerless} is automatically reclaimed when the
garbage collector no longer sees any live reference to it@footnote{In
Guile up to version 1.8, memory allocated with @code{scm_gc_malloc}
@emph{had} to be freed with @code{scm_gc_free}.}.

Memory allocated with @code{scm_gc_malloc} is scanned for live pointers.
This means that if @code{scm_gc_malloc}-allocated memory contains a
pointer to some other part of the memory, the garbage collector notices
it and prevents it from being reclaimed@footnote{In Guile up to 1.8,
memory allocated with @code{scm_gc_malloc} was @emph{not} scanned.
Consequently, the GC had to be told explicitly about pointers to live
objects contained in the memory block, e.g., @i{via} SMOB mark functions
(@pxref{Smobs, @code{scm_set_smob_mark}})}.  Conversely, memory
allocated with @code{scm_gc_malloc_pointerless} is assumed to be
``pointer-less'' and is not scanned.

For memory that is not associated with a Scheme object, you can use
@code{scm_malloc} instead of @code{malloc}.  Like
@code{scm_gc_malloc}, it will either return a valid pointer or signal
an error.  However, it will not assume that the new memory block can
be freed by a garbage collection.  The memory must be explicitly freed
with @code{free}.

There is also @code{scm_gc_realloc} and @code{scm_realloc}, to be used
in place of @code{realloc} when appropriate, and @code{scm_gc_calloc}
and @code{scm_calloc}, to be used in place of @code{calloc} when
appropriate.

The function @code{scm_dynwind_free} can be useful when memory should be
freed with libc's @code{free} when leaving a dynwind context,
@xref{Dynamic Wind}.

@deftypefn {C Function} {void *} scm_malloc (size_t @var{size})
@deftypefnx {C Function} {void *} scm_calloc (size_t @var{size})
Allocate @var{size} bytes of memory and return a pointer to it.  When
@var{size} is 0, return @code{NULL}.  When not enough memory is
available, signal an error.  This function runs the GC to free up some
memory when it deems it appropriate.

The memory is allocated by the libc @code{malloc} function and can be
freed with @code{free}.  There is no @code{scm_free} function to go
with @code{scm_malloc} to make it easier to pass memory back and forth
between different modules.

The function @code{scm_calloc} is similar to @code{scm_malloc}, but
initializes the block of memory to zero as well.
@end deftypefn

@deftypefn {C Function} {void *} scm_realloc (void *@var{mem}, size_t @var{new_size})
Change the size of the memory block at @var{mem} to @var{new_size} and
return its new location.  When @var{new_size} is 0, this is the same
as calling @code{free} on @var{mem} and @code{NULL} is returned.  When
@var{mem} is @code{NULL}, this function behaves like @code{scm_malloc}
and allocates a new block of size @var{new_size}.

When not enough memory is available, signal an error.  This function
runs the GC to free up some memory when it deems it appropriate.
@end deftypefn

@deftypefn {C Function} {void *} scm_gc_malloc (size_t @var{size}, const char *@var{what})
@deftypefnx {C Function} {void *} scm_gc_malloc_pointerless (size_t @var{size}, const char *@var{what})
@deftypefnx {C Function} {void *} scm_gc_realloc (void *@var{mem}, size_t @var{old_size}, size_t @var{new_size}, const char *@var{what});
@deftypefnx {C Function} {void *} scm_gc_calloc (size_t @var{size}, const char *@var{what})
Allocate @var{size} bytes of automatically-managed memory.  The memory
is automatically freed when no longer referenced from any live memory
block.

Memory allocated with @code{scm_gc_malloc} or @code{scm_gc_calloc} is
scanned for pointers.  Memory allocated by
@code{scm_gc_malloc_pointerless} is not scanned.

The @code{scm_gc_realloc} call preserves the ``pointerlessness'' of the
memory area pointed to by @var{mem}.  Note that you need to pass the old
size of a reallocated memory block as well.  See below for a motivation.
@end deftypefn

@deftypefn {C Function} void scm_gc_free (void *@var{mem}, size_t @var{size}, const char *@var{what})
Explicitly free the memory block pointed to by @var{mem}, which was
previously allocated by one of the above @code{scm_gc} functions.

Note that you need to explicitly pass the @var{size} parameter.  This
is done since it should normally be easy to provide this parameter
(for memory that is associated with GC controlled objects) and help keep
the memory management overhead very low.  However, in Guile 2.x,
@var{size} is always ignored.
@end deftypefn

@deftypefn {C Function} void scm_gc_register_collectable_memory (void *@var{mem}, size_t @var{size}, const char *@var{what})
Informs the GC that the memory at @var{mem} of size @var{size} can
potentially be freed during a GC.  That is, announce that @var{mem} is
part of a GC controlled object and when the GC happens to free that
object, @var{size} bytes will be freed along with it.  The GC will
@strong{not} free the memory itself, it will just know that so-and-so
much bytes of memory are associated with GC controlled objects and the
memory system figures this into its decisions when to run a GC.

The @var{what} argument is used for statistical purposes.  It should
describe the type of object that the memory will be used for so that
users can identify just what strange objects are eating up their
memory.

In Guile 2.x, this function has no effect.
@end deftypefn

@deftypefn {C Function} void scm_gc_unregister_collectable_memory (void *@var{mem}, size_t @var{size})
Informs the GC that the memory at @var{mem} of size @var{size} is no
longer associated with a GC controlled object.  You must take care to
match up every call to @code{scm_gc_register_collectable_memory} with
a call to @code{scm_gc_unregister_collectable_memory}.  If you don't do
this, the GC might have a wrong impression of what is going on and run
much less efficiently than it could.

In Guile 2.x, this function has no effect.
@end deftypefn

@deftypefn {C Function} void scm_frame_free (void *mem)
Equivalent to @code{scm_frame_unwind_handler (free, @var{mem},
SCM_F_WIND_EXPLICITLY)}.  That is, the memory block at @var{mem} will
be freed when the current frame is left.
@end deftypefn

@deffn {Scheme Procedure} malloc-stats
Return an alist ((@var{what} . @var{n}) ...) describing number
of malloced objects.
@var{what} is the second argument to @code{scm_gc_malloc},
@var{n} is the number of objects of that type currently
allocated.

This function is only available if the @code{GUILE_DEBUG_MALLOC}
preprocessor macro was defined when Guile was compiled.
@end deffn

@subsubsection Upgrading from scm_must_malloc et al.

Version 1.6 of Guile and earlier did not have the functions from the
previous section.  In their place, it had the functions
@code{scm_must_malloc}, @code{scm_must_realloc} and
@code{scm_must_free}.  This section explains why we want you to stop
using them, and how to do this.

@findex scm_must_malloc
@findex scm_must_realloc
@findex scm_must_calloc
@findex scm_must_free
The functions @code{scm_must_malloc} and @code{scm_must_realloc}
behaved like @code{scm_gc_malloc} and @code{scm_gc_realloc} do now,
respectively.  They would inform the GC about the newly allocated
memory via the internal equivalent of
@code{scm_gc_register_collectable_memory}.  However,
@code{scm_must_free} did not unregister the memory it was about to
free.  The usual way to unregister memory was to return its size from
a smob free function.

This disconnectedness of the actual freeing of memory and reporting
this to the GC proved to be bad in practice.  It was easy to make
mistakes and report the wrong size because allocating and freeing was
not done with symmetric code, and because it is cumbersome to compute
the total size of nested data structures that were freed with multiple
calls to @code{scm_must_free}.  Additionally, there was no equivalent
to @code{scm_malloc}, and it was tempting to just use
@code{scm_must_malloc} and never to tell the GC that the memory has
been freed.

The effect was that the internal statistics kept by the GC drifted out
of sync with reality and could even overflow in long running programs.
When this happened, the result was a dramatic increase in (senseless)
GC activity which would effectively stop the program dead.

@findex scm_done_malloc
@findex scm_done_free
The functions @code{scm_done_malloc} and @code{scm_done_free} were
introduced to help restore balance to the force, but existing bugs did
not magically disappear, of course.

Therefore we decided to force everybody to review their code by
deprecating the existing functions and introducing new ones in their
place that are hopefully easier to use correctly.

For every use of @code{scm_must_malloc} you need to decide whether to
use @code{scm_malloc} or @code{scm_gc_malloc} in its place.  When the
memory block is not part of a smob or some other Scheme object whose
lifetime is ultimately managed by the garbage collector, use
@code{scm_malloc} and @code{free}.  When it is part of a smob, use
@code{scm_gc_malloc} and change the smob free function to use
@code{scm_gc_free} instead of @code{scm_must_free} or @code{free} and
make it return zero.

The important thing is to always pair @code{scm_malloc} with
@code{free}; and to always pair @code{scm_gc_malloc} with
@code{scm_gc_free}.

The same reasoning applies to @code{scm_must_realloc} and
@code{scm_realloc} versus @code{scm_gc_realloc}.

@node Weak References
@subsection Weak References

[FIXME: This chapter is based on Mikael Djurfeldt's answer to a
question by Michael Livshin. Any mistakes are not theirs, of course. ]

Weak references let you attach bookkeeping information to data so that
the additional information automatically disappears when the original
data is no longer in use and gets garbage collected. In a weak key hash,
the hash entry for that key disappears as soon as the key is no longer
referenced from anywhere else. For weak value hashes, the same happens
as soon as the value is no longer in use. Entries in a doubly weak hash
disappear when either the key or the value are not used anywhere else
anymore.

Object properties offer the same kind of functionality as weak key
hashes in many situations. (@pxref{Object Properties})

Here's an example (a little bit strained perhaps, but one of the
examples is actually used in Guile):

Assume that you're implementing a debugging system where you want to
associate information about filename and position of source code
expressions with the expressions themselves.

Hashtables can be used for that, but if you use ordinary hash tables
it will be impossible for the scheme interpreter to "forget" old
source when, for example, a file is reloaded.

To implement the mapping from source code expressions to positional
information it is necessary to use weak-key tables since we don't want
the expressions to be remembered just because they are in our table.

To implement a mapping from source file line numbers to source code
expressions you would use a weak-value table.

To implement a mapping from source code expressions to the procedures
they constitute a doubly-weak table has to be used.

@menu
* Weak hash tables::
* Weak vectors::
@end menu

@node Weak hash tables
@subsubsection Weak hash tables

@deffn {Scheme Procedure} make-weak-key-hash-table size
@deffnx {Scheme Procedure} make-weak-value-hash-table size
@deffnx {Scheme Procedure} make-doubly-weak-hash-table size
@deffnx {C Function} scm_make_weak_key_hash_table (size)
@deffnx {C Function} scm_make_weak_value_hash_table (size)
@deffnx {C Function} scm_make_doubly_weak_hash_table (size)
Return a weak hash table with @var{size} buckets. As with any
hash table, choosing a good size for the table requires some
caution.

You can modify weak hash tables in exactly the same way you
would modify regular hash tables. (@pxref{Hash Tables})
@end deffn

@deffn {Scheme Procedure} weak-key-hash-table? obj
@deffnx {Scheme Procedure} weak-value-hash-table? obj
@deffnx {Scheme Procedure} doubly-weak-hash-table? obj
@deffnx {C Function} scm_weak_key_hash_table_p (obj)
@deffnx {C Function} scm_weak_value_hash_table_p (obj)
@deffnx {C Function} scm_doubly_weak_hash_table_p (obj)
Return @code{#t} if @var{obj} is the specified weak hash
table. Note that a doubly weak hash table is neither a weak key
nor a weak value hash table.
@end deffn

@node Weak vectors
@subsubsection Weak vectors

Weak vectors are mainly useful in Guile's implementation of weak hash
tables.

@deffn {Scheme Procedure} make-weak-vector size [fill]
@deffnx {C Function} scm_make_weak_vector (size, fill)
Return a weak vector with @var{size} elements. If the optional
argument @var{fill} is given, all entries in the vector will be
set to @var{fill}. The default value for @var{fill} is the
empty list.
@end deffn

@deffn {Scheme Procedure} weak-vector . l
@deffnx {Scheme Procedure} list->weak-vector l
@deffnx {C Function} scm_weak_vector (l)
Construct a weak vector from a list: @code{weak-vector} uses
the list of its arguments while @code{list->weak-vector} uses
its only argument @var{l} (a list) to construct a weak vector
the same way @code{list->vector} would.
@end deffn

@deffn {Scheme Procedure} weak-vector? obj
@deffnx {C Function} scm_weak_vector_p (obj)
Return @code{#t} if @var{obj} is a weak vector. Note that all
weak hashes are also weak vectors.
@end deffn

@node Guardians
@subsection Guardians

Guardians provide a way to be notified about objects that would
otherwise be collected as garbage.  Guarding them prevents the objects
from being collected and cleanup actions can be performed on them, for
example.

See R. Kent Dybvig, Carl Bruggeman, and David Eby (1993) "Guardians in
a Generation-Based Garbage Collector".  ACM SIGPLAN Conference on
Programming Language Design and Implementation, June 1993.

@deffn {Scheme Procedure} make-guardian
@deffnx {C Function} scm_make_guardian ()
Create a new guardian.  A guardian protects a set of objects from
garbage collection, allowing a program to apply cleanup or other
actions.

@code{make-guardian} returns a procedure representing the guardian.
Calling the guardian procedure with an argument adds the argument to
the guardian's set of protected objects.  Calling the guardian
procedure without an argument returns one of the protected objects
which are ready for garbage collection, or @code{#f} if no such object
is available.  Objects which are returned in this way are removed from
the guardian.

You can put a single object into a guardian more than once and you can
put a single object into more than one guardian.  The object will then
be returned multiple times by the guardian procedures.

An object is eligible to be returned from a guardian when it is no
longer referenced from outside any guardian.

There is no guarantee about the order in which objects are returned
from a guardian.  If you want to impose an order on finalization
actions, for example, you can do that by keeping objects alive in some
global data structure until they are no longer needed for finalizing
other objects.

Being an element in a weak vector, a key in a hash table with weak
keys, or a value in a hash table with weak values does not prevent an
object from being returned by a guardian.  But as long as an object
can be returned from a guardian it will not be removed from such a
weak vector or hash table.  In other words, a weak link does not
prevent an object from being considered collectable, but being inside
a guardian prevents a weak link from being broken.

A key in a weak key hash table can be thought of as having a strong
reference to its associated value as long as the key is accessible.
Consequently, when the key is only accessible from within a guardian,
the reference from the key to the value is also considered to be
coming from within a guardian.  Thus, if there is no other reference
to the value, it is eligible to be returned from a guardian.
@end deffn

@node Objects
@section Objects

@deffn {Scheme Procedure} entity? obj
@deffnx {C Function} scm_entity_p (obj)
Return @code{#t} if @var{obj} is an entity.
@end deffn

@deffn {Scheme Procedure} operator? obj
@deffnx {C Function} scm_operator_p (obj)
Return @code{#t} if @var{obj} is an operator.
@end deffn

@deffn {Scheme Procedure} set-object-procedure! obj proc
@deffnx {C Function} scm_set_object_procedure_x (obj, proc)
Set the object procedure of @var{obj} to @var{proc}.
@var{obj} must be either an entity or an operator.
@end deffn

@deffn {Scheme Procedure} make-class-object metaclass layout
@deffnx {C Function} scm_make_class_object (metaclass, layout)
Create a new class object of class @var{metaclass}, with the
slot layout specified by @var{layout}.
@end deffn

@deffn {Scheme Procedure} make-subclass-object class layout
@deffnx {C Function} scm_make_subclass_object (class, layout)
Create a subclass object of @var{class}, with the slot layout
specified by @var{layout}.
@end deffn

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

license: mit


code:
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2008, 2009, 2010
@c   Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.

@node Modules
@section Modules
@cindex modules

When programs become large, naming conflicts can occur when a function
or global variable defined in one file has the same name as a function
or global variable in another file.  Even just a @emph{similarity}
between function names can cause hard-to-find bugs, since a programmer
might type the wrong function name.

The approach used to tackle this problem is called @emph{information
encapsulation}, which consists of packaging functional units into a
given name space that is clearly separated from other name spaces.
@cindex encapsulation
@cindex information encapsulation
@cindex name space

The language features that allow this are usually called @emph{the
module system} because programs are broken up into modules that are
compiled separately (or loaded separately in an interpreter).

Older languages, like C, have limited support for name space
manipulation and protection.  In C a variable or function is public by
default, and can be made local to a module with the @code{static}
keyword.  But you cannot reference public variables and functions from
another module with different names.

More advanced module systems have become a common feature in recently
designed languages: ML, Python, Perl, and Modula 3 all allow the
@emph{renaming} of objects from a foreign module, so they will not
clutter the global name space.
@cindex name space - private

In addition, Guile offers variables as first-class objects.  They can
be used for interacting with the module system.

@menu
* General Information about Modules::  Guile module basics.
* Using Guile Modules::         How to use existing modules.
* Creating Guile Modules::      How to package your code into modules.
* Module System Reflection::    Accessing module objects at run-time.
* Included Guile Modules::      Which modules come with Guile?
* R6RS Version References::     Using version numbers with modules.
* R6RS Libraries::              The library and import forms.
* Accessing Modules from C::    How to work with modules with C code.
* Variables::                   First-class variables.
* provide and require::         The SLIB feature mechanism.
* Environments::                R5RS top-level environments.
@end menu

@node General Information about Modules
@subsection General Information about Modules

A Guile module can be thought of as a collection of named procedures,
variables and macros.  More precisely, it is a set of @dfn{bindings}
of symbols (names) to Scheme objects.

An environment is a mapping from identifiers (or symbols) to locations,
i.e., a set of bindings.
There are top-level environments and lexical environments.
The environment in which a lambda is executed is remembered as part of its
definition.

Within a module, all bindings are visible.  Certain bindings
can be declared @dfn{public}, in which case they are added to the
module's so-called @dfn{export list}; this set of public bindings is
called the module's @dfn{public interface} (@pxref{Creating Guile
Modules}).

A client module @dfn{uses} a providing module's bindings by either
accessing the providing module's public interface, or by building a
custom interface (and then accessing that).  In a custom interface, the
client module can @dfn{select} which bindings to access and can also
algorithmically @dfn{rename} bindings.  In contrast, when using the
providing module's public interface, the entire export list is available
without renaming (@pxref{Using Guile Modules}).

To use a module, it must be found and loaded.  All Guile modules have a
unique @dfn{module name}, which is a list of one or more symbols.
Examples are @code{(ice-9 popen)} or @code{(srfi srfi-11)}.  When Guile
searches for the code of a module, it constructs the name of the file to
load by concatenating the name elements with slashes between the
elements and appending a number of file name extensions from the list
@code{%load-extensions} (@pxref{Loading}).  The resulting file name is
then searched in all directories in the variable @code{%load-path}
(@pxref{Build Config}).  For example, the @code{(ice-9 popen)} module
would result in the filename @code{ice-9/popen.scm} and searched in the
installation directories of Guile and in all other directories in the
load path.

A slightly different search mechanism is used when a client module
specifies a version reference as part of a request to load a module
(@pxref{R6RS Version References}).  Instead of searching the directories
in the load path for a single filename, Guile uses the elements of the
version reference to locate matching, numbered subdirectories of a
constructed base path.  For example, a request for the
@code{(rnrs base)} module with version reference @code{(6)} would cause
Guile to discover the @code{rnrs/6} subdirectory (if it exists in any of
the directories in the load path) and search its contents for the
filename @code{base.scm}.

When multiple modules are found that match a version reference, Guile
sorts these modules by version number, followed by the length of their
version specifications, in order to choose a ``best'' match.

@c FIXME::martin:  Not sure about this, maybe someone knows better?
Every module has a so-called syntax transformer associated with it.
This is a procedure which performs all syntax transformation for the
time the module is read in and evaluated.  When working with modules,
you can manipulate the current syntax transformer using the
@code{use-syntax} syntactic form or the @code{#:use-syntax} module
definition option (@pxref{Creating Guile Modules}).

@node Using Guile Modules
@subsection Using Guile Modules

To use a Guile module is to access either its public interface or a
custom interface (@pxref{General Information about Modules}).  Both
types of access are handled by the syntactic form @code{use-modules},
which accepts one or more interface specifications and, upon evaluation,
arranges for those interfaces to be available to the current module.
This process may include locating and loading code for a given module if
that code has not yet been loaded, following @code{%load-path} (@pxref{Build
Config}).

An @dfn{interface specification} has one of two forms.  The first
variation is simply to name the module, in which case its public
interface is the one accessed.  For example:

@lisp
(use-modules (ice-9 popen))
@end lisp

Here, the interface specification is @code{(ice-9 popen)}, and the
result is that the current module now has access to @code{open-pipe},
@code{close-pipe}, @code{open-input-pipe}, and so on (@pxref{Included
Guile Modules}).

Note in the previous example that if the current module had already
defined @code{open-pipe}, that definition would be overwritten by the
definition in @code{(ice-9 popen)}.  For this reason (and others), there
is a second variation of interface specification that not only names a
module to be accessed, but also selects bindings from it and renames
them to suit the current module's needs.  For example:

@cindex binding renamer
@lisp
(use-modules ((ice-9 popen)
              #:select ((open-pipe . pipe-open) close-pipe)
              #:renamer (symbol-prefix-proc 'unixy:)))
@end lisp

Here, the interface specification is more complex than before, and the
result is that a custom interface with only two bindings is created and
subsequently accessed by the current module.  The mapping of old to new
names is as follows:

@c Use `smallexample' since `table' is ugly.  --ttn
@smallexample
(ice-9 popen) sees:             current module sees:
open-pipe                       unixy:pipe-open
close-pipe                      unixy:close-pipe
@end smallexample

This example also shows how to use the convenience procedure
@code{symbol-prefix-proc}.

You can also directly refer to bindings in a module by using the
@code{@@} syntax.  For example, instead of using the
@code{use-modules} statement from above and writing
@code{unixy:pipe-open} to refer to the @code{pipe-open} from the
@code{(ice-9 popen)}, you could also write @code{(@@ (ice-9 popen)
open-pipe)}.  Thus an alternative to the complete @code{use-modules}
statement would be

@lisp
(define unixy:pipe-open (@@ (ice-9 popen) open-pipe))
(define unixy:close-pipe (@@ (ice-9 popen) close-pipe))
@end lisp

There is also @code{@@@@}, which can be used like @code{@@}, but does
not check whether the variable that is being accessed is actually
exported.  Thus, @code{@@@@} can be thought of as the impolite version
of @code{@@} and should only be used as a last resort or for
debugging, for example.

Note that just as with a @code{use-modules} statement, any module that
has not yet been loaded yet will be loaded when referenced by a
@code{@@} or @code{@@@@} form.

You can also use the @code{@@} and @code{@@@@} syntaxes as the target
of a @code{set!} when the binding refers to a variable.

@c begin (scm-doc-string "boot-9.scm" "symbol-prefix-proc")
@deffn {Scheme Procedure} symbol-prefix-proc prefix-sym
Return a procedure that prefixes its arg (a symbol) with
@var{prefix-sym}.
@c Insert gratuitous C++ slam here.  --ttn
@end deffn

@c begin (scm-doc-string "boot-9.scm" "use-modules")
@deffn syntax use-modules spec @dots{}
Resolve each interface specification @var{spec} into an interface and
arrange for these to be accessible by the current module.  The return
value is unspecified.

@var{spec} can be a list of symbols, in which case it names a module
whose public interface is found and used.

@var{spec} can also be of the form:

@cindex binding renamer
@lisp
 (MODULE-NAME [:select SELECTION] [:renamer RENAMER])
@end lisp

in which case a custom interface is newly created and used.
@var{module-name} is a list of symbols, as above; @var{selection} is a
list of selection-specs; and @var{renamer} is a procedure that takes a
symbol and returns its new name.  A selection-spec is either a symbol or
a pair of symbols @code{(ORIG . SEEN)}, where @var{orig} is the name in
the used module and @var{seen} is the name in the using module.  Note
that @var{seen} is also passed through @var{renamer}.

The @code{:select} and @code{:renamer} clauses are optional.  If both are
omitted, the returned interface has no bindings.  If the @code{:select}
clause is omitted, @var{renamer} operates on the used module's public
interface.

In addition to the above, @var{spec} can also include a @code{:version}
clause, of the form:

@lisp
 :version VERSION-SPEC
@end lisp

where @var{version-spec} is an R6RS-compatible version reference.  The
presence of this clause changes Guile's search behavior as described in
the section on module name resolution
(@pxref{General Information about Modules}).  An error will be signaled
in the case in which a module with the same name has already been
loaded, if that module specifies a version and that version is not
compatible with @var{version-spec}.

Signal error if module name is not resolvable.
@end deffn

@c FIXME::martin: Is this correct, and is there more to say?
@c FIXME::martin: Define term and concept `syntax transformer' somewhere.

@deffn syntax use-syntax module-name
Load the module @code{module-name} and use its syntax
transformer as the syntax transformer for the currently defined module,
as well as installing it as the current syntax transformer.
@end deffn

@deffn syntax @@ module-name binding-name
Refer to the binding named @var{binding-name} in module
@var{module-name}.  The binding must have been exported by the module.
@end deffn

@deffn syntax @@@@ module-name binding-name
Refer to the binding named @var{binding-name} in module
@var{module-name}.  The binding must not have been exported by the
module.  This syntax is only intended for debugging purposes or as a
last resort.
@end deffn

@node Creating Guile Modules
@subsection Creating Guile Modules

When you want to create your own modules, you have to take the following
steps:

@itemize @bullet
@item
Create a Scheme source file and add all variables and procedures you wish
to export, or which are required by the exported procedures.

@item
Add a @code{define-module} form at the beginning.

@item
Export all bindings which should be in the public interface, either
by using @code{define-public} or @code{export} (both documented below).
@end itemize

@c begin (scm-doc-string "boot-9.scm" "define-module")
@deffn syntax define-module module-name [options @dots{}]
@var{module-name} is of the form @code{(hierarchy file)}.  One
example of this is

@lisp
(define-module (ice-9 popen))
@end lisp

@code{define-module} makes this module available to Guile programs under
the given @var{module-name}.

The @var{options} are keyword/value pairs which specify more about the
defined module.  The recognized options and their meaning is shown in
the following table.

@c fixme: Should we use "#:" or ":"?

@table @code
@item #:use-module @var{interface-specification}
Equivalent to a @code{(use-modules @var{interface-specification})}
(@pxref{Using Guile Modules}).

@item #:use-syntax @var{module}
Use @var{module} when loading the currently defined module, and install
it as the syntax transformer.

@item #:autoload @var{module} @var{symbol-list}
@cindex autoload
Load @var{module} when any of @var{symbol-list} are accessed.  For
example,

@example
(define-module (my mod)
  #:autoload (srfi srfi-1) (partition delete-duplicates))
...
(if something
    (set! foo (delete-duplicates ...)))
@end example

When a module is autoloaded, all its bindings become available.
@var{symbol-list} is just those that will first trigger the load.

An autoload is a good way to put off loading a big module until it's
really needed, for instance for faster startup or if it will only be
needed in certain circumstances.

@code{@@} can do a similar thing (@pxref{Using Guile Modules}), but in
that case an @code{@@} form must be written every time a binding from
the module is used.

@item #:export @var{list}
@cindex export
Export all identifiers in @var{list} which must be a list of symbols
or pairs of symbols. This is equivalent to @code{(export @var{list})}
in the module body.

@item #:re-export @var{list}
@cindex re-export
Re-export all identifiers in @var{list} which must be a list of
symbols or pairs of symbols.  The symbols in @var{list} must be
imported by the current module from other modules.  This is equivalent
to @code{re-export} below.

@item #:export-syntax @var{list}
@cindex export-syntax
Export all identifiers in @var{list} which must be a list of symbols
or pairs of symbols.  The identifiers in @var{list} must refer to
macros (@pxref{Macros}) defined in the current module.  This is
equivalent to @code{(export-syntax @var{list})} in the module body.

@item #:re-export-syntax @var{list}
@cindex re-export-syntax
Re-export all identifiers in @var{list} which must be a list of
symbols or pairs of symbols.  The symbols in @var{list} must refer to
macros imported by the current module from other modules.  This is
equivalent to @code{(re-export-syntax @var{list})} in the module body.

@item #:replace @var{list}
@cindex replace
@cindex replacing binding
@cindex overriding binding
@cindex duplicate binding
Export all identifiers in @var{list} (a list of symbols or pairs of
symbols) and mark them as @dfn{replacing bindings}.  In the module
user's name space, this will have the effect of replacing any binding
with the same name that is not also ``replacing''.  Normally a
replacement results in an ``override'' warning message,
@code{#:replace} avoids that.

In general, a module that exports a binding for which the @code{(guile)}
module already has a definition should use @code{#:replace} instead of
@code{#:export}.  @code{#:replace}, in a sense, lets Guile know that the
module @emph{purposefully} replaces a core binding.  It is important to
note, however, that this binding replacement is confined to the name
space of the module user.  In other words, the value of the core binding
in question remains unchanged for other modules.

Note that although it is often a good idea for the replaced binding to
remain compatible with a binding in @code{(guile)}, to avoid surprising
the user, sometimes the bindings will be incompatible.  For example,
SRFI-19 exports its own version of @code{current-time} (@pxref{SRFI-19
Time}) which is not compatible with the core @code{current-time}
function (@pxref{Time}).  Guile assumes that a user importing a module
knows what she is doing, and uses @code{#:replace} for this binding
rather than @code{#:export}.

The @code{#:duplicates} (see below) provides fine-grain control about
duplicate binding handling on the module-user side.

@item #:version @var{list}
@cindex module version
Specify a version for the module in the form of @var{list}, a list of
zero or more exact, nonnegative integers.  The corresponding
@code{#:version} option in the @code{use-modules} form allows callers
to restrict the value of this option in various ways.

@item #:duplicates @var{list}
@cindex duplicate binding handlers
@cindex duplicate binding
@cindex overriding binding
Tell Guile to handle duplicate bindings for the bindings imported by
the current module according to the policy defined by @var{list}, a
list of symbols.  @var{list} must contain symbols representing a
duplicate binding handling policy chosen among the following:

@table @code
@item check
Raises an error when a binding is imported from more than one place.
@item warn
Issue a warning when a binding is imported from more than one place
and leave the responsibility of actually handling the duplication to
the next duplicate binding handler.
@item replace
When a new binding is imported that has the same name as a previously
imported binding, then do the following:

@enumerate
@item
@cindex replacing binding
If the old binding was said to be @dfn{replacing} (via the
@code{#:replace} option above) and the new binding is not replacing,
the keep the old binding.
@item
If the old binding was not said to be replacing and the new binding is
replacing, then replace the old binding with the new one.
@item
If neither the old nor the new binding is replacing, then keep the old
one.
@end enumerate

@item warn-override-core
Issue a warning when a core binding is being overwritten and actually
override the core binding with the new one.
@item first
In case of duplicate bindings, the firstly imported binding is always
the one which is kept.
@item last
In case of duplicate bindings, the lastly imported binding is always
the one which is kept.
@item noop
In case of duplicate bindings, leave the responsibility to the next
duplicate handler.
@end table

If @var{list} contains more than one symbol, then the duplicate
binding handlers which appear first will be used first when resolving
a duplicate binding situation.  As mentioned above, some resolution
policies may explicitly leave the responsibility of handling the
duplication to the next handler in @var{list}.

@findex default-duplicate-binding-handler
The default duplicate binding resolution policy is given by the
@code{default-duplicate-binding-handler} procedure, and is

@lisp
(replace warn-override-core warn last)
@end lisp

@item #:no-backtrace
@cindex no backtrace
Tell Guile not to record information for procedure backtraces when
executing the procedures in this module.

@item #:pure
@cindex pure module
Create a @dfn{pure} module, that is a module which does not contain any
of the standard procedure bindings except for the syntax forms.  This is
useful if you want to create @dfn{safe} modules, that is modules which
do not know anything about dangerous procedures.
@end table

@end deffn
@c end

@deffn syntax export variable @dots{}
Add all @var{variable}s (which must be symbols or pairs of symbols) to
the list of exported bindings of the current module.  If @var{variable}
is a pair, its @code{car} gives the name of the variable as seen by the
current module and its @code{cdr} specifies a name for the binding in
the current module's public interface.
@end deffn

@c begin (scm-doc-string "boot-9.scm" "define-public")
@deffn syntax define-public @dots{}
Equivalent to @code{(begin (define foo ...) (export foo))}.
@end deffn
@c end

@deffn syntax re-export variable @dots{}
Add all @var{variable}s (which must be symbols or pairs of symbols) to
the list of re-exported bindings of the current module.  Pairs of
symbols are handled as in @code{export}.  Re-exported bindings must be
imported by the current module from some other module.
@end deffn

@node Module System Reflection
@subsection Module System Reflection

The previous sections have described a declarative view of the module
system.  You can also work with it programmatically by accessing and
modifying various parts of the Scheme objects that Guile uses to
implement the module system.

At any time, there is a @dfn{current module}.  This module is the one
where a top-level @code{define} and similar syntax will add new
bindings.  You can find other module objects with @code{resolve-module},
for example.

These module objects can be used as the second argument to @code{eval}.

@deffn {Scheme Procedure} current-module
Return the current module object.
@end deffn

@deffn {Scheme Procedure} set-current-module module
Set the current module to @var{module} and return
the previous current module.
@end deffn

@deffn {Scheme Procedure} save-module-excursion thunk
Call @var{thunk} within a @code{dynamic-wind} such that the module that
is current at invocation time is restored when @var{thunk}'s dynamic
extent is left (@pxref{Dynamic Wind}).

More precisely, if @var{thunk} escapes non-locally, the current module
(at the time of escape) is saved, and the original current module (at
the time @var{thunk}'s dynamic extent was last entered) is restored.  If
@var{thunk}'s dynamic extent is re-entered, then the current module is
saved, and the previously saved inner module is set current again.
@end deffn

@deffn {Scheme Procedure} resolve-module name
Find the module named @var{name} and return it.  When it has not already
been defined, try to auto-load it.  When it can't be found that way
either, create an empty module.  The name is a list of symbols.
@end deffn

@deffn {Scheme Procedure} resolve-interface name
Find the module named @var{name} as with @code{resolve-module} and
return its interface.  The interface of a module is also a module
object, but it contains only the exported bindings.
@end deffn

@deffn {Scheme Procedure} module-use! module interface
Add @var{interface} to the front of the use-list of @var{module}.  Both
arguments should be module objects, and @var{interface} should very
likely be a module returned by @code{resolve-interface}.
@end deffn

@node Included Guile Modules
@subsection Included Guile Modules

@c FIXME::martin: Review me!

Some modules are included in the Guile distribution; here are references
to the entries in this manual which describe them in more detail:

@table @strong
@item boot-9
boot-9 is Guile's initialization module, and it is always loaded when
Guile starts up.

@item (ice-9 debug)
Mikael Djurfeldt's source-level debugging support for Guile
(@pxref{Tracing}).

@item (ice-9 expect)
Actions based on matching input from a port (@pxref{Expect}).

@item (ice-9 format)
Formatted output in the style of Common Lisp (@pxref{Formatted
Output}).

@item (ice-9 ftw)
File tree walker (@pxref{File Tree Walk}).

@item (ice-9 getopt-long)
Command line option processing (@pxref{getopt-long}).

@item (ice-9 history)
Refer to previous interactive expressions (@pxref{Value History}).

@item (ice-9 popen)
Pipes to and from child processes (@pxref{Pipes}).

@item (ice-9 pretty-print)
Nicely formatted output of Scheme expressions and objects
(@pxref{Pretty Printing}).

@item (ice-9 q)
First-in first-out queues (@pxref{Queues}).

@item (ice-9 rdelim)
Line- and character-delimited input (@pxref{Line/Delimited}).

@item (ice-9 readline)
@code{readline} interactive command line editing (@pxref{Readline
Support}).

@item (ice-9 receive)
Multiple-value handling with @code{receive} (@pxref{Multiple Values}).

@item (ice-9 regex)
Regular expression matching (@pxref{Regular Expressions}).

@item (ice-9 rw)
Block string input/output (@pxref{Block Reading and Writing}).

@item (ice-9 streams)
Sequence of values calculated on-demand (@pxref{Streams}).

@item (ice-9 syncase)
R5RS @code{syntax-rules} macro system (@pxref{Syntax Rules}).

@item (ice-9 threads)
Guile's support for multi threaded execution (@pxref{Scheduling}).

@item (ice-9 documentation)
Online documentation (REFFIXME).

@item (srfi srfi-1)
A library providing a lot of useful list and pair processing
procedures (@pxref{SRFI-1}).

@item (srfi srfi-2)
Support for @code{and-let*} (@pxref{SRFI-2}).

@item (srfi srfi-4)
Support for homogeneous numeric vectors (@pxref{SRFI-4}).

@item (srfi srfi-6)
Support for some additional string port procedures (@pxref{SRFI-6}).

@item (srfi srfi-8)
Multiple-value handling with @code{receive} (@pxref{SRFI-8}).

@item (srfi srfi-9)
Record definition with @code{define-record-type} (@pxref{SRFI-9}).

@item (srfi srfi-10)
Read hash extension @code{#,()} (@pxref{SRFI-10}).

@item (srfi srfi-11)
Multiple-value handling with @code{let-values} and @code{let*-values}
(@pxref{SRFI-11}).

@item (srfi srfi-13)
String library (@pxref{SRFI-13}).

@item (srfi srfi-14)
Character-set library (@pxref{SRFI-14}).

@item (srfi srfi-16)
@code{case-lambda} procedures of variable arity (@pxref{SRFI-16}).

@item (srfi srfi-17)
Getter-with-setter support (@pxref{SRFI-17}).

@item (srfi srfi-19)
Time/Date library (@pxref{SRFI-19}).

@item (srfi srfi-26)
Convenient syntax for partial application (@pxref{SRFI-26})

@item (srfi srfi-31)
@code{rec} convenient recursive expressions (@pxref{SRFI-31})

@item (ice-9 slib)
This module contains hooks for using Aubrey Jaffer's portable Scheme
library SLIB from Guile (@pxref{SLIB}).
@end table

@node R6RS Version References
@subsection R6RS Version References

Guile's module system includes support for locating modules based on
a declared version specifier of the same form as the one described in
R6RS (@pxref{Library form, R6RS Library Form,, r6rs, The Revised^6
Report on the Algorithmic Language Scheme}).  By using the
@code{#:version} keyword in a @code{define-module} form, a module may
specify a version as a list of zero or more exact, nonnegative integers.

This version can then be used to locate the module during the module
search process.  Client modules and callers of the @code{use-modules}
function may specify constraints on the versions of target modules by
providing a @dfn{version reference}, which has one of the following
forms:

@lisp
 (@var{sub-version-reference} ...)
 (and @var{version-reference} ...)
 (or @var{version-reference} ...)
 (not @var{version-reference})
@end lisp

in which @var{sub-version-reference} is in turn one of:

@lisp
 (@var{sub-version})
 (>= @var{sub-version})
 (<= @var{sub-version})
 (and @var{sub-version-reference} ...)
 (or @var{sub-version-reference} ...)
 (not @var{sub-version-reference})
@end lisp

in which @var{sub-version} is an exact, nonnegative integer as above. A
version reference matches a declared module version if each element of
the version reference matches a corresponding element of the module
version, according to the following rules:

@itemize @bullet
@item
The @code{and} sub-form matches a version or version element if every
element in the tail of the sub-form matches the specified version or
version element.

@item
The @code{or} sub-form matches a version or version element if any
element in the tail of the sub-form matches the specified version or
version element.

@item
The @code{not} sub-form matches a version or version element if the tail
of the sub-form does not match the version or version element.

@item
The @code{>=} sub-form matches a version element if the element is
greater than or equal to the @var{sub-version} in the tail of the
sub-form.

@item
The @code{<=} sub-form matches a version element if the version is less
than or equal to the @var{sub-version} in the tail of the sub-form.

@item
A @var{sub-version} matches a version element if one is @var{eqv?} to
the other.
@end itemize

For example, a module declared as:

@lisp
 (define-module (mylib mymodule) #:version (1 2 0))
@end lisp

would be successfully loaded by any of the following @code{use-modules}
expressions:

@lisp
 (use-modules ((mylib mymodule) #:version (1 2 (>= 0))))
 (use-modules ((mylib mymodule) #:version (or (1 2 0) (1 2 1))))
 (use-modules ((mylib mymodule) #:version ((and (>= 1) (not 2)) 2 0)))
@end lisp

@node R6RS Libraries
@subsection R6RS Libraries

In addition to the API described in the previous sections, you also
have the option to create modules using the portable @code{library} form
described in R6RS (@pxref{Library form, R6RS Library Form,, r6rs, The
Revised^6 Report on the Algorithmic Language Scheme}), and to import
libraries created in this format by other programmers.  Guile's R6RS
library implementation takes advantage of the flexibility built into the
module system by expanding the R6RS library form into a corresponding
Guile @code{define-module} form that specifies equivalent import and
export requirements and includes the same body expressions.  The library
expression:

@lisp
  (library (mylib (1 2))
    (import (otherlib (3)))
    (export mybinding))
@end lisp

is equivalent to the module definition:

@lisp
  (define-module (mylib)
    #:version (1 2)
    #:use-module ((otherlib) #:version (3))
    #:export (mybinding))
@end lisp

Central to the mechanics of R6RS libraries is the concept of import
and export @dfn{levels}, which control the visibility of bindings at
various phases of a library's lifecycle --- macros necessary to
expand forms in the library's body need to be available at expand
time; variables used in the body of a procedure exported by the
library must be available at runtime.  R6RS specifies the optional
@code{for} sub-form of an @emph{import set} specification (see below)
as a mechanism by which a library author can indicate that a
particular library import should take place at a particular phase
with respect to the lifecycle of the importing library.

Guile's libraries implementation uses a technique called
@dfn{implicit phasing} (first described by Abdulaziz Ghuloum and R.
Kent Dybvig), which allows the expander and compiler to automatically
determine the necessary visibility of a binding imported from another
library.  As such, the @code{for} sub-form described below is ignored by
Guile (but may be required by Schemes in which phasing is explicit).

@deffn {Scheme Syntax} library name (export export-spec ...) (import import-spec ...) body ...
Defines a new library with the specified name, exports, and imports,
and evaluates the specified body expressions in this library's
environment.

The library @var{name} is a non-empty list of identifiers, optionally
ending with a version specification of the form described above
(@pxref{Creating Guile Modules}).

Each @var{export-spec} is the name of a variable defined or imported
by the library, or must take the form
@code{(rename (internal-name external-name) ...)}, where the
identifier @var{internal-name} names a variable defined or imported
by the library and @var{external-name} is the name by which the
variable is seen by importing libraries.

Each @var{import-spec} must be either an @dfn{import set} (see below)
or must be of the form @code{(for import-set import-level ...)},
where each @var{import-level} is one of:

@lisp
  run
  expand
  (meta @var{level})
@end lisp

where @var{level} is an integer.  Note that since Guile does not
require explicit phase specification, any @var{import-set}s found
inside of @code{for} sub-forms will be ``unwrapped'' during
expansion and processed as if they had been specified directly.

Import sets in turn take one of the following forms:

@lisp
  @var{library-reference}
  (library @var{library-reference})
  (only @var{import-set} @var{identifier} ...)
  (except @var{import-set} @var{identifier} ...)
  (prefix @var{import-set} @var{identifier})
  (rename @var{import-set} (@var{internal-identifier} @var{external-identifier}) ...)
@end lisp

where @var{library-reference} is a non-empty list of identifiers
ending with an optional version reference (@pxref{R6RS Version
References}), and the other sub-forms have the following semantics,
defined recursively on nested @var{import-set}s:

@itemize @bullet

@item
The @code{library} sub-form is used to specify libraries for import
whose names begin with the identifier ``library.''

@item
The @code{only} sub-form imports only the specified @var{identifier}s
from the given @var{import-set}.

@item
The @code{except} sub-form imports all of the bindings exported by
@var{import-set} except for those that appear in the specified list
of @var{identifier}s.

@item
The @code{prefix} sub-form imports all of the bindings exported
by @var{import-set}, first prefixing them with the specified
@var{identifier}.

@item
The @code{rename} sub-form imports all of the identifiers exported
by @var{import-set}.  The binding for each @var{internal-identifier}
among these identifiers is made visible to the importing library as
the corresponding @var{external-identifier}; all other bindings are
imported using the names provided by @var{import-set}.

@end itemize

Note that because Guile translates R6RS libraries into module
definitions, an import specification may be used to declare a
dependency on a native Guile module --- although doing so may make
your libraries less portable to other Schemes.

@end deffn

@deffn {Scheme Syntax} import import-spec ...
Import into the current environment the libraries specified by the
given import specifications, where each @var{import-spec} takes the
same form as in the @code{library} form described above.
@end deffn

@node Accessing Modules from C
@subsection Accessing Modules from C

The last sections have described how modules are used in Scheme code,
which is the recommended way of creating and accessing modules.  You
can also work with modules from C, but it is more cumbersome.

The following procedures are available.

@deftypefn {C Procedure} SCM scm_current_module ()
Return the module that is the @emph{current module}.
@end deftypefn

@deftypefn {C Procedure} SCM scm_set_current_module (SCM @var{module})
Set the current module to @var{module} and return the previous current
module.
@end deftypefn

@deftypefn {C Procedure} SCM scm_c_call_with_current_module (SCM @var{module}, SCM (*@var{func})(void *), void *@var{data})
Call @var{func} and make @var{module} the current module during the
call.  The argument @var{data} is passed to @var{func}.  The return
value of @code{scm_c_call_with_current_module} is the return value of
@var{func}.
@end deftypefn

@deftypefn {C Procedure} SCM scm_c_lookup (const char *@var{name})
Return the variable bound to the symbol indicated by @var{name} in the
current module.  If there is no such binding or the symbol is not
bound to a variable, signal an error.
@end deftypefn

@deftypefn {C Procedure} SCM scm_lookup (SCM @var{name})
Like @code{scm_c_lookup}, but the symbol is specified directly.
@end deftypefn

@deftypefn {C Procedure} SCM scm_c_module_lookup (SCM @var{module}, const char *@var{name})
@deftypefnx {C Procedure} SCM scm_module_lookup (SCM @var{module}, SCM @var{name})
Like @code{scm_c_lookup} and @code{scm_lookup}, but the specified
module is used instead of the current one.
@end deftypefn

@deftypefn {C Procedure} SCM scm_c_define (const char *@var{name}, SCM @var{val})
Bind the symbol indicated by @var{name} to a variable in the current
module and set that variable to @var{val}.  When @var{name} is already
bound to a variable, use that.  Else create a new variable.
@end deftypefn

@deftypefn {C Procedure} SCM scm_define (SCM @var{name}, SCM @var{val})
Like @code{scm_c_define}, but the symbol is specified directly.
@end deftypefn

@deftypefn {C Procedure} SCM scm_c_module_define (SCM @var{module}, const char *@var{name}, SCM @var{val})
@deftypefnx {C Procedure} SCM scm_module_define (SCM @var{module}, SCM @var{name}, SCM @var{val})
Like @code{scm_c_define} and @code{scm_define}, but the specified
module is used instead of the current one.
@end deftypefn

@deftypefn {C Procedure} SCM scm_module_reverse_lookup (SCM @var{module}, SCM @var{variable})
Find the symbol that is bound to @var{variable} in @var{module}.  When no such binding is found, return @var{#f}.
@end deftypefn

@deftypefn {C Procedure} SCM scm_c_define_module (const char *@var{name}, void (*@var{init})(void *), void *@var{data})
Define a new module named @var{name} and make it current while
@var{init} is called, passing it @var{data}.  Return the module.

The parameter @var{name} is a string with the symbols that make up
the module name, separated by spaces.  For example, @samp{"foo bar"} names
the module @samp{(foo bar)}.

When there already exists a module named @var{name}, it is used
unchanged, otherwise, an empty module is created.
@end deftypefn

@deftypefn {C Procedure} SCM scm_c_resolve_module (const char *@var{name})
Find the module name @var{name} and return it.  When it has not
already been defined, try to auto-load it.  When it can't be found
that way either, create an empty module.  The name is interpreted as
for @code{scm_c_define_module}.
@end deftypefn

@deftypefn {C Procedure} SCM scm_resolve_module (SCM @var{name})
Like @code{scm_c_resolve_module}, but the name is given as a real list
of symbols.
@end deftypefn

@deftypefn {C Procedure} SCM scm_c_use_module (const char *@var{name})
Add the module named @var{name} to the uses list of the current
module, as with @code{(use-modules @var{name})}.  The name is
interpreted as for @code{scm_c_define_module}.
@end deftypefn

@deftypefn {C Procedure} SCM scm_c_export (const char *@var{name}, ...)
Add the bindings designated by @var{name}, ... to the public interface
of the current module.  The list of names is terminated by
@code{NULL}.
@end deftypefn

@node Variables
@subsection Variables
@tpindex Variables

Each module has its own hash table, sometimes known as an @dfn{obarray},
that maps the names defined in that module to their corresponding
variable objects.

A variable is a box-like object that can hold any Scheme value.  It is
said to be @dfn{undefined} if its box holds a special Scheme value that
denotes undefined-ness (which is different from all other Scheme values,
including for example @code{#f}); otherwise the variable is
@dfn{defined}.

On its own, a variable object is anonymous.  A variable is said to be
@dfn{bound} when it is associated with a name in some way, usually a
symbol in a module obarray.  When this happens, the relationship is
mutual: the variable is bound to the name (in that module), and the name
(in that module) is bound to the variable.

(That's the theory, anyway.  In practice, defined-ness and bound-ness
sometimes get confused, because Lisp and Scheme implementations have
often conflated --- or deliberately drawn no distinction between --- a
name that is unbound and a name that is bound to a variable whose value
is undefined.  We will try to be clear about the difference and explain
any confusion where it is unavoidable.)

Variables do not have a read syntax.  Most commonly they are created and
bound implicitly by @code{define} expressions: a top-level @code{define}
expression of the form

@lisp
(define @var{name} @var{value})
@end lisp

@noindent
creates a variable with initial value @var{value} and binds it to the
name @var{name} in the current module.  But they can also be created
dynamically by calling one of the constructor procedures
@code{make-variable} and @code{make-undefined-variable}.

@deffn {Scheme Procedure} make-undefined-variable
@deffnx {C Function} scm_make_undefined_variable ()
Return a variable that is initially unbound.
@end deffn

@deffn {Scheme Procedure} make-variable init
@deffnx {C Function} scm_make_variable (init)
Return a variable initialized to value @var{init}.
@end deffn

@deffn {Scheme Procedure} variable-bound? var
@deffnx {C Function} scm_variable_bound_p (var)
Return @code{#t} iff @var{var} is bound to a value.
Throws an error if @var{var} is not a variable object.
@end deffn

@deffn {Scheme Procedure} variable-ref var
@deffnx {C Function} scm_variable_ref (var)
Dereference @var{var} and return its value.
@var{var} must be a variable object; see @code{make-variable}
and @code{make-undefined-variable}.
@end deffn

@deffn {Scheme Procedure} variable-set! var val
@deffnx {C Function} scm_variable_set_x (var, val)
Set the value of the variable @var{var} to @var{val}.
@var{var} must be a variable object, @var{val} can be any
value. Return an unspecified value.
@end deffn

@deffn {Scheme Procedure} variable? obj
@deffnx {C Function} scm_variable_p (obj)
Return @code{#t} iff @var{obj} is a variable object, else
return @code{#f}.
@end deffn

@node provide and require
@subsection provide and require

Aubrey Jaffer, mostly to support his portable Scheme library SLIB,
implemented a provide/require mechanism for many Scheme implementations.
Library files in SLIB @emph{provide} a feature, and when user programs
@emph{require} that feature, the library file is loaded in.

For example, the file @file{random.scm} in the SLIB package contains the
line

@lisp
(provide 'random)
@end lisp

so to use its procedures, a user would type

@lisp
(require 'random)
@end lisp

and they would magically become available, @emph{but still have the same
names!}  So this method is nice, but not as good as a full-featured
module system.

When SLIB is used with Guile, provide and require can be used to access
its facilities.

@node Environments
@subsection Environments
@cindex environment

Scheme, as defined in R5RS, does @emph{not} have a full module system.
However it does define the concept of a top-level @dfn{environment}.
Such an environment maps identifiers (symbols) to Scheme objects such
as procedures and lists: @ref{About Closure}.  In other words, it
implements a set of @dfn{bindings}.

Environments in R5RS can be passed as the second argument to
@code{eval} (@pxref{Fly Evaluation}).  Three procedures are defined to
return environments: @code{scheme-report-environment},
@code{null-environment} and @code{interaction-environment} (@pxref{Fly
Evaluation}).

In addition, in Guile any module can be used as an R5RS environment,
i.e., passed as the second argument to @code{eval}.

Note: the following two procedures are available only when the
@code{(ice-9 r5rs)} module is loaded:

@lisp
(use-modules (ice-9 r5rs))
@end lisp

@deffn {Scheme Procedure} scheme-report-environment version
@deffnx {Scheme Procedure} null-environment version
@var{version} must be the exact integer `5', corresponding to revision
5 of the Scheme report (the Revised^5 Report on Scheme).
@code{scheme-report-environment} returns a specifier for an
environment that is empty except for all bindings defined in the
report that are either required or both optional and supported by the
implementation. @code{null-environment} returns a specifier for an
environment that is empty except for the (syntactic) bindings for all
syntactic keywords defined in the report that are either required or
both optional and supported by the implementation.

Currently Guile does not support values of @var{version} for other
revisions of the report.

The effect of assigning (through the use of @code{eval}) a variable
bound in a @code{scheme-report-environment} (for example @code{car})
is unspecified.  Currently the environments specified by
@code{scheme-report-environment} are not immutable in Guile.
@end deffn

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