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 @chapter 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 @section 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 @section 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 @section 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 @subsection 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 @subsection let-keywords Reference
201 @c FIXME::martin: Review me!
203 @code{let-keywords} and @code{let-keywords*} are used for extracting
204 values from argument lists which use keywords instead of argument
205 position for binding local variables to argument values.
207 @code{let-keywords} binds all variables simultaneously, while
208 @code{let-keywords*} binds them sequentially, consistent with @code{let}
209 and @code{let*} (@pxref{Local Bindings}).
211 @deffn {library syntax} let-keywords rest-arg allow-other-keys? (binding @dots{}) expr @dots{}
212 @deffnx {library syntax} let-keywords rest-arg allow-other-keys? (binding @dots{}) expr @dots{}
213 These macros pick out keyword arguments from @var{rest-arg}, but do not
214 modify it. This is consistent at least with Common Lisp, which
215 duplicates keyword arguments in the rest argument. More explanation of what
216 keyword arguments in a lambda list look like can be found below in
217 the documentation for @code{lambda*}
218 (@pxref{lambda* Reference}). @var{binding}s can have the same form as
219 for @code{let-optional}. If @var{allow-other-keys?} is false, an error
220 will be thrown if anything that looks like a keyword argument but does
221 not match a known keyword parameter will result in an error.
223 After binding the variables, the expressions @var{expr} @dots{} are
228 @node lambda* Reference
229 @subsection lambda* Reference
231 @c FIXME::martin: Review me!
233 When using optional and keyword argument lists, using @code{lambda} for
234 creating procedures and using @code{let-optional} or @code{let-keywords}
235 is a bit lengthy. Therefore, @code{lambda*} is provided, which combines
236 the features of those macros into a single convenient syntax.
238 For quick reference, here is the syntax of the formal argument list for
239 @code{lambda*} (brackets are used to indicate grouping only):
242 ext-param-list ::= [identifier]* [#:optional [ext-var-decl]+]?
243 [#:key [ext-var-decl]+ [#:allow-other-keys]?]?
244 [[#:rest identifier]|[. identifier]]?
246 ext-var-decl ::= identifier | ( identifier expression )
249 The characters `*', `+' and `?' are not to be taken literally; they mean
250 respectively, zero or more occurrences, one or more occurrences, and one
253 @deffn {library syntax} lambda* formals body
254 @code{lambda*} creates a procedure that takes optional arguments. These
255 are specified by putting them inside brackets at the end of the
256 parameter list, but before any dotted rest argument. For example,
259 (lambda* (a b #:optional c d . e) '())
262 creates a procedure with fixed arguments @var{a} and @var{b}, optional
263 arguments @var{c} and @var{d}, and rest argument @var{e}. If the
264 optional arguments are omitted in a call, the variables for them are
267 @code{lambda*} can also take keyword arguments. For example, a procedure
271 (lambda* (#:key xyzzy larch) '())
274 can be called with any of the argument lists @code{(#:xyzzy 11)}
275 @code{(#:larch 13)} @code{(#:larch 42 #:xyzzy 19)} @code{()}. Whichever
276 arguments are given as keywords are bound to values.
278 Optional and keyword arguments can also be given default values
279 which they take on when they are not present in a call, by giving a
280 two-item list in place of an optional argument, for example in:
283 (lambda* (foo #:optional (bar 42) #:key (baz 73))
287 @var{foo} is a fixed argument, @var{bar} is an optional argument with
288 default value 42, and baz is a keyword argument with default value 73.
289 Default value expressions are not evaluated unless they are needed and
290 until the procedure is called.
292 @code{lambda*} also supports two more special parameter list keywords.
294 @code{lambda*}-defined procedures now throw an error by default if a
295 keyword other than one of those specified is found in the actual
296 passed arguments. However, specifying @code{#:allow-other-keys}
297 immediately after the keyword argument declarations restores the
298 previous behavior of ignoring unknown keywords. @code{lambda*} also now
299 guarantees that if the same keyword is passed more than once, the
300 last one passed is the one that takes effect. For example,
303 ((lambda* (#:key (heads 0) (tails 0)) (display (list heads tails)))
304 #:heads 37 #:tails 42 #:heads 99)
307 would result in (99 47) being displayed.
309 @code{#:rest} is also now provided as a synonym for the dotted syntax
310 rest argument. The argument lists @code{(a . b)} and @code{(a #:rest b)}
311 are equivalent in all respects to @code{lambda*}. This is provided for
312 more similarity to DSSSL, MIT-Scheme and Kawa among others, as well as
313 for refugees from other Lisp dialects.
317 @node define* Reference
318 @subsection define* Reference
320 @c FIXME::martin: Review me!
322 Just like @code{define} has a shorthand notation for defining procedures
323 (@pxref{Lambda Alternatives}), @code{define*} is provided as an
324 abbreviation of the combination of @code{define} and @code{lambda*}.
326 @code{define*-public} is the @code{lambda*} version of
327 @code{define-public}; @code{defmacro*} and @code{defmacro*-public} exist
328 for defining macros with the improved argument list handling
329 possibilities. The @code{-public} versions not only define the
330 procedures/macros, but also export them from the current module.
332 @deffn {library syntax} define* formals body
333 @deffnx {library syntax} define*-public formals body
334 @code{define*} and @code{define*-public} support optional arguments with
335 a similar syntax to @code{lambda*}. They also support arbitrary-depth
336 currying, just like Guile's define. Some examples:
339 (define* (x y #:optional a (z 3) #:key w . u)
340 (display (list y z u)))
342 defines a procedure @code{x} with a fixed argument @var{y}, an optional
343 argument @var{a}, another optional argument @var{z} with default value 3,
344 a keyword argument @var{w}, and a rest argument @var{u}.
347 (define-public* ((foo #:optional bar) #:optional baz) '())
350 This illustrates currying. A procedure @code{foo} is defined, which,
351 when called with an optional argument @var{bar}, returns a procedure
352 that takes an optional argument @var{baz}.
354 Of course, @code{define*[-public]} also supports @code{#:rest} and
355 @code{#:allow-other-keys} in the same way as @code{lambda*}.
358 @deffn {library syntax} defmacro* name formals body
359 @deffnx {library syntax} defmacro*-public name formals body
360 These are just like @code{defmacro} and @code{defmacro-public} except that they
361 take @code{lambda*}-style extended parameter lists, where @code{#:optional},
362 @code{#:key}, @code{#:allow-other-keys} and @code{#:rest} are allowed with the usual
363 semantics. Here is an example of a macro with an optional argument:
366 (defmacro* transmorgify (a #:optional b)
372 @node Procedure Properties
373 @section Procedure Properties and Meta-information
375 @c FIXME::martin: Review me!
377 Procedures always have attached the environment in which they were
378 created and information about how to apply them to actual arguments. In
379 addition to that, properties and meta-information can be stored with
380 procedures. The procedures in this section can be used to test whether
381 a given procedure satisfies a condition; and to access and set a
382 procedure's property.
384 The first group of procedures are predicates to test whether a Scheme
385 object is a procedure, or a special procedure, respectively.
386 @code{procedure?} is the most general predicates, it returns @code{#t}
387 for any kind of procedure. @code{closure?} does not return @code{#t}
388 for primitive procedures, and @code{thunk?} only returns @code{#t} for
389 procedures which do not accept any arguments.
392 @deffn {Scheme Procedure} procedure? obj
393 @deffnx {C Function} scm_procedure_p (obj)
394 Return @code{#t} if @var{obj} is a procedure.
397 @deffn {Scheme Procedure} closure? obj
398 @deffnx {C Function} scm_closure_p (obj)
399 Return @code{#t} if @var{obj} is a closure.
402 @deffn {Scheme Procedure} thunk? obj
403 @deffnx {C Function} scm_thunk_p (obj)
404 Return @code{#t} if @var{obj} is a thunk.
407 @c FIXME::martin: Is that true?
408 @cindex procedure properties
409 Procedure properties are general properties to be attached to
410 procedures. These can be the name of a procedure or other relevant
411 information, such as debug hints.
413 @deffn {Scheme Procedure} procedure-name proc
414 @deffnx {C Function} scm_procedure_name (proc)
415 Return the name of the procedure @var{proc}
418 @deffn {Scheme Procedure} procedure-source proc
419 @deffnx {C Function} scm_procedure_source (proc)
420 Return the source of the procedure @var{proc}.
423 @deffn {Scheme Procedure} procedure-environment proc
424 @deffnx {C Function} scm_procedure_environment (proc)
425 Return the environment of the procedure @var{proc}.
428 @deffn {Scheme Procedure} procedure-properties proc
429 @deffnx {C Function} scm_procedure_properties (proc)
430 Return @var{obj}'s property list.
433 @deffn {Scheme Procedure} procedure-property obj key
434 @deffnx {C Function} scm_procedure_property (obj, key)
435 Return the property of @var{obj} with name @var{key}.
438 @deffn {Scheme Procedure} set-procedure-properties! proc alist
439 @deffnx {C Function} scm_set_procedure_properties_x (proc, alist)
440 Set @var{obj}'s property list to @var{alist}.
443 @deffn {Scheme Procedure} set-procedure-property! obj key value
444 @deffnx {C Function} scm_set_procedure_property_x (obj, key, value)
445 In @var{obj}'s property list, set the property named @var{key} to
449 @cindex procedure documentation
450 Documentation for a procedure can be accessed with the procedure
451 @code{procedure-documentation}.
453 @deffn {Scheme Procedure} procedure-documentation proc
454 @deffnx {C Function} scm_procedure_documentation (proc)
455 Return the documentation string associated with @code{proc}. By
456 convention, if a procedure contains more than one expression and the
457 first expression is a string constant, that string is assumed to contain
458 documentation for that procedure.
461 @cindex source properties
462 @c FIXME::martin: Is the following true?
463 Source properties are properties which are related to the source code of
464 a procedure, such as the line and column numbers, the file name etc.
466 @deffn {Scheme Procedure} set-source-properties! obj plist
467 @deffnx {C Function} scm_set_source_properties_x (obj, plist)
468 Install the association list @var{plist} as the source property
472 @deffn {Scheme Procedure} set-source-property! obj key datum
473 @deffnx {C Function} scm_set_source_property_x (obj, key, datum)
474 Set the source property of object @var{obj}, which is specified by
475 @var{key} to @var{datum}. Normally, the key will be a symbol.
478 @deffn {Scheme Procedure} source-properties obj
479 @deffnx {C Function} scm_source_properties (obj)
480 Return the source property association list of @var{obj}.
484 @deffn {Scheme Procedure} source-property obj key
485 @deffnx {C Function} scm_source_property (obj, key)
486 Return the source property specified by @var{key} from
487 @var{obj}'s source property list.
491 @node Procedures with Setters
492 @section Procedures with Setters
494 @c FIXME::martin: Review me!
496 @c FIXME::martin: Document `operator struct'.
498 @cindex procedure with setter
500 A @dfn{procedure with setter} is a special kind of procedure which
501 normally behaves like any accessor procedure, that is a procedure which
502 accesses a data structure. The difference is that this kind of
503 procedure has a so-called @dfn{setter} attached, which is a procedure
504 for storing something into a data structure.
506 Procedures with setters are treated specially when the procedure appears
507 in the special form @code{set!} (REFFIXME). How it works is best shown
510 Suppose we have a procedure called @code{foo-ref}, which accepts two
511 arguments, a value of type @code{foo} and an integer. The procedure
512 returns the value stored at the given index in the @code{foo} object.
513 Let @code{f} be a variable containing such a @code{foo} data
514 structure.@footnote{Working definitions would be:
516 (define foo-ref vector-ref)
517 (define foo-set! vector-set!)
518 (define f (make-vector 2 #f))
523 (foo-ref f 0) @result{} bar
524 (foo-ref f 1) @result{} braz
527 Also suppose that a corresponding setter procedure called
528 @code{foo-set!} does exist.
532 (foo-ref f 0) @result{} bla
535 Now we could create a new procedure called @code{foo}, which is a
536 procedure with setter, by calling @code{make-procedure-with-setter} with
537 the accessor and setter procedures @code{foo-ref} and @code{foo-set!}.
538 Let us call this new procedure @code{foo}.
541 (define foo (make-procedure-with-setter foo-ref foo-set!))
544 @code{foo} can from now an be used to either read from the data
545 structure stored in @code{f}, or to write into the structure.
548 (set! (foo f 0) 'dum)
549 (foo f 0) @result{} dum
552 @deffn {Scheme Procedure} make-procedure-with-setter procedure setter
553 @deffnx {C Function} scm_make_procedure_with_setter (procedure, setter)
554 Create a new procedure which behaves like @var{procedure}, but
555 with the associated setter @var{setter}.
558 @deffn {Scheme Procedure} procedure-with-setter? obj
559 @deffnx {C Function} scm_procedure_with_setter_p (obj)
560 Return @code{#t} if @var{obj} is a procedure with an
561 associated setter procedure.
564 @deffn {Scheme Procedure} procedure proc
565 @deffnx {C Function} scm_procedure (proc)
566 Return the procedure of @var{proc}, which must be either a
567 procedure with setter, or an operator struct.
570 @deffn {Scheme Procedure} setter proc
571 Return the setter of @var{proc}, which must be either a procedure with
572 setter or an operator struct.
577 @section Lisp Style Macro Definitions
580 @cindex transformation
581 Macros are objects which cause the expression that they appear in to be
582 transformed in some way @emph{before} being evaluated. In expressions
583 that are intended for macro transformation, the identifier that names
584 the relevant macro must appear as the first element, like this:
587 (@var{macro-name} @var{macro-args} @dots{})
590 In Lisp-like languages, the traditional way to define macros is very
591 similar to procedure definitions. The key differences are that the
592 macro definition body should return a list that describes the
593 transformed expression, and that the definition is marked as a macro
594 definition (rather than a procedure definition) by the use of a
595 different definition keyword: in Lisp, @code{defmacro} rather than
596 @code{defun}, and in Scheme, @code{define-macro} rather than
600 @fnindex define-macro
601 Guile supports this style of macro definition using both @code{defmacro}
602 and @code{define-macro}. The only difference between them is how the
603 macro name and arguments are grouped together in the definition:
606 (defmacro @var{name} (@var{args} @dots{}) @var{body} @dots{})
613 (define-macro (@var{name} @var{args} @dots{}) @var{body} @dots{})
617 The difference is analogous to the corresponding difference between
618 Lisp's @code{defun} and Scheme's @code{define}.
620 @code{false-if-exception}, from the @file{boot-9.scm} file in the Guile
621 distribution, is a good example of macro definition using
625 (defmacro false-if-exception (expr)
632 The effect of this definition is that expressions beginning with the
633 identifier @code{false-if-exception} are automatically transformed into
634 a @code{catch} expression following the macro definition specification.
638 (false-if-exception (open-input-file "may-not-exist"))
641 (lambda () (open-input-file "may-not-exist"))
647 @section The R5RS @code{syntax-rules} System
648 @cindex R5RS syntax-rules system
650 R5RS defines an alternative system for macro and syntax transformations
651 using the keywords @code{define-syntax}, @code{let-syntax},
652 @code{letrec-syntax} and @code{syntax-rules}.
654 The main difference between the R5RS system and the traditional macros
655 of the previous section is how the transformation is specified. In
656 R5RS, rather than permitting a macro definition to return an arbitrary
657 expression, the transformation is specified in a pattern language that
661 does not require complicated quoting and extraction of components of the
662 source expression using @code{caddr} etc.
665 is designed such that the bindings associated with identifiers in the
666 transformed expression are well defined, and such that it is impossible
667 for the transformed expression to construct new identifiers.
671 The last point is commonly referred to as being @dfn{hygienic}: the R5RS
672 @code{syntax-case} system provides @dfn{hygienic macros}.
674 For example, the R5RS pattern language for the @code{false-if-exception}
675 example of the previous section looks like this:
685 @cindex @code{syncase}
686 In Guile, the @code{syntax-rules} system is provided by the @code{(ice-9
687 syncase)} module. To make these facilities available in your code,
688 include the expression @code{(use-syntax (ice-9 syncase))} (@pxref{Using
689 Guile Modules}) before the first usage of @code{define-syntax} etc. If
690 you are writing a Scheme module, you can alternatively include the form
691 @code{#:use-syntax (ice-9 syncase)} in your @code{define-module}
692 declaration (@pxref{Creating Guile Modules}).
695 * Pattern Language:: The @code{syntax-rules} pattern language.
696 * Define-Syntax:: Top level syntax definitions.
697 * Let-Syntax:: Local syntax definitions.
701 @node Pattern Language
702 @subsection The @code{syntax-rules} Pattern Language
706 @subsection Top Level Syntax Definitions
708 define-syntax: The gist is
710 (define-syntax <keyword> <transformer-spec>)
712 makes the <keyword> into a macro so that
716 expands at _compile_ or _read_ time (i.e. before any
717 evaluation begins) into some expression that is
718 given by the <transformer-spec>.
722 @subsection Local Syntax Definitions
726 @section Support for the @code{syntax-case} System
730 @node Internal Macros
731 @section Internal Representation of Macros and Syntax
733 Internally, Guile uses three different flavors of macros. The three
734 flavors are called @dfn{acro} (or @dfn{syntax}), @dfn{macro} and
744 with @code{foo} being some flavor of macro, one of the following things
745 will happen when the expression is evaluated.
749 When @code{foo} has been defined to be an @dfn{acro}, the procedure used
750 in the acro definition of @code{foo} is passed the whole expression and
751 the current lexical environment, and whatever that procedure returns is
752 the value of evaluating the expression. You can think of this a
753 procedure that receives its argument as an unevaluated expression.
756 When @code{foo} has been defined to be a @dfn{macro}, the procedure used
757 in the macro definition of @code{foo} is passed the whole expression and
758 the current lexical environment, and whatever that procedure returns is
759 evaluated again. That is, the procedure should return a valid Scheme
763 When @code{foo} has been defined to be a @dfn{mmacro}, the procedure
764 used in the mmacro definition of `foo' is passed the whole expression
765 and the current lexical environment, and whatever that procedure returns
766 replaces the original expression. Evaluation then starts over from the
767 new expression that has just been returned.
770 The key difference between a @dfn{macro} and a @dfn{mmacro} is that the
771 expression returned by a @dfn{mmacro} procedure is remembered (or
772 @dfn{memoized}) so that the expansion does not need to be done again
773 next time the containing code is evaluated.
775 The primitives @code{procedure->syntax}, @code{procedure->macro} and
776 @code{procedure->memoizing-macro} are used to construct acros, macros
777 and mmacros respectively. However, if you do not have a very special
778 reason to use one of these primitives, you should avoid them: they are
779 very specific to Guile's current implementation and therefore likely to
780 change. Use @code{defmacro}, @code{define-macro} (@pxref{Macros}) or
781 @code{define-syntax} (@pxref{Syntax Rules}) instead. (In low level
782 terms, @code{defmacro}, @code{define-macro} and @code{define-syntax} are
783 all implemented as mmacros.)
785 @deffn {Scheme Procedure} procedure->syntax code
786 @deffnx {C Function} scm_makacro (code)
787 Return a macro which, when a symbol defined to this value appears as the
788 first symbol in an expression, returns the result of applying @var{code}
789 to the expression and the environment.
792 @deffn {Scheme Procedure} procedure->macro code
793 @deffnx {C Function} scm_makmacro (code)
794 Return a macro which, when a symbol defined to this value appears as the
795 first symbol in an expression, evaluates the result of applying
796 @var{code} to the expression and the environment. For example:
802 `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))
806 (set! @i{foo} (tracef @i{foo} '@i{foo})).
810 @deffn {Scheme Procedure} procedure->memoizing-macro code
811 @deffnx {C Function} scm_makmmacro (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.
815 @code{procedure->memoizing-macro} is the same as
816 @code{procedure->macro}, except that the expression returned by
817 @var{code} replaces the original macro expression in the memoized form
818 of the containing code.
821 In the following primitives, @dfn{acro} flavor macros are referred to
822 as @dfn{syntax transformers}.
824 @deffn {Scheme Procedure} macro? obj
825 @deffnx {C Function} scm_macro_p (obj)
826 Return @code{#t} if @var{obj} is a regular macro, a memoizing macro or a
830 @deffn {Scheme Procedure} macro-type m
831 @deffnx {C Function} scm_macro_type (m)
832 Return one of the symbols @code{syntax}, @code{macro} or
833 @code{macro!}, depending on whether @var{m} is a syntax
834 transformer, a regular macro, or a memoizing macro,
835 respectively. If @var{m} is not a macro, @code{#f} is
839 @deffn {Scheme Procedure} macro-name m
840 @deffnx {C Function} scm_macro_name (m)
841 Return the name of the macro @var{m}.
844 @deffn {Scheme Procedure} macro-transformer m
845 @deffnx {C Function} scm_macro_transformer (m)
846 Return the transformer of the macro @var{m}.
849 @deffn {Scheme Procedure} cons-source xorig x y
850 @deffnx {C Function} scm_cons_source (xorig, x, y)
851 Create and return a new pair whose car and cdr are @var{x} and @var{y}.
852 Any source properties associated with @var{xorig} are also associated
858 @c TeX-master: "guile.texi"