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 * Compiled Procedures:: Scheme procedures can be compiled.
15 * Optional Arguments:: Handling keyword, optional and rest arguments.
16 * Procedure Properties:: Procedure properties and meta-information.
17 * Procedures with Setters:: Procedures with setters.
18 * Macros:: Lisp style macro definitions.
19 * Syntax Rules:: Support for R5RS @code{syntax-rules}.
20 * Syntax Case:: Support for the @code{syntax-case} system.
21 * Internal Macros:: Guile's internal representation.
26 @subsection Lambda: Basic Procedure Creation
29 @c FIXME::martin: Review me!
31 A @code{lambda} expression evaluates to a procedure. The environment
32 which is in effect when a @code{lambda} expression is evaluated is
33 enclosed in the newly created procedure, this is referred to as a
34 @dfn{closure} (@pxref{About Closure}).
36 When a procedure created by @code{lambda} is called with some actual
37 arguments, the environment enclosed in the procedure is extended by
38 binding the variables named in the formal argument list to new locations
39 and storing the actual arguments into these locations. Then the body of
40 the @code{lambda} expression is evaluation sequentially. The result of
41 the last expression in the procedure body is then the result of the
44 The following examples will show how procedures can be created using
45 @code{lambda}, and what you can do with these procedures.
48 (lambda (x) (+ x x)) @result{} @r{a procedure}
49 ((lambda (x) (+ x x)) 4) @result{} 8
52 The fact that the environment in effect when creating a procedure is
53 enclosed in the procedure is shown with this example:
58 (lambda (y) (+ x y))))
63 @deffn syntax lambda formals body
64 @var{formals} should be a formal argument list as described in the
68 @item (@var{variable1} @dots{})
69 The procedure takes a fixed number of arguments; when the procedure is
70 called, the arguments will be stored into the newly created location for
73 The procedure takes any number of arguments; when the procedure is
74 called, the sequence of actual arguments will converted into a list and
75 stored into the newly created location for the formal variable.
76 @item (@var{variable1} @dots{} @var{variablen} . @var{variablen+1})
77 If a space-delimited period precedes the last variable, then the
78 procedure takes @var{n} or more variables where @var{n} is the number
79 of formal arguments before the period. There must be at least one
80 argument before the period. The first @var{n} actual arguments will be
81 stored into the newly allocated locations for the first @var{n} formal
82 arguments and the sequence of the remaining actual arguments is
83 converted into a list and the stored into the location for the last
84 formal argument. If there are exactly @var{n} actual arguments, the
85 empty list is stored into the location of the last formal argument.
88 The list in @var{variable} or @var{variablen+1} is always newly
89 created and the procedure can modify it if desired. This is the case
90 even when the procedure is invoked via @code{apply}, the required part
91 of the list argument there will be copied (@pxref{Fly Evaluation,,
92 Procedures for On the Fly Evaluation}).
94 @var{body} is a sequence of Scheme expressions which are evaluated in
95 order when the procedure is invoked.
98 @node Primitive Procedures
99 @subsection Primitive Procedures
101 @cindex primitive procedures
103 Procedures written in C can be registered for use from Scheme,
104 provided they take only arguments of type @code{SCM} and return
105 @code{SCM} values. @code{scm_c_define_gsubr} is likely to be the most
106 useful mechanism, combining the process of registration
107 (@code{scm_c_make_gsubr}) and definition (@code{scm_define}).
109 @deftypefun SCM scm_c_make_gsubr (const char *name, int req, int opt, int rst, fcn)
110 Register a C procedure @var{FCN} as a ``subr'' --- a primitive
111 subroutine that can be called from Scheme. It will be associated with
112 the given @var{name} but no environment binding will be created. The
113 arguments @var{req}, @var{opt} and @var{rst} specify the number of
114 required, optional and ``rest'' arguments respectively. The total
115 number of these arguments should match the actual number of arguments
116 to @var{fcn}. The number of rest arguments should be 0 or 1.
117 @code{scm_c_make_gsubr} returns a value of type @code{SCM} which is a
118 ``handle'' for the procedure.
121 @deftypefun SCM scm_c_define_gsubr (const char *name, int req, int opt, int rst, fcn)
122 Register a C procedure @var{FCN}, as for @code{scm_c_make_gsubr}
123 above, and additionally create a top-level Scheme binding for the
124 procedure in the ``current environment'' using @code{scm_define}.
125 @code{scm_c_define_gsubr} returns a handle for the procedure in the
126 same way as @code{scm_c_make_gsubr}, which is usually not further
130 @code{scm_c_make_gsubr} and @code{scm_c_define_gsubr} automatically
131 use @code{scm_c_make_subr} and also @code{scm_makcclo} if necessary.
132 It is advisable to use the gsubr variants since they provide a
133 slightly higher-level abstraction of the Guile implementation.
135 @node Compiled Procedures
136 @subsection Compiled Procedures
138 Procedures that were created when loading a compiled file are
139 themselves compiled. (In contrast, procedures that are defined by
140 loading a Scheme source file are interpreted, and often not as fast as
141 compiled procedures.)
143 Loading compiled files is the normal way that compiled procedures come
144 to being, though procedures can be compiled at runtime as well.
145 @xref{Read/Load/Eval/Compile}, for more information on runtime
148 Compiled procedures, also known as @dfn{programs}, respond all
149 procedures that operate on procedures. In addition, there are a few
150 more accessors for low-level details on programs.
152 Most people won't need to use the routines described in this section,
153 but it's good to have them documented. You'll have to include the
154 appropriate module first, though:
157 (use-modules (system vm program))
160 @deffn {Scheme Procedure} program? obj
161 @deffnx {C Function} scm_program_p (obj)
162 Returns @code{#t} iff @var{obj} is a compiled procedure.
165 @deffn {Scheme Procedure} program-bytecode program
166 @deffnx {C Function} scm_program_bytecode (program)
167 Returns the object code associated with this program, as a
171 @deffn {Scheme Procedure} program-base program
172 @deffnx {C Function} scm_program_base (program)
173 Returns the address in memory corresponding to the start of
174 @var{program}'s object code, as an integer. This is useful mostly when
175 you map the value of an instruction pointer from the VM to actual
179 @deffn {Scheme Procedure} program-objects program
180 @deffnx {C Function} scm_program_objects (program)
181 Returns the ``object table'' associated with this program, as a
182 vector. @xref{VM Programs}, for more information.
185 @deffn {Scheme Procedure} program-module program
186 @deffnx {C Function} scm_program_module (program)
187 Returns the module that was current when this program was created.
188 Free variables in this program are looked up with respect to this
192 @deffn {Scheme Procedure} program-external program
193 @deffnx {C Function} scm_program_external (program)
194 Returns the set of heap-allocated variables that this program captures
195 in its closure, as a list. If a closure is code with data, you can get
196 the code from @code{program-bytecode}, and the data via
197 @code{program-external}.
199 Users must not modify the returned value unless they think they're
203 @deffn {Scheme Procedure} program-external-set! program external
204 @deffnx {C Function} scm_program_external_set_x (program, external)
205 Set @var{external} as the set of closure variables on @var{program}.
207 The Guile maintainers will not be held responsible for side effects of
208 calling this function, including but not limited to replacement of
209 shampoo with hair dye, and a slight salty taste in tomorrow's dinner.
212 @deffn {Scheme Procedure} program-arity program
213 @deffnx {C Function} scm_program_arity (program)
214 @deffnx {Scheme Procedure} arity:nargs arity
215 @deffnx {Scheme Procedure} arity:nrest arity
216 @deffnx {Scheme Procedure} arity:nlocs arity
217 @deffnx {Scheme Procedure} arity:nexts arity
218 Accessors for a representation of the ``arity'' of a program.
220 @code{nargs} is the number of arguments to the procedure, and
221 @code{nrest} will be non-zero if the last argument is a rest argument.
223 The other two accessors determine the number of local and external
224 (heap-allocated) variables that this procedure will need to have
228 @deffn {Scheme Procedure} program-meta program
229 @deffnx scm_program_meta (program)
230 Return the metadata thunk of @var{program}, or @code{#f} if it has no
233 When called, a metadata thunk returns a list of the following form:
234 @code{(@var{bindings} @var{sources} . @var{properties})}. The format
235 of each of these elements is discussed below.
238 @deffn {Scheme Procedure} program-bindings program
239 @deffnx {Scheme Procedure} make-binding name extp index start end
240 @deffnx {Scheme Procedure} binding:name binding
241 @deffnx {Scheme Procedure} binding:extp binding
242 @deffnx {Scheme Procedure} binding:index binding
243 @deffnx {Scheme Procedure} binding:start binding
244 @deffnx {Scheme Procedure} binding:end binding
245 Bindings annotations for programs, along with their accessors.
247 Bindings declare names and liveness extents for block-local variables.
248 The best way to see what these are is to play around with them at a
249 REPL. The only tricky bit is that @var{extp} is a boolean, declaring
250 whether the binding is heap-allocated or not. @xref{VM Concepts}, for
253 Note that bindings information are stored in a program as part of its
254 metadata thunk, so including them in the generated object code does
255 not impose a runtime performance penalty.
258 @deffn {Scheme Procedure} program-sources program
259 @deffnx {Scheme Procedure} source:addr source
260 @deffnx {Scheme Procedure} source:line source
261 @deffnx {Scheme Procedure} source:column source
262 @deffnx {Scheme Procedure} source:file source
263 Source location annotations for programs, along with their accessors.
265 Source location information propagates through the compiler and ends
266 up being serialized to the program's metadata. This information is
267 keyed by the offset of the instruction pointer within the object code
268 of the program. Specifically, it is keyed on the @code{ip} @emph{just
269 following} an instruction, so that backtraces can find the source
270 location of a call that is in progress.
273 @deffn {Scheme Procedure} program-properties program
274 Return the properties of a @code{program} as an association list,
275 keyed by property name (a symbol).
277 Some interesting properties include:
279 @item @code{name}, the name of the procedure
280 @item @code{documentation}, the procedure's docstring
284 @deffn {Scheme Procedure} program-property program name
285 Access a program's property by name, returning @code{#f} if not found.
288 @deffn {Scheme Procedure} program-documentation program
289 @deffnx {Scheme Procedure} program-name program
290 Accessors for specific properties.
293 @node Optional Arguments
294 @subsection Optional Arguments
296 @c FIXME::martin: Review me!
298 Scheme procedures, as defined in R5RS, can either handle a fixed number
299 of actual arguments, or a fixed number of actual arguments followed by
300 arbitrarily many additional arguments. Writing procedures of variable
301 arity can be useful, but unfortunately, the syntactic means for handling
302 argument lists of varying length is a bit inconvenient. It is possible
303 to give names to the fixed number of argument, but the remaining
304 (optional) arguments can be only referenced as a list of values
307 Guile comes with the module @code{(ice-9 optargs)}, which makes using
308 optional arguments much more convenient. In addition, this module
309 provides syntax for handling keywords in argument lists
312 Before using any of the procedures or macros defined in this section,
313 you have to load the module @code{(ice-9 optargs)} with the statement:
315 @cindex @code{optargs}
317 (use-modules (ice-9 optargs))
321 * let-optional Reference:: Locally binding optional arguments.
322 * let-keywords Reference:: Locally binding keywords arguments.
323 * lambda* Reference:: Creating advanced argument handling procedures.
324 * define* Reference:: Defining procedures and macros.
328 @node let-optional Reference
329 @subsubsection let-optional Reference
331 @c FIXME::martin: Review me!
333 The syntax @code{let-optional} and @code{let-optional*} are for
334 destructuring rest argument lists and giving names to the various list
335 elements. @code{let-optional} binds all variables simultaneously, while
336 @code{let-optional*} binds them sequentially, consistent with @code{let}
337 and @code{let*} (@pxref{Local Bindings}).
339 @deffn {library syntax} let-optional rest-arg (binding @dots{}) expr @dots{}
340 @deffnx {library syntax} let-optional* rest-arg (binding @dots{}) expr @dots{}
341 These two macros give you an optional argument interface that is very
342 @dfn{Schemey} and introduces no fancy syntax. They are compatible with
343 the scsh macros of the same name, but are slightly extended. Each of
344 @var{binding} may be of one of the forms @var{var} or @code{(@var{var}
345 @var{default-value})}. @var{rest-arg} should be the rest-argument of the
346 procedures these are used from. The items in @var{rest-arg} are
347 sequentially bound to the variable names are given. When @var{rest-arg}
348 runs out, the remaining vars are bound either to the default values or
349 @code{#f} if no default value was specified. @var{rest-arg} remains
350 bound to whatever may have been left of @var{rest-arg}.
352 After binding the variables, the expressions @var{expr} @dots{} are
357 @node let-keywords Reference
358 @subsubsection let-keywords Reference
360 @code{let-keywords} and @code{let-keywords*} extract values from
361 keyword style argument lists, binding local variables to those values
364 @deffn {library syntax} let-keywords args allow-other-keys? (binding @dots{}) body @dots{}
365 @deffnx {library syntax} let-keywords* args allow-other-keys? (binding @dots{}) body @dots{}
366 @var{args} is evaluated and should give a list of the form
367 @code{(#:keyword1 value1 #:keyword2 value2 @dots{})}. The
368 @var{binding}s are variables and default expressions, with the
369 variables to be set (by name) from the keyword values. The @var{body}
370 forms are then evaluated and the last is the result. An example will
371 make the syntax clearest,
374 (define args '(#:xyzzy "hello" #:foo "world"))
376 (let-keywords args #t
377 ((foo "default for foo")
378 (bar (string-append "default" "for" "bar")))
382 @print{} world, defaultforbar
385 The binding for @code{foo} comes from the @code{#:foo} keyword in
386 @code{args}. But the binding for @code{bar} is the default in the
387 @code{let-keywords}, since there's no @code{#:bar} in the args.
389 @var{allow-other-keys?} is evaluated and controls whether unknown
390 keywords are allowed in the @var{args} list. When true other keys are
391 ignored (such as @code{#:xyzzy} in the example), when @code{#f} an
392 error is thrown for anything unknown.
394 @code{let-keywords} is like @code{let} (@pxref{Local Bindings}) in
395 that all bindings are made at once, the defaults expressions are
396 evaluated (if needed) outside the scope of the @code{let-keywords}.
398 @code{let-keywords*} is like @code{let*}, each binding is made
399 successively, and the default expressions see the bindings previously
400 made. This is the style used by @code{lambda*} keywords
401 (@pxref{lambda* Reference}). For example,
404 (define args '(#:foo 3))
406 (let-keywords* args #f
413 The expression for each default is only evaluated if it's needed,
414 ie. if the keyword doesn't appear in @var{args}. So one way to make a
415 keyword mandatory is to throw an error of some sort as the default.
418 (define args '(#:start 7 #:finish 13))
420 (let-keywords* args #t
422 (stop (error "missing #:stop argument")))
424 @result{} ERROR: missing #:stop argument
429 @node lambda* Reference
430 @subsubsection lambda* Reference
432 When using optional and keyword argument lists, @code{lambda} for
433 creating a procedure then @code{let-optional} or @code{let-keywords}
434 is a bit lengthy. @code{lambda*} combines the features of those
435 macros into a single convenient syntax.
437 @deffn {library syntax} lambda* ([var@dots{}] @* [#:optional vardef@dots{}] @* [#:key vardef@dots{} [#:allow-other-keys]] @* [#:rest var | . var]) @* body
439 Create a procedure which takes optional and/or keyword arguments
440 specified with @code{#:optional} and @code{#:key}. For example,
443 (lambda* (a b #:optional c d . e) '())
446 is a procedure with fixed arguments @var{a} and @var{b}, optional
447 arguments @var{c} and @var{d}, and rest argument @var{e}. If the
448 optional arguments are omitted in a call, the variables for them are
451 @code{lambda*} can also take keyword arguments. For example, a procedure
455 (lambda* (#:key xyzzy larch) '())
458 can be called with any of the argument lists @code{(#:xyzzy 11)},
459 @code{(#:larch 13)}, @code{(#:larch 42 #:xyzzy 19)}, @code{()}.
460 Whichever arguments are given as keywords are bound to values (and
461 those not given are @code{#f}).
463 Optional and keyword arguments can also have default values to take
464 when not present in a call, by giving a two-element list of variable
465 name and expression. For example in
468 (lambda* (foo #:optional (bar 42) #:key (baz 73))
472 @var{foo} is a fixed argument, @var{bar} is an optional argument with
473 default value 42, and baz is a keyword argument with default value 73.
474 Default value expressions are not evaluated unless they are needed,
475 and until the procedure is called.
477 Normally it's an error if a call has keywords other than those
478 specified by @code{#:key}, but adding @code{#:allow-other-keys} to the
479 definition (after the keyword argument declarations) will ignore
482 If a call has a keyword given twice, the last value is used. For
486 ((lambda* (#:key (heads 0) (tails 0))
487 (display (list heads tails)))
488 #:heads 37 #:tails 42 #:heads 99)
492 @code{#:rest} is a synonym for the dotted syntax rest argument. The
493 argument lists @code{(a . b)} and @code{(a #:rest b)} are equivalent
494 in all respects. This is provided for more similarity to DSSSL,
495 MIT-Scheme and Kawa among others, as well as for refugees from other
498 When @code{#:key} is used together with a rest argument, the keyword
499 parameters in a call all remain in the rest list. This is the same as
500 Common Lisp. For example,
503 ((lambda* (#:key (x 0) #:allow-other-keys #:rest r)
506 @print{} (#:x 123 #:y 456)
509 @code{#:optional} and @code{#:key} establish their bindings
510 successively, from left to right, as per @code{let-optional*} and
511 @code{let-keywords*}. This means default expressions can refer back
512 to prior parameters, for example
515 (lambda* (start #:optional (end (+ 10 start)))
516 (do ((i start (1+ i)))
523 @node define* Reference
524 @subsubsection define* Reference
526 @c FIXME::martin: Review me!
528 Just like @code{define} has a shorthand notation for defining procedures
529 (@pxref{Lambda Alternatives}), @code{define*} is provided as an
530 abbreviation of the combination of @code{define} and @code{lambda*}.
532 @code{define*-public} is the @code{lambda*} version of
533 @code{define-public}; @code{defmacro*} and @code{defmacro*-public} exist
534 for defining macros with the improved argument list handling
535 possibilities. The @code{-public} versions not only define the
536 procedures/macros, but also export them from the current module.
538 @deffn {library syntax} define* formals body
539 @deffnx {library syntax} define*-public formals body
540 @code{define*} and @code{define*-public} support optional arguments with
541 a similar syntax to @code{lambda*}. They also support arbitrary-depth
542 currying, just like Guile's define. Some examples:
545 (define* (x y #:optional a (z 3) #:key w . u)
546 (display (list y z u)))
548 defines a procedure @code{x} with a fixed argument @var{y}, an optional
549 argument @var{a}, another optional argument @var{z} with default value 3,
550 a keyword argument @var{w}, and a rest argument @var{u}.
553 (define-public* ((foo #:optional bar) #:optional baz) '())
556 This illustrates currying. A procedure @code{foo} is defined, which,
557 when called with an optional argument @var{bar}, returns a procedure
558 that takes an optional argument @var{baz}.
560 Of course, @code{define*[-public]} also supports @code{#:rest} and
561 @code{#:allow-other-keys} in the same way as @code{lambda*}.
564 @deffn {library syntax} defmacro* name formals body
565 @deffnx {library syntax} defmacro*-public name formals body
566 These are just like @code{defmacro} and @code{defmacro-public} except that they
567 take @code{lambda*}-style extended parameter lists, where @code{#:optional},
568 @code{#:key}, @code{#:allow-other-keys} and @code{#:rest} are allowed with the usual
569 semantics. Here is an example of a macro with an optional argument:
572 (defmacro* transmorgify (a #:optional b)
578 @node Procedure Properties
579 @subsection Procedure Properties and Meta-information
581 @c FIXME::martin: Review me!
583 Procedures always have attached the environment in which they were
584 created and information about how to apply them to actual arguments. In
585 addition to that, properties and meta-information can be stored with
586 procedures. The procedures in this section can be used to test whether
587 a given procedure satisfies a condition; and to access and set a
588 procedure's property.
590 The first group of procedures are predicates to test whether a Scheme
591 object is a procedure, or a special procedure, respectively.
592 @code{procedure?} is the most general predicates, it returns @code{#t}
593 for any kind of procedure. @code{closure?} does not return @code{#t}
594 for primitive procedures, and @code{thunk?} only returns @code{#t} for
595 procedures which do not accept any arguments.
598 @deffn {Scheme Procedure} procedure? obj
599 @deffnx {C Function} scm_procedure_p (obj)
600 Return @code{#t} if @var{obj} is a procedure.
603 @deffn {Scheme Procedure} closure? obj
604 @deffnx {C Function} scm_closure_p (obj)
605 Return @code{#t} if @var{obj} is a closure.
608 @deffn {Scheme Procedure} thunk? obj
609 @deffnx {C Function} scm_thunk_p (obj)
610 Return @code{#t} if @var{obj} is a thunk.
613 @c FIXME::martin: Is that true?
614 @cindex procedure properties
615 Procedure properties are general properties to be attached to
616 procedures. These can be the name of a procedure or other relevant
617 information, such as debug hints.
619 @deffn {Scheme Procedure} procedure-name proc
620 @deffnx {C Function} scm_procedure_name (proc)
621 Return the name of the procedure @var{proc}
624 @deffn {Scheme Procedure} procedure-source proc
625 @deffnx {C Function} scm_procedure_source (proc)
626 Return the source of the procedure @var{proc}.
629 @deffn {Scheme Procedure} procedure-environment proc
630 @deffnx {C Function} scm_procedure_environment (proc)
631 Return the environment of the procedure @var{proc}.
634 @deffn {Scheme Procedure} procedure-properties proc
635 @deffnx {C Function} scm_procedure_properties (proc)
636 Return @var{obj}'s property list.
639 @deffn {Scheme Procedure} procedure-property obj key
640 @deffnx {C Function} scm_procedure_property (obj, key)
641 Return the property of @var{obj} with name @var{key}.
644 @deffn {Scheme Procedure} set-procedure-properties! proc alist
645 @deffnx {C Function} scm_set_procedure_properties_x (proc, alist)
646 Set @var{obj}'s property list to @var{alist}.
649 @deffn {Scheme Procedure} set-procedure-property! obj key value
650 @deffnx {C Function} scm_set_procedure_property_x (obj, key, value)
651 In @var{obj}'s property list, set the property named @var{key} to
655 @cindex procedure documentation
656 Documentation for a procedure can be accessed with the procedure
657 @code{procedure-documentation}.
659 @deffn {Scheme Procedure} procedure-documentation proc
660 @deffnx {C Function} scm_procedure_documentation (proc)
661 Return the documentation string associated with @code{proc}. By
662 convention, if a procedure contains more than one expression and the
663 first expression is a string constant, that string is assumed to contain
664 documentation for that procedure.
668 @node Procedures with Setters
669 @subsection Procedures with Setters
671 @c FIXME::martin: Review me!
673 @c FIXME::martin: Document `operator struct'.
675 @cindex procedure with setter
677 A @dfn{procedure with setter} is a special kind of procedure which
678 normally behaves like any accessor procedure, that is a procedure which
679 accesses a data structure. The difference is that this kind of
680 procedure has a so-called @dfn{setter} attached, which is a procedure
681 for storing something into a data structure.
683 Procedures with setters are treated specially when the procedure appears
684 in the special form @code{set!} (REFFIXME). How it works is best shown
687 Suppose we have a procedure called @code{foo-ref}, which accepts two
688 arguments, a value of type @code{foo} and an integer. The procedure
689 returns the value stored at the given index in the @code{foo} object.
690 Let @code{f} be a variable containing such a @code{foo} data
691 structure.@footnote{Working definitions would be:
693 (define foo-ref vector-ref)
694 (define foo-set! vector-set!)
695 (define f (make-vector 2 #f))
700 (foo-ref f 0) @result{} bar
701 (foo-ref f 1) @result{} braz
704 Also suppose that a corresponding setter procedure called
705 @code{foo-set!} does exist.
709 (foo-ref f 0) @result{} bla
712 Now we could create a new procedure called @code{foo}, which is a
713 procedure with setter, by calling @code{make-procedure-with-setter} with
714 the accessor and setter procedures @code{foo-ref} and @code{foo-set!}.
715 Let us call this new procedure @code{foo}.
718 (define foo (make-procedure-with-setter foo-ref foo-set!))
721 @code{foo} can from now an be used to either read from the data
722 structure stored in @code{f}, or to write into the structure.
725 (set! (foo f 0) 'dum)
726 (foo f 0) @result{} dum
729 @deffn {Scheme Procedure} make-procedure-with-setter procedure setter
730 @deffnx {C Function} scm_make_procedure_with_setter (procedure, setter)
731 Create a new procedure which behaves like @var{procedure}, but
732 with the associated setter @var{setter}.
735 @deffn {Scheme Procedure} procedure-with-setter? obj
736 @deffnx {C Function} scm_procedure_with_setter_p (obj)
737 Return @code{#t} if @var{obj} is a procedure with an
738 associated setter procedure.
741 @deffn {Scheme Procedure} procedure proc
742 @deffnx {C Function} scm_procedure (proc)
743 Return the procedure of @var{proc}, which must be either a
744 procedure with setter, or an operator struct.
747 @deffn {Scheme Procedure} setter proc
748 Return the setter of @var{proc}, which must be either a procedure with
749 setter or an operator struct.
754 @subsection Lisp Style Macro Definitions
757 @cindex transformation
758 Macros are objects which cause the expression that they appear in to be
759 transformed in some way @emph{before} being evaluated. In expressions
760 that are intended for macro transformation, the identifier that names
761 the relevant macro must appear as the first element, like this:
764 (@var{macro-name} @var{macro-args} @dots{})
767 In Lisp-like languages, the traditional way to define macros is very
768 similar to procedure definitions. The key differences are that the
769 macro definition body should return a list that describes the
770 transformed expression, and that the definition is marked as a macro
771 definition (rather than a procedure definition) by the use of a
772 different definition keyword: in Lisp, @code{defmacro} rather than
773 @code{defun}, and in Scheme, @code{define-macro} rather than
777 @fnindex define-macro
778 Guile supports this style of macro definition using both @code{defmacro}
779 and @code{define-macro}. The only difference between them is how the
780 macro name and arguments are grouped together in the definition:
783 (defmacro @var{name} (@var{args} @dots{}) @var{body} @dots{})
790 (define-macro (@var{name} @var{args} @dots{}) @var{body} @dots{})
794 The difference is analogous to the corresponding difference between
795 Lisp's @code{defun} and Scheme's @code{define}.
797 @code{false-if-exception}, from the @file{boot-9.scm} file in the Guile
798 distribution, is a good example of macro definition using
802 (defmacro false-if-exception (expr)
809 The effect of this definition is that expressions beginning with the
810 identifier @code{false-if-exception} are automatically transformed into
811 a @code{catch} expression following the macro definition specification.
815 (false-if-exception (open-input-file "may-not-exist"))
818 (lambda () (open-input-file "may-not-exist"))
824 @subsection The R5RS @code{syntax-rules} System
825 @cindex R5RS syntax-rules system
827 R5RS defines an alternative system for macro and syntax transformations
828 using the keywords @code{define-syntax}, @code{let-syntax},
829 @code{letrec-syntax} and @code{syntax-rules}.
831 The main difference between the R5RS system and the traditional macros
832 of the previous section is how the transformation is specified. In
833 R5RS, rather than permitting a macro definition to return an arbitrary
834 expression, the transformation is specified in a pattern language that
838 does not require complicated quoting and extraction of components of the
839 source expression using @code{caddr} etc.
842 is designed such that the bindings associated with identifiers in the
843 transformed expression are well defined, and such that it is impossible
844 for the transformed expression to construct new identifiers.
848 The last point is commonly referred to as being @dfn{hygienic}: the R5RS
849 @code{syntax-case} system provides @dfn{hygienic macros}.
851 For example, the R5RS pattern language for the @code{false-if-exception}
852 example of the previous section looks like this:
862 @cindex @code{syncase}
863 In Guile, the @code{syntax-rules} system is provided by the @code{(ice-9
864 syncase)} module. To make these facilities available in your code,
865 include the expression @code{(use-syntax (ice-9 syncase))} (@pxref{Using
866 Guile Modules}) before the first usage of @code{define-syntax} etc. If
867 you are writing a Scheme module, you can alternatively include the form
868 @code{#:use-syntax (ice-9 syncase)} in your @code{define-module}
869 declaration (@pxref{Creating Guile Modules}).
872 * Pattern Language:: The @code{syntax-rules} pattern language.
873 * Define-Syntax:: Top level syntax definitions.
874 * Let-Syntax:: Local syntax definitions.
878 @node Pattern Language
879 @subsubsection The @code{syntax-rules} Pattern Language
883 @subsubsection Top Level Syntax Definitions
885 define-syntax: The gist is
887 (define-syntax <keyword> <transformer-spec>)
889 makes the <keyword> into a macro so that
893 expands at _compile_ or _read_ time (i.e. before any
894 evaluation begins) into some expression that is
895 given by the <transformer-spec>.
899 @subsubsection Local Syntax Definitions
903 @subsection Support for the @code{syntax-case} System
907 @node Internal Macros
908 @subsection Internal Representation of Macros and Syntax
910 Internally, Guile uses three different flavors of macros. The three
911 flavors are called @dfn{acro} (or @dfn{syntax}), @dfn{macro} and
921 with @code{foo} being some flavor of macro, one of the following things
922 will happen when the expression is evaluated.
926 When @code{foo} has been defined to be an @dfn{acro}, the procedure used
927 in the acro definition of @code{foo} is passed the whole expression and
928 the current lexical environment, and whatever that procedure returns is
929 the value of evaluating the expression. You can think of this a
930 procedure that receives its argument as an unevaluated expression.
933 When @code{foo} has been defined to be a @dfn{macro}, the procedure used
934 in the macro definition of @code{foo} is passed the whole expression and
935 the current lexical environment, and whatever that procedure returns is
936 evaluated again. That is, the procedure should return a valid Scheme
940 When @code{foo} has been defined to be a @dfn{mmacro}, the procedure
941 used in the mmacro definition of `foo' is passed the whole expression
942 and the current lexical environment, and whatever that procedure returns
943 replaces the original expression. Evaluation then starts over from the
944 new expression that has just been returned.
947 The key difference between a @dfn{macro} and a @dfn{mmacro} is that the
948 expression returned by a @dfn{mmacro} procedure is remembered (or
949 @dfn{memoized}) so that the expansion does not need to be done again
950 next time the containing code is evaluated.
952 The primitives @code{procedure->syntax}, @code{procedure->macro} and
953 @code{procedure->memoizing-macro} are used to construct acros, macros
954 and mmacros respectively. However, if you do not have a very special
955 reason to use one of these primitives, you should avoid them: they are
956 very specific to Guile's current implementation and therefore likely to
957 change. Use @code{defmacro}, @code{define-macro} (@pxref{Macros}) or
958 @code{define-syntax} (@pxref{Syntax Rules}) instead. (In low level
959 terms, @code{defmacro}, @code{define-macro} and @code{define-syntax} are
960 all implemented as mmacros.)
962 @deffn {Scheme Procedure} procedure->syntax code
963 @deffnx {C Function} scm_makacro (code)
964 Return a macro which, when a symbol defined to this value appears as the
965 first symbol in an expression, returns the result of applying @var{code}
966 to the expression and the environment.
969 @deffn {Scheme Procedure} procedure->macro code
970 @deffnx {C Function} scm_makmacro (code)
971 Return a macro which, when a symbol defined to this value appears as the
972 first symbol in an expression, evaluates the result of applying
973 @var{code} to the expression and the environment. For example:
979 `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))
983 (set! @i{foo} (tracef @i{foo} '@i{foo})).
987 @deffn {Scheme Procedure} procedure->memoizing-macro code
988 @deffnx {C Function} scm_makmmacro (code)
989 Return a macro which, when a symbol defined to this value appears as the
990 first symbol in an expression, evaluates the result of applying
991 @var{code} to the expression and the environment.
992 @code{procedure->memoizing-macro} is the same as
993 @code{procedure->macro}, except that the expression returned by
994 @var{code} replaces the original macro expression in the memoized form
995 of the containing code.
998 In the following primitives, @dfn{acro} flavor macros are referred to
999 as @dfn{syntax transformers}.
1001 @deffn {Scheme Procedure} macro? obj
1002 @deffnx {C Function} scm_macro_p (obj)
1003 Return @code{#t} if @var{obj} is a regular macro, a memoizing macro or a
1007 @deffn {Scheme Procedure} macro-type m
1008 @deffnx {C Function} scm_macro_type (m)
1009 Return one of the symbols @code{syntax}, @code{macro} or
1010 @code{macro!}, depending on whether @var{m} is a syntax
1011 transformer, a regular macro, or a memoizing macro,
1012 respectively. If @var{m} is not a macro, @code{#f} is
1016 @deffn {Scheme Procedure} macro-name m
1017 @deffnx {C Function} scm_macro_name (m)
1018 Return the name of the macro @var{m}.
1021 @deffn {Scheme Procedure} macro-transformer m
1022 @deffnx {C Function} scm_macro_transformer (m)
1023 Return the transformer of the macro @var{m}.
1026 @deffn {Scheme Procedure} cons-source xorig x y
1027 @deffnx {C Function} scm_cons_source (xorig, x, y)
1028 Create and return a new pair whose car and cdr are @var{x} and @var{y}.
1029 Any source properties associated with @var{xorig} are also associated
1035 @c TeX-master: "guile.texi"