2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
8 @node Procedures and Macros
9 @section Procedures and Macros
12 * Lambda:: Basic procedure creation using lambda.
13 * Primitive Procedures:: Procedures defined in C.
14 * Optional Arguments:: Handling keyword, optional and rest arguments.
15 * Procedure Properties:: Procedure properties and meta-information.
16 * Procedures with Setters:: Procedures with setters.
17 * Macros:: Lisp style macro definitions.
18 * Syntax Rules:: Support for R5RS @code{syntax-rules}.
19 * Syntax Case:: Support for the @code{syntax-case} system.
20 * Internal Macros:: Guile's internal representation.
25 @subsection Lambda: Basic Procedure Creation
28 @c FIXME::martin: Review me!
30 A @code{lambda} expression evaluates to a procedure. The environment
31 which is in effect when a @code{lambda} expression is evaluated is
32 enclosed in the newly created procedure, this is referred to as a
33 @dfn{closure} (@pxref{About Closure}).
35 When a procedure created by @code{lambda} is called with some actual
36 arguments, the environment enclosed in the procedure is extended by
37 binding the variables named in the formal argument list to new locations
38 and storing the actual arguments into these locations. Then the body of
39 the @code{lambda} expression is evaluation sequentially. The result of
40 the last expression in the procedure body is then the result of the
43 The following examples will show how procedures can be created using
44 @code{lambda}, and what you can do with these procedures.
47 (lambda (x) (+ x x)) @result{} @r{a procedure}
48 ((lambda (x) (+ x x)) 4) @result{} 8
51 The fact that the environment in effect when creating a procedure is
52 enclosed in the procedure is shown with this example:
57 (lambda (y) (+ x y))))
62 @deffn syntax lambda formals body
63 @var{formals} should be a formal argument list as described in the
67 @item (@var{variable1} @dots{})
68 The procedure takes a fixed number of arguments; when the procedure is
69 called, the arguments will be stored into the newly created location for
72 The procedure takes any number of arguments; when the procedure is
73 called, the sequence of actual arguments will converted into a list and
74 stored into the newly created location for the formal variable.
75 @item (@var{variable1} @dots{} @var{variablen} . @var{variablen+1})
76 If a space-delimited period precedes the last variable, then the
77 procedure takes @var{n} or more variables where @var{n} is the number
78 of formal arguments before the period. There must be at least one
79 argument before the period. The first @var{n} actual arguments will be
80 stored into the newly allocated locations for the first @var{n} formal
81 arguments and the sequence of the remaining actual arguments is
82 converted into a list and the stored into the location for the last
83 formal argument. If there are exactly @var{n} actual arguments, the
84 empty list is stored into the location of the last formal argument.
87 The list in @var{variable} or @var{variablen+1} is always newly
88 created and the procedure can modify it if desired. This is the case
89 even when the procedure is invoked via @code{apply}, the required part
90 of the list argument there will be copied (@pxref{Fly Evaluation,,
91 Procedures for On the Fly Evaluation}).
93 @var{body} is a sequence of Scheme expressions which are evaluated in
94 order when the procedure is invoked.
97 @node Primitive Procedures
98 @subsection Primitive Procedures
100 @cindex primitive procedures
102 Procedures written in C can be registered for use from Scheme,
103 provided they take only arguments of type @code{SCM} and return
104 @code{SCM} values. @code{scm_c_define_gsubr} is likely to be the most
105 useful mechanism, combining the process of registration
106 (@code{scm_c_make_gsubr}) and definition (@code{scm_define}).
108 @deftypefun SCM scm_c_make_gsubr (const char *name, int req, int opt, int rst, fcn)
109 Register a C procedure @var{FCN} as a ``subr'' --- a primitive
110 subroutine that can be called from Scheme. It will be associated with
111 the given @var{name} but no environment binding will be created. The
112 arguments @var{req}, @var{opt} and @var{rst} specify the number of
113 required, optional and ``rest'' arguments respectively. The total
114 number of these arguments should match the actual number of arguments
115 to @var{fcn}. The number of rest arguments should be 0 or 1.
116 @code{scm_c_make_gsubr} returns a value of type @code{SCM} which is a
117 ``handle'' for the procedure.
120 @deftypefun SCM scm_c_define_gsubr (const char *name, int req, int opt, int rst, fcn)
121 Register a C procedure @var{FCN}, as for @code{scm_c_make_gsubr}
122 above, and additionally create a top-level Scheme binding for the
123 procedure in the ``current environment'' using @code{scm_define}.
124 @code{scm_c_define_gsubr} returns a handle for the procedure in the
125 same way as @code{scm_c_make_gsubr}, which is usually not further
129 @code{scm_c_make_gsubr} and @code{scm_c_define_gsubr} automatically
130 use @code{scm_c_make_subr} and also @code{scm_makcclo} if necessary.
131 It is advisable to use the gsubr variants since they provide a
132 slightly higher-level abstraction of the Guile implementation.
134 @node Optional Arguments
135 @subsection Optional Arguments
137 @c FIXME::martin: Review me!
139 Scheme procedures, as defined in R5RS, can either handle a fixed number
140 of actual arguments, or a fixed number of actual arguments followed by
141 arbitrarily many additional arguments. Writing procedures of variable
142 arity can be useful, but unfortunately, the syntactic means for handling
143 argument lists of varying length is a bit inconvenient. It is possible
144 to give names to the fixed number of argument, but the remaining
145 (optional) arguments can be only referenced as a list of values
148 Guile comes with the module @code{(ice-9 optargs)}, which makes using
149 optional arguments much more convenient. In addition, this module
150 provides syntax for handling keywords in argument lists
153 Before using any of the procedures or macros defined in this section,
154 you have to load the module @code{(ice-9 optargs)} with the statement:
156 @cindex @code{optargs}
158 (use-modules (ice-9 optargs))
162 * let-optional Reference:: Locally binding optional arguments.
163 * let-keywords Reference:: Locally binding keywords arguments.
164 * lambda* Reference:: Creating advanced argument handling procedures.
165 * define* Reference:: Defining procedures and macros.
169 @node let-optional Reference
170 @subsubsection let-optional Reference
172 @c FIXME::martin: Review me!
174 The syntax @code{let-optional} and @code{let-optional*} are for
175 destructuring rest argument lists and giving names to the various list
176 elements. @code{let-optional} binds all variables simultaneously, while
177 @code{let-optional*} binds them sequentially, consistent with @code{let}
178 and @code{let*} (@pxref{Local Bindings}).
180 @deffn {library syntax} let-optional rest-arg (binding @dots{}) expr @dots{}
181 @deffnx {library syntax} let-optional* rest-arg (binding @dots{}) expr @dots{}
182 These two macros give you an optional argument interface that is very
183 @dfn{Schemey} and introduces no fancy syntax. They are compatible with
184 the scsh macros of the same name, but are slightly extended. Each of
185 @var{binding} may be of one of the forms @var{var} or @code{(@var{var}
186 @var{default-value})}. @var{rest-arg} should be the rest-argument of the
187 procedures these are used from. The items in @var{rest-arg} are
188 sequentially bound to the variable names are given. When @var{rest-arg}
189 runs out, the remaining vars are bound either to the default values or
190 @code{#f} if no default value was specified. @var{rest-arg} remains
191 bound to whatever may have been left of @var{rest-arg}.
193 After binding the variables, the expressions @var{expr} @dots{} are
198 @node let-keywords Reference
199 @subsubsection let-keywords Reference
201 @code{let-keywords} and @code{let-keywords*} extract values from
202 keyword style argument lists, binding local variables to those values
205 @deffn {library syntax} let-keywords args allow-other-keys? (binding @dots{}) body @dots{}
206 @deffnx {library syntax} let-keywords* args allow-other-keys? (binding @dots{}) body @dots{}
207 @var{args} is evaluated and should give a list of the form
208 @code{(#:keyword1 value1 #:keyword2 value2 @dots{})}. The
209 @var{binding}s are variables and default expressions, with the
210 variables to be set (by name) from the keyword values. The @var{body}
211 forms are then evaluated and the last is the result. An example will
212 make the syntax clearest,
215 (define args '(#:xyzzy "hello" #:foo "world"))
217 (let-keywords args #t
218 ((foo "default for foo")
219 (bar (string-append "default" "for" "bar")))
223 @print{} world, defaultforbar
226 The binding for @code{foo} comes from the @code{#:foo} keyword in
227 @code{args}. But the binding for @code{bar} is the default in the
228 @code{let-keywords}, since there's no @code{#:bar} in the args.
230 @var{allow-other-keys?} is evaluated and controls whether unknown
231 keywords are allowed in the @var{args} list. When true other keys are
232 ignored (such as @code{#:xyzzy} in the example), when @code{#f} an
233 error is thrown for anything unknown.
235 @code{let-keywords} is like @code{let} (@pxref{Local Bindings}) in
236 that all bindings are made at once, the defaults expressions are
237 evaluated (if needed) outside the scope of the @code{let-keywords}.
239 @code{let-keywords*} is like @code{let*}, each binding is made
240 successively, and the default expressions see the bindings previously
241 made. This is the style used by @code{lambda*} keywords
242 (@pxref{lambda* Reference}). For example,
245 (define args '(#:foo 3))
247 (let-keywords* args #f
254 The expression for each default is only evaluated if it's needed,
255 ie. if the keyword doesn't appear in @var{args}. So one way to make a
256 keyword mandatory is to throw an error of some sort as the default.
259 (define args '(#:start 7 #:finish 13))
261 (let-keywords* args #t
263 (stop (error "missing #:stop argument")))
265 @result{} ERROR: missing #:stop argument
270 @node lambda* Reference
271 @subsubsection lambda* Reference
273 When using optional and keyword argument lists, @code{lambda} for
274 creating a procedure then @code{let-optional} or @code{let-keywords}
275 is a bit lengthy. @code{lambda*} combines the features of those
276 macros into a single convenient syntax.
278 @deffn {library syntax} lambda* ([var@dots{}] @* [#:optional vardef@dots{}] @* [#:key vardef@dots{} [#:allow-other-keys]] @* [#:rest var | . var]) @* body
280 Create a procedure which takes optional and/or keyword arguments
281 specified with @code{#:optional} and @code{#:key}. For example,
284 (lambda* (a b #:optional c d . e) '())
287 is a procedure with fixed arguments @var{a} and @var{b}, optional
288 arguments @var{c} and @var{d}, and rest argument @var{e}. If the
289 optional arguments are omitted in a call, the variables for them are
292 @code{lambda*} can also take keyword arguments. For example, a procedure
296 (lambda* (#:key xyzzy larch) '())
299 can be called with any of the argument lists @code{(#:xyzzy 11)},
300 @code{(#:larch 13)}, @code{(#:larch 42 #:xyzzy 19)}, @code{()}.
301 Whichever arguments are given as keywords are bound to values (and
302 those not given are @code{#f}).
304 Optional and keyword arguments can also have default values to take
305 when not present in a call, by giving a two-element list of variable
306 name and expression. For example in
309 (lambda* (foo #:optional (bar 42) #:key (baz 73))
313 @var{foo} is a fixed argument, @var{bar} is an optional argument with
314 default value 42, and baz is a keyword argument with default value 73.
315 Default value expressions are not evaluated unless they are needed,
316 and until the procedure is called.
318 Normally it's an error if a call has keywords other than those
319 specified by @code{#:key}, but adding @code{#:allow-other-keys} to the
320 definition (after the keyword argument declarations) will ignore
323 If a call has a keyword given twice, the last value is used. For
327 ((lambda* (#:key (heads 0) (tails 0))
328 (display (list heads tails)))
329 #:heads 37 #:tails 42 #:heads 99)
333 @code{#:rest} is a synonym for the dotted syntax rest argument. The
334 argument lists @code{(a . b)} and @code{(a #:rest b)} are equivalent
335 in all respects. This is provided for more similarity to DSSSL,
336 MIT-Scheme and Kawa among others, as well as for refugees from other
339 When @code{#:key} is used together with a rest argument, the keyword
340 parameters in a call all remain in the rest list. This is the same as
341 Common Lisp. For example,
344 ((lambda* (#:key (x 0) #:allow-other-keys #:rest r)
347 @print{} (#:x 123 #:y 456)
350 @code{#:optional} and @code{#:key} establish their bindings
351 successively, from left to right, as per @code{let-optional*} and
352 @code{let-keywords*}. This means default expressions can refer back
353 to prior parameters, for example
356 (lambda* (start #:optional (end (+ 10 start)))
357 (do ((i start (1+ i)))
364 @node define* Reference
365 @subsubsection define* Reference
367 @c FIXME::martin: Review me!
369 Just like @code{define} has a shorthand notation for defining procedures
370 (@pxref{Lambda Alternatives}), @code{define*} is provided as an
371 abbreviation of the combination of @code{define} and @code{lambda*}.
373 @code{define*-public} is the @code{lambda*} version of
374 @code{define-public}; @code{defmacro*} and @code{defmacro*-public} exist
375 for defining macros with the improved argument list handling
376 possibilities. The @code{-public} versions not only define the
377 procedures/macros, but also export them from the current module.
379 @deffn {library syntax} define* formals body
380 @deffnx {library syntax} define*-public formals body
381 @code{define*} and @code{define*-public} support optional arguments with
382 a similar syntax to @code{lambda*}. They also support arbitrary-depth
383 currying, just like Guile's define. Some examples:
386 (define* (x y #:optional a (z 3) #:key w . u)
387 (display (list y z u)))
389 defines a procedure @code{x} with a fixed argument @var{y}, an optional
390 argument @var{a}, another optional argument @var{z} with default value 3,
391 a keyword argument @var{w}, and a rest argument @var{u}.
394 (define-public* ((foo #:optional bar) #:optional baz) '())
397 This illustrates currying. A procedure @code{foo} is defined, which,
398 when called with an optional argument @var{bar}, returns a procedure
399 that takes an optional argument @var{baz}.
401 Of course, @code{define*[-public]} also supports @code{#:rest} and
402 @code{#:allow-other-keys} in the same way as @code{lambda*}.
405 @deffn {library syntax} defmacro* name formals body
406 @deffnx {library syntax} defmacro*-public name formals body
407 These are just like @code{defmacro} and @code{defmacro-public} except that they
408 take @code{lambda*}-style extended parameter lists, where @code{#:optional},
409 @code{#:key}, @code{#:allow-other-keys} and @code{#:rest} are allowed with the usual
410 semantics. Here is an example of a macro with an optional argument:
413 (defmacro* transmorgify (a #:optional b)
419 @node Procedure Properties
420 @subsection Procedure Properties and Meta-information
422 @c FIXME::martin: Review me!
424 Procedures always have attached the environment in which they were
425 created and information about how to apply them to actual arguments. In
426 addition to that, properties and meta-information can be stored with
427 procedures. The procedures in this section can be used to test whether
428 a given procedure satisfies a condition; and to access and set a
429 procedure's property.
431 The first group of procedures are predicates to test whether a Scheme
432 object is a procedure, or a special procedure, respectively.
433 @code{procedure?} is the most general predicates, it returns @code{#t}
434 for any kind of procedure. @code{closure?} does not return @code{#t}
435 for primitive procedures, and @code{thunk?} only returns @code{#t} for
436 procedures which do not accept any arguments.
439 @deffn {Scheme Procedure} procedure? obj
440 @deffnx {C Function} scm_procedure_p (obj)
441 Return @code{#t} if @var{obj} is a procedure.
444 @deffn {Scheme Procedure} closure? obj
445 @deffnx {C Function} scm_closure_p (obj)
446 Return @code{#t} if @var{obj} is a closure.
449 @deffn {Scheme Procedure} thunk? obj
450 @deffnx {C Function} scm_thunk_p (obj)
451 Return @code{#t} if @var{obj} is a thunk.
454 @c FIXME::martin: Is that true?
455 @cindex procedure properties
456 Procedure properties are general properties to be attached to
457 procedures. These can be the name of a procedure or other relevant
458 information, such as debug hints.
460 @deffn {Scheme Procedure} procedure-name proc
461 @deffnx {C Function} scm_procedure_name (proc)
462 Return the name of the procedure @var{proc}
465 @deffn {Scheme Procedure} procedure-source proc
466 @deffnx {C Function} scm_procedure_source (proc)
467 Return the source of the procedure @var{proc}.
470 @deffn {Scheme Procedure} procedure-environment proc
471 @deffnx {C Function} scm_procedure_environment (proc)
472 Return the environment of the procedure @var{proc}.
475 @deffn {Scheme Procedure} procedure-properties proc
476 @deffnx {C Function} scm_procedure_properties (proc)
477 Return @var{obj}'s property list.
480 @deffn {Scheme Procedure} procedure-property obj key
481 @deffnx {C Function} scm_procedure_property (obj, key)
482 Return the property of @var{obj} with name @var{key}.
485 @deffn {Scheme Procedure} set-procedure-properties! proc alist
486 @deffnx {C Function} scm_set_procedure_properties_x (proc, alist)
487 Set @var{obj}'s property list to @var{alist}.
490 @deffn {Scheme Procedure} set-procedure-property! obj key value
491 @deffnx {C Function} scm_set_procedure_property_x (obj, key, value)
492 In @var{obj}'s property list, set the property named @var{key} to
496 @cindex procedure documentation
497 Documentation for a procedure can be accessed with the procedure
498 @code{procedure-documentation}.
500 @deffn {Scheme Procedure} procedure-documentation proc
501 @deffnx {C Function} scm_procedure_documentation (proc)
502 Return the documentation string associated with @code{proc}. By
503 convention, if a procedure contains more than one expression and the
504 first expression is a string constant, that string is assumed to contain
505 documentation for that procedure.
509 @node Procedures with Setters
510 @subsection Procedures with Setters
512 @c FIXME::martin: Review me!
514 @c FIXME::martin: Document `operator struct'.
516 @cindex procedure with setter
518 A @dfn{procedure with setter} is a special kind of procedure which
519 normally behaves like any accessor procedure, that is a procedure which
520 accesses a data structure. The difference is that this kind of
521 procedure has a so-called @dfn{setter} attached, which is a procedure
522 for storing something into a data structure.
524 Procedures with setters are treated specially when the procedure appears
525 in the special form @code{set!} (REFFIXME). How it works is best shown
528 Suppose we have a procedure called @code{foo-ref}, which accepts two
529 arguments, a value of type @code{foo} and an integer. The procedure
530 returns the value stored at the given index in the @code{foo} object.
531 Let @code{f} be a variable containing such a @code{foo} data
532 structure.@footnote{Working definitions would be:
534 (define foo-ref vector-ref)
535 (define foo-set! vector-set!)
536 (define f (make-vector 2 #f))
541 (foo-ref f 0) @result{} bar
542 (foo-ref f 1) @result{} braz
545 Also suppose that a corresponding setter procedure called
546 @code{foo-set!} does exist.
550 (foo-ref f 0) @result{} bla
553 Now we could create a new procedure called @code{foo}, which is a
554 procedure with setter, by calling @code{make-procedure-with-setter} with
555 the accessor and setter procedures @code{foo-ref} and @code{foo-set!}.
556 Let us call this new procedure @code{foo}.
559 (define foo (make-procedure-with-setter foo-ref foo-set!))
562 @code{foo} can from now an be used to either read from the data
563 structure stored in @code{f}, or to write into the structure.
566 (set! (foo f 0) 'dum)
567 (foo f 0) @result{} dum
570 @deffn {Scheme Procedure} make-procedure-with-setter procedure setter
571 @deffnx {C Function} scm_make_procedure_with_setter (procedure, setter)
572 Create a new procedure which behaves like @var{procedure}, but
573 with the associated setter @var{setter}.
576 @deffn {Scheme Procedure} procedure-with-setter? obj
577 @deffnx {C Function} scm_procedure_with_setter_p (obj)
578 Return @code{#t} if @var{obj} is a procedure with an
579 associated setter procedure.
582 @deffn {Scheme Procedure} procedure proc
583 @deffnx {C Function} scm_procedure (proc)
584 Return the procedure of @var{proc}, which must be either a
585 procedure with setter, or an operator struct.
588 @deffn {Scheme Procedure} setter proc
589 Return the setter of @var{proc}, which must be either a procedure with
590 setter or an operator struct.
595 @subsection Lisp Style Macro Definitions
598 @cindex transformation
599 Macros are objects which cause the expression that they appear in to be
600 transformed in some way @emph{before} being evaluated. In expressions
601 that are intended for macro transformation, the identifier that names
602 the relevant macro must appear as the first element, like this:
605 (@var{macro-name} @var{macro-args} @dots{})
608 In Lisp-like languages, the traditional way to define macros is very
609 similar to procedure definitions. The key differences are that the
610 macro definition body should return a list that describes the
611 transformed expression, and that the definition is marked as a macro
612 definition (rather than a procedure definition) by the use of a
613 different definition keyword: in Lisp, @code{defmacro} rather than
614 @code{defun}, and in Scheme, @code{define-macro} rather than
618 @fnindex define-macro
619 Guile supports this style of macro definition using both @code{defmacro}
620 and @code{define-macro}. The only difference between them is how the
621 macro name and arguments are grouped together in the definition:
624 (defmacro @var{name} (@var{args} @dots{}) @var{body} @dots{})
631 (define-macro (@var{name} @var{args} @dots{}) @var{body} @dots{})
635 The difference is analogous to the corresponding difference between
636 Lisp's @code{defun} and Scheme's @code{define}.
638 @code{false-if-exception}, from the @file{boot-9.scm} file in the Guile
639 distribution, is a good example of macro definition using
643 (defmacro false-if-exception (expr)
650 The effect of this definition is that expressions beginning with the
651 identifier @code{false-if-exception} are automatically transformed into
652 a @code{catch} expression following the macro definition specification.
656 (false-if-exception (open-input-file "may-not-exist"))
659 (lambda () (open-input-file "may-not-exist"))
665 @subsection The R5RS @code{syntax-rules} System
666 @cindex R5RS syntax-rules system
668 R5RS defines an alternative system for macro and syntax transformations
669 using the keywords @code{define-syntax}, @code{let-syntax},
670 @code{letrec-syntax} and @code{syntax-rules}.
672 The main difference between the R5RS system and the traditional macros
673 of the previous section is how the transformation is specified. In
674 R5RS, rather than permitting a macro definition to return an arbitrary
675 expression, the transformation is specified in a pattern language that
679 does not require complicated quoting and extraction of components of the
680 source expression using @code{caddr} etc.
683 is designed such that the bindings associated with identifiers in the
684 transformed expression are well defined, and such that it is impossible
685 for the transformed expression to construct new identifiers.
689 The last point is commonly referred to as being @dfn{hygienic}: the R5RS
690 @code{syntax-case} system provides @dfn{hygienic macros}.
692 For example, the R5RS pattern language for the @code{false-if-exception}
693 example of the previous section looks like this:
703 @cindex @code{syncase}
704 In Guile, the @code{syntax-rules} system is provided by the @code{(ice-9
705 syncase)} module. To make these facilities available in your code,
706 include the expression @code{(use-syntax (ice-9 syncase))} (@pxref{Using
707 Guile Modules}) before the first usage of @code{define-syntax} etc. If
708 you are writing a Scheme module, you can alternatively include the form
709 @code{#:use-syntax (ice-9 syncase)} in your @code{define-module}
710 declaration (@pxref{Creating Guile Modules}).
713 * Pattern Language:: The @code{syntax-rules} pattern language.
714 * Define-Syntax:: Top level syntax definitions.
715 * Let-Syntax:: Local syntax definitions.
719 @node Pattern Language
720 @subsubsection The @code{syntax-rules} Pattern Language
724 @subsubsection Top Level Syntax Definitions
726 define-syntax: The gist is
728 (define-syntax <keyword> <transformer-spec>)
730 makes the <keyword> into a macro so that
734 expands at _compile_ or _read_ time (i.e. before any
735 evaluation begins) into some expression that is
736 given by the <transformer-spec>.
740 @subsubsection Local Syntax Definitions
744 @subsection Support for the @code{syntax-case} System
748 @node Internal Macros
749 @subsection Internal Representation of Macros and Syntax
751 Internally, Guile uses three different flavors of macros. The three
752 flavors are called @dfn{acro} (or @dfn{syntax}), @dfn{macro} and
762 with @code{foo} being some flavor of macro, one of the following things
763 will happen when the expression is evaluated.
767 When @code{foo} has been defined to be an @dfn{acro}, the procedure used
768 in the acro definition of @code{foo} is passed the whole expression and
769 the current lexical environment, and whatever that procedure returns is
770 the value of evaluating the expression. You can think of this a
771 procedure that receives its argument as an unevaluated expression.
774 When @code{foo} has been defined to be a @dfn{macro}, the procedure used
775 in the macro definition of @code{foo} is passed the whole expression and
776 the current lexical environment, and whatever that procedure returns is
777 evaluated again. That is, the procedure should return a valid Scheme
781 When @code{foo} has been defined to be a @dfn{mmacro}, the procedure
782 used in the mmacro definition of `foo' is passed the whole expression
783 and the current lexical environment, and whatever that procedure returns
784 replaces the original expression. Evaluation then starts over from the
785 new expression that has just been returned.
788 The key difference between a @dfn{macro} and a @dfn{mmacro} is that the
789 expression returned by a @dfn{mmacro} procedure is remembered (or
790 @dfn{memoized}) so that the expansion does not need to be done again
791 next time the containing code is evaluated.
793 The primitives @code{procedure->syntax}, @code{procedure->macro} and
794 @code{procedure->memoizing-macro} are used to construct acros, macros
795 and mmacros respectively. However, if you do not have a very special
796 reason to use one of these primitives, you should avoid them: they are
797 very specific to Guile's current implementation and therefore likely to
798 change. Use @code{defmacro}, @code{define-macro} (@pxref{Macros}) or
799 @code{define-syntax} (@pxref{Syntax Rules}) instead. (In low level
800 terms, @code{defmacro}, @code{define-macro} and @code{define-syntax} are
801 all implemented as mmacros.)
803 @deffn {Scheme Procedure} procedure->syntax code
804 @deffnx {C Function} scm_makacro (code)
805 Return a macro which, when a symbol defined to this value appears as the
806 first symbol in an expression, returns the result of applying @var{code}
807 to the expression and the environment.
810 @deffn {Scheme Procedure} procedure->macro code
811 @deffnx {C Function} scm_makmacro (code)
812 Return a macro which, when a symbol defined to this value appears as the
813 first symbol in an expression, evaluates the result of applying
814 @var{code} to the expression and the environment. For example:
820 `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))
824 (set! @i{foo} (tracef @i{foo} '@i{foo})).
828 @deffn {Scheme Procedure} procedure->memoizing-macro code
829 @deffnx {C Function} scm_makmmacro (code)
830 Return a macro which, when a symbol defined to this value appears as the
831 first symbol in an expression, evaluates the result of applying
832 @var{code} to the expression and the environment.
833 @code{procedure->memoizing-macro} is the same as
834 @code{procedure->macro}, except that the expression returned by
835 @var{code} replaces the original macro expression in the memoized form
836 of the containing code.
839 In the following primitives, @dfn{acro} flavor macros are referred to
840 as @dfn{syntax transformers}.
842 @deffn {Scheme Procedure} macro? obj
843 @deffnx {C Function} scm_macro_p (obj)
844 Return @code{#t} if @var{obj} is a regular macro, a memoizing macro or a
848 @deffn {Scheme Procedure} macro-type m
849 @deffnx {C Function} scm_macro_type (m)
850 Return one of the symbols @code{syntax}, @code{macro} or
851 @code{macro!}, depending on whether @var{m} is a syntax
852 transformer, a regular macro, or a memoizing macro,
853 respectively. If @var{m} is not a macro, @code{#f} is
857 @deffn {Scheme Procedure} macro-name m
858 @deffnx {C Function} scm_macro_name (m)
859 Return the name of the macro @var{m}.
862 @deffn {Scheme Procedure} macro-transformer m
863 @deffnx {C Function} scm_macro_transformer (m)
864 Return the transformer of the macro @var{m}.
867 @deffn {Scheme Procedure} cons-source xorig x y
868 @deffnx {C Function} scm_cons_source (xorig, x, y)
869 Create and return a new pair whose car and cdr are @var{x} and @var{y}.
870 Any source properties associated with @var{xorig} are also associated
876 @c TeX-master: "guile.texi"