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-objcode program
166 @deffnx {C Function} scm_program_objcode (program)
167 Returns the object code associated with this program. @xref{Bytecode
168 and Objcode}, for more information.
171 @deffn {Scheme Procedure} program-objects program
172 @deffnx {C Function} scm_program_objects (program)
173 Returns the ``object table'' associated with this program, as a
174 vector. @xref{VM Programs}, for more information.
177 @deffn {Scheme Procedure} program-module program
178 @deffnx {C Function} scm_program_module (program)
179 Returns the module that was current when this program was created. Can
180 return @code{#f} if the compiler could determine that this information
184 @deffn {Scheme Procedure} program-external program
185 @deffnx {C Function} scm_program_external (program)
186 Returns the set of heap-allocated variables that this program captures
187 in its closure, as a list. If a closure is code with data, you can get
188 the code from @code{program-bytecode}, and the data via
189 @code{program-external}.
191 Users must not modify the returned value unless they think they're
195 @deffn {Scheme Procedure} program-external-set! program external
196 @deffnx {C Function} scm_program_external_set_x (program, external)
197 Set @var{external} as the set of closure variables on @var{program}.
199 The Guile maintainers will not be held responsible for side effects of
200 calling this function, including but not limited to replacement of
201 shampoo with hair dye, and a slight salty taste in tomorrow's dinner.
204 @deffn {Scheme Procedure} program-arity program
205 @deffnx {C Function} scm_program_arity (program)
206 @deffnx {Scheme Procedure} arity:nargs arity
207 @deffnx {Scheme Procedure} arity:nrest arity
208 @deffnx {Scheme Procedure} arity:nlocs arity
209 @deffnx {Scheme Procedure} arity:nexts arity
210 Accessors for a representation of the ``arity'' of a program.
212 @code{nargs} is the number of arguments to the procedure, and
213 @code{nrest} will be non-zero if the last argument is a rest argument.
215 The other two accessors determine the number of local and external
216 (heap-allocated) variables that this procedure will need to have
220 @deffn {Scheme Procedure} program-meta program
221 @deffnx scm_program_meta (program)
222 Return the metadata thunk of @var{program}, or @code{#f} if it has no
225 When called, a metadata thunk returns a list of the following form:
226 @code{(@var{bindings} @var{sources} . @var{properties})}. The format
227 of each of these elements is discussed below.
230 @deffn {Scheme Procedure} program-bindings program
231 @deffnx {Scheme Procedure} make-binding name extp index start end
232 @deffnx {Scheme Procedure} binding:name binding
233 @deffnx {Scheme Procedure} binding:extp binding
234 @deffnx {Scheme Procedure} binding:index binding
235 @deffnx {Scheme Procedure} binding:start binding
236 @deffnx {Scheme Procedure} binding:end binding
237 Bindings annotations for programs, along with their accessors.
239 Bindings declare names and liveness extents for block-local variables.
240 The best way to see what these are is to play around with them at a
241 REPL. The only tricky bit is that @var{extp} is a boolean, declaring
242 whether the binding is heap-allocated or not. @xref{VM Concepts}, for
245 Note that bindings information is stored in a program as part of its
246 metadata thunk, so including it in the generated object code does not
247 impose a runtime performance penalty.
250 @deffn {Scheme Procedure} program-sources program
251 @deffnx {Scheme Procedure} source:addr source
252 @deffnx {Scheme Procedure} source:line source
253 @deffnx {Scheme Procedure} source:column source
254 @deffnx {Scheme Procedure} source:file source
255 Source location annotations for programs, along with their accessors.
257 Source location information propagates through the compiler and ends
258 up being serialized to the program's metadata. This information is
259 keyed by the offset of the instruction pointer within the object code
260 of the program. Specifically, it is keyed on the @code{ip} @emph{just
261 following} an instruction, so that backtraces can find the source
262 location of a call that is in progress.
265 @deffn {Scheme Procedure} program-properties program
266 Return the properties of a @code{program} as an association list,
267 keyed by property name (a symbol).
269 Some interesting properties include:
271 @item @code{name}, the name of the procedure
272 @item @code{documentation}, the procedure's docstring
276 @deffn {Scheme Procedure} program-property program name
277 Access a program's property by name, returning @code{#f} if not found.
280 @deffn {Scheme Procedure} program-documentation program
281 @deffnx {Scheme Procedure} program-name program
282 Accessors for specific properties.
285 @node Optional Arguments
286 @subsection Optional Arguments
288 @c FIXME::martin: Review me!
290 Scheme procedures, as defined in R5RS, can either handle a fixed number
291 of actual arguments, or a fixed number of actual arguments followed by
292 arbitrarily many additional arguments. Writing procedures of variable
293 arity can be useful, but unfortunately, the syntactic means for handling
294 argument lists of varying length is a bit inconvenient. It is possible
295 to give names to the fixed number of argument, but the remaining
296 (optional) arguments can be only referenced as a list of values
299 Guile comes with the module @code{(ice-9 optargs)}, which makes using
300 optional arguments much more convenient. In addition, this module
301 provides syntax for handling keywords in argument lists
304 Before using any of the procedures or macros defined in this section,
305 you have to load the module @code{(ice-9 optargs)} with the statement:
307 @cindex @code{optargs}
309 (use-modules (ice-9 optargs))
313 * let-optional Reference:: Locally binding optional arguments.
314 * let-keywords Reference:: Locally binding keywords arguments.
315 * lambda* Reference:: Creating advanced argument handling procedures.
316 * define* Reference:: Defining procedures and macros.
320 @node let-optional Reference
321 @subsubsection let-optional Reference
323 @c FIXME::martin: Review me!
325 The syntax @code{let-optional} and @code{let-optional*} are for
326 destructuring rest argument lists and giving names to the various list
327 elements. @code{let-optional} binds all variables simultaneously, while
328 @code{let-optional*} binds them sequentially, consistent with @code{let}
329 and @code{let*} (@pxref{Local Bindings}).
331 @deffn {library syntax} let-optional rest-arg (binding @dots{}) expr @dots{}
332 @deffnx {library syntax} let-optional* rest-arg (binding @dots{}) expr @dots{}
333 These two macros give you an optional argument interface that is very
334 @dfn{Schemey} and introduces no fancy syntax. They are compatible with
335 the scsh macros of the same name, but are slightly extended. Each of
336 @var{binding} may be of one of the forms @var{var} or @code{(@var{var}
337 @var{default-value})}. @var{rest-arg} should be the rest-argument of the
338 procedures these are used from. The items in @var{rest-arg} are
339 sequentially bound to the variable names are given. When @var{rest-arg}
340 runs out, the remaining vars are bound either to the default values or
341 @code{#f} if no default value was specified. @var{rest-arg} remains
342 bound to whatever may have been left of @var{rest-arg}.
344 After binding the variables, the expressions @var{expr} @dots{} are
349 @node let-keywords Reference
350 @subsubsection let-keywords Reference
352 @code{let-keywords} and @code{let-keywords*} extract values from
353 keyword style argument lists, binding local variables to those values
356 @deffn {library syntax} let-keywords args allow-other-keys? (binding @dots{}) body @dots{}
357 @deffnx {library syntax} let-keywords* args allow-other-keys? (binding @dots{}) body @dots{}
358 @var{args} is evaluated and should give a list of the form
359 @code{(#:keyword1 value1 #:keyword2 value2 @dots{})}. The
360 @var{binding}s are variables and default expressions, with the
361 variables to be set (by name) from the keyword values. The @var{body}
362 forms are then evaluated and the last is the result. An example will
363 make the syntax clearest,
366 (define args '(#:xyzzy "hello" #:foo "world"))
368 (let-keywords args #t
369 ((foo "default for foo")
370 (bar (string-append "default" "for" "bar")))
374 @print{} world, defaultforbar
377 The binding for @code{foo} comes from the @code{#:foo} keyword in
378 @code{args}. But the binding for @code{bar} is the default in the
379 @code{let-keywords}, since there's no @code{#:bar} in the args.
381 @var{allow-other-keys?} is evaluated and controls whether unknown
382 keywords are allowed in the @var{args} list. When true other keys are
383 ignored (such as @code{#:xyzzy} in the example), when @code{#f} an
384 error is thrown for anything unknown.
386 @code{let-keywords} is like @code{let} (@pxref{Local Bindings}) in
387 that all bindings are made at once, the defaults expressions are
388 evaluated (if needed) outside the scope of the @code{let-keywords}.
390 @code{let-keywords*} is like @code{let*}, each binding is made
391 successively, and the default expressions see the bindings previously
392 made. This is the style used by @code{lambda*} keywords
393 (@pxref{lambda* Reference}). For example,
396 (define args '(#:foo 3))
398 (let-keywords* args #f
405 The expression for each default is only evaluated if it's needed,
406 ie. if the keyword doesn't appear in @var{args}. So one way to make a
407 keyword mandatory is to throw an error of some sort as the default.
410 (define args '(#:start 7 #:finish 13))
412 (let-keywords* args #t
414 (stop (error "missing #:stop argument")))
416 @result{} ERROR: missing #:stop argument
421 @node lambda* Reference
422 @subsubsection lambda* Reference
424 When using optional and keyword argument lists, @code{lambda} for
425 creating a procedure then @code{let-optional} or @code{let-keywords}
426 is a bit lengthy. @code{lambda*} combines the features of those
427 macros into a single convenient syntax.
429 @deffn {library syntax} lambda* ([var@dots{}] @* [#:optional vardef@dots{}] @* [#:key vardef@dots{} [#:allow-other-keys]] @* [#:rest var | . var]) @* body
431 Create a procedure which takes optional and/or keyword arguments
432 specified with @code{#:optional} and @code{#:key}. For example,
435 (lambda* (a b #:optional c d . e) '())
438 is a procedure with fixed arguments @var{a} and @var{b}, optional
439 arguments @var{c} and @var{d}, and rest argument @var{e}. If the
440 optional arguments are omitted in a call, the variables for them are
443 @code{lambda*} can also take keyword arguments. For example, a procedure
447 (lambda* (#:key xyzzy larch) '())
450 can be called with any of the argument lists @code{(#:xyzzy 11)},
451 @code{(#:larch 13)}, @code{(#:larch 42 #:xyzzy 19)}, @code{()}.
452 Whichever arguments are given as keywords are bound to values (and
453 those not given are @code{#f}).
455 Optional and keyword arguments can also have default values to take
456 when not present in a call, by giving a two-element list of variable
457 name and expression. For example in
460 (lambda* (foo #:optional (bar 42) #:key (baz 73))
464 @var{foo} is a fixed argument, @var{bar} is an optional argument with
465 default value 42, and baz is a keyword argument with default value 73.
466 Default value expressions are not evaluated unless they are needed,
467 and until the procedure is called.
469 Normally it's an error if a call has keywords other than those
470 specified by @code{#:key}, but adding @code{#:allow-other-keys} to the
471 definition (after the keyword argument declarations) will ignore
474 If a call has a keyword given twice, the last value is used. For
478 ((lambda* (#:key (heads 0) (tails 0))
479 (display (list heads tails)))
480 #:heads 37 #:tails 42 #:heads 99)
484 @code{#:rest} is a synonym for the dotted syntax rest argument. The
485 argument lists @code{(a . b)} and @code{(a #:rest b)} are equivalent
486 in all respects. This is provided for more similarity to DSSSL,
487 MIT-Scheme and Kawa among others, as well as for refugees from other
490 When @code{#:key} is used together with a rest argument, the keyword
491 parameters in a call all remain in the rest list. This is the same as
492 Common Lisp. For example,
495 ((lambda* (#:key (x 0) #:allow-other-keys #:rest r)
498 @print{} (#:x 123 #:y 456)
501 @code{#:optional} and @code{#:key} establish their bindings
502 successively, from left to right, as per @code{let-optional*} and
503 @code{let-keywords*}. This means default expressions can refer back
504 to prior parameters, for example
507 (lambda* (start #:optional (end (+ 10 start)))
508 (do ((i start (1+ i)))
515 @node define* Reference
516 @subsubsection define* Reference
518 @c FIXME::martin: Review me!
520 Just like @code{define} has a shorthand notation for defining procedures
521 (@pxref{Lambda Alternatives}), @code{define*} is provided as an
522 abbreviation of the combination of @code{define} and @code{lambda*}.
524 @code{define*-public} is the @code{lambda*} version of
525 @code{define-public}; @code{defmacro*} and @code{defmacro*-public} exist
526 for defining macros with the improved argument list handling
527 possibilities. The @code{-public} versions not only define the
528 procedures/macros, but also export them from the current module.
530 @deffn {library syntax} define* formals body
531 @deffnx {library syntax} define*-public formals body
532 @code{define*} and @code{define*-public} support optional arguments with
533 a similar syntax to @code{lambda*}. They also support arbitrary-depth
534 currying, just like Guile's define. Some examples:
537 (define* (x y #:optional a (z 3) #:key w . u)
538 (display (list y z u)))
540 defines a procedure @code{x} with a fixed argument @var{y}, an optional
541 argument @var{a}, another optional argument @var{z} with default value 3,
542 a keyword argument @var{w}, and a rest argument @var{u}.
545 (define-public* ((foo #:optional bar) #:optional baz) '())
548 This illustrates currying. A procedure @code{foo} is defined, which,
549 when called with an optional argument @var{bar}, returns a procedure
550 that takes an optional argument @var{baz}.
552 Of course, @code{define*[-public]} also supports @code{#:rest} and
553 @code{#:allow-other-keys} in the same way as @code{lambda*}.
556 @deffn {library syntax} defmacro* name formals body
557 @deffnx {library syntax} defmacro*-public name formals body
558 These are just like @code{defmacro} and @code{defmacro-public} except that they
559 take @code{lambda*}-style extended parameter lists, where @code{#:optional},
560 @code{#:key}, @code{#:allow-other-keys} and @code{#:rest} are allowed with the usual
561 semantics. Here is an example of a macro with an optional argument:
564 (defmacro* transmorgify (a #:optional b)
570 @node Procedure Properties
571 @subsection Procedure Properties and Meta-information
573 @c FIXME::martin: Review me!
575 Procedures always have attached the environment in which they were
576 created and information about how to apply them to actual arguments. In
577 addition to that, properties and meta-information can be stored with
578 procedures. The procedures in this section can be used to test whether
579 a given procedure satisfies a condition; and to access and set a
580 procedure's property.
582 The first group of procedures are predicates to test whether a Scheme
583 object is a procedure, or a special procedure, respectively.
584 @code{procedure?} is the most general predicates, it returns @code{#t}
585 for any kind of procedure. @code{closure?} does not return @code{#t}
586 for primitive procedures, and @code{thunk?} only returns @code{#t} for
587 procedures which do not accept any arguments.
590 @deffn {Scheme Procedure} procedure? obj
591 @deffnx {C Function} scm_procedure_p (obj)
592 Return @code{#t} if @var{obj} is a procedure.
595 @deffn {Scheme Procedure} closure? obj
596 @deffnx {C Function} scm_closure_p (obj)
597 Return @code{#t} if @var{obj} is a closure.
600 @deffn {Scheme Procedure} thunk? obj
601 @deffnx {C Function} scm_thunk_p (obj)
602 Return @code{#t} if @var{obj} is a thunk.
605 @c FIXME::martin: Is that true?
606 @cindex procedure properties
607 Procedure properties are general properties to be attached to
608 procedures. These can be the name of a procedure or other relevant
609 information, such as debug hints.
611 @deffn {Scheme Procedure} procedure-name proc
612 @deffnx {C Function} scm_procedure_name (proc)
613 Return the name of the procedure @var{proc}
616 @deffn {Scheme Procedure} procedure-source proc
617 @deffnx {C Function} scm_procedure_source (proc)
618 Return the source of the procedure @var{proc}.
621 @deffn {Scheme Procedure} procedure-environment proc
622 @deffnx {C Function} scm_procedure_environment (proc)
623 Return the environment of the procedure @var{proc}.
626 @deffn {Scheme Procedure} procedure-properties proc
627 @deffnx {C Function} scm_procedure_properties (proc)
628 Return @var{obj}'s property list.
631 @deffn {Scheme Procedure} procedure-property obj key
632 @deffnx {C Function} scm_procedure_property (obj, key)
633 Return the property of @var{obj} with name @var{key}.
636 @deffn {Scheme Procedure} set-procedure-properties! proc alist
637 @deffnx {C Function} scm_set_procedure_properties_x (proc, alist)
638 Set @var{obj}'s property list to @var{alist}.
641 @deffn {Scheme Procedure} set-procedure-property! obj key value
642 @deffnx {C Function} scm_set_procedure_property_x (obj, key, value)
643 In @var{obj}'s property list, set the property named @var{key} to
647 @cindex procedure documentation
648 Documentation for a procedure can be accessed with the procedure
649 @code{procedure-documentation}.
651 @deffn {Scheme Procedure} procedure-documentation proc
652 @deffnx {C Function} scm_procedure_documentation (proc)
653 Return the documentation string associated with @code{proc}. By
654 convention, if a procedure contains more than one expression and the
655 first expression is a string constant, that string is assumed to contain
656 documentation for that procedure.
660 @node Procedures with Setters
661 @subsection Procedures with Setters
663 @c FIXME::martin: Review me!
665 @c FIXME::martin: Document `operator struct'.
667 @cindex procedure with setter
669 A @dfn{procedure with setter} is a special kind of procedure which
670 normally behaves like any accessor procedure, that is a procedure which
671 accesses a data structure. The difference is that this kind of
672 procedure has a so-called @dfn{setter} attached, which is a procedure
673 for storing something into a data structure.
675 Procedures with setters are treated specially when the procedure appears
676 in the special form @code{set!} (REFFIXME). How it works is best shown
679 Suppose we have a procedure called @code{foo-ref}, which accepts two
680 arguments, a value of type @code{foo} and an integer. The procedure
681 returns the value stored at the given index in the @code{foo} object.
682 Let @code{f} be a variable containing such a @code{foo} data
683 structure.@footnote{Working definitions would be:
685 (define foo-ref vector-ref)
686 (define foo-set! vector-set!)
687 (define f (make-vector 2 #f))
692 (foo-ref f 0) @result{} bar
693 (foo-ref f 1) @result{} braz
696 Also suppose that a corresponding setter procedure called
697 @code{foo-set!} does exist.
701 (foo-ref f 0) @result{} bla
704 Now we could create a new procedure called @code{foo}, which is a
705 procedure with setter, by calling @code{make-procedure-with-setter} with
706 the accessor and setter procedures @code{foo-ref} and @code{foo-set!}.
707 Let us call this new procedure @code{foo}.
710 (define foo (make-procedure-with-setter foo-ref foo-set!))
713 @code{foo} can from now an be used to either read from the data
714 structure stored in @code{f}, or to write into the structure.
717 (set! (foo f 0) 'dum)
718 (foo f 0) @result{} dum
721 @deffn {Scheme Procedure} make-procedure-with-setter procedure setter
722 @deffnx {C Function} scm_make_procedure_with_setter (procedure, setter)
723 Create a new procedure which behaves like @var{procedure}, but
724 with the associated setter @var{setter}.
727 @deffn {Scheme Procedure} procedure-with-setter? obj
728 @deffnx {C Function} scm_procedure_with_setter_p (obj)
729 Return @code{#t} if @var{obj} is a procedure with an
730 associated setter procedure.
733 @deffn {Scheme Procedure} procedure proc
734 @deffnx {C Function} scm_procedure (proc)
735 Return the procedure of @var{proc}, which must be either a
736 procedure with setter, or an operator struct.
739 @deffn {Scheme Procedure} setter proc
740 Return the setter of @var{proc}, which must be either a procedure with
741 setter or an operator struct.
746 @subsection Lisp Style Macro Definitions
749 @cindex transformation
750 Macros are objects which cause the expression that they appear in to be
751 transformed in some way @emph{before} being evaluated. In expressions
752 that are intended for macro transformation, the identifier that names
753 the relevant macro must appear as the first element, like this:
756 (@var{macro-name} @var{macro-args} @dots{})
759 In Lisp-like languages, the traditional way to define macros is very
760 similar to procedure definitions. The key differences are that the
761 macro definition body should return a list that describes the
762 transformed expression, and that the definition is marked as a macro
763 definition (rather than a procedure definition) by the use of a
764 different definition keyword: in Lisp, @code{defmacro} rather than
765 @code{defun}, and in Scheme, @code{define-macro} rather than
769 @fnindex define-macro
770 Guile supports this style of macro definition using both @code{defmacro}
771 and @code{define-macro}. The only difference between them is how the
772 macro name and arguments are grouped together in the definition:
775 (defmacro @var{name} (@var{args} @dots{}) @var{body} @dots{})
782 (define-macro (@var{name} @var{args} @dots{}) @var{body} @dots{})
786 The difference is analogous to the corresponding difference between
787 Lisp's @code{defun} and Scheme's @code{define}.
789 @code{false-if-exception}, from the @file{boot-9.scm} file in the Guile
790 distribution, is a good example of macro definition using
794 (defmacro false-if-exception (expr)
801 The effect of this definition is that expressions beginning with the
802 identifier @code{false-if-exception} are automatically transformed into
803 a @code{catch} expression following the macro definition specification.
807 (false-if-exception (open-input-file "may-not-exist"))
810 (lambda () (open-input-file "may-not-exist"))
816 @subsection The R5RS @code{syntax-rules} System
817 @cindex R5RS syntax-rules system
819 R5RS defines an alternative system for macro and syntax transformations
820 using the keywords @code{define-syntax}, @code{let-syntax},
821 @code{letrec-syntax} and @code{syntax-rules}.
823 The main difference between the R5RS system and the traditional macros
824 of the previous section is how the transformation is specified. In
825 R5RS, rather than permitting a macro definition to return an arbitrary
826 expression, the transformation is specified in a pattern language that
830 does not require complicated quoting and extraction of components of the
831 source expression using @code{caddr} etc.
834 is designed such that the bindings associated with identifiers in the
835 transformed expression are well defined, and such that it is impossible
836 for the transformed expression to construct new identifiers.
840 The last point is commonly referred to as being @dfn{hygienic}: the R5RS
841 @code{syntax-case} system provides @dfn{hygienic macros}.
843 For example, the R5RS pattern language for the @code{false-if-exception}
844 example of the previous section looks like this:
854 @cindex @code{syncase}
855 In Guile, the @code{syntax-rules} system is provided by the @code{(ice-9
856 syncase)} module. To make these facilities available in your code,
857 include the expression @code{(use-syntax (ice-9 syncase))} (@pxref{Using
858 Guile Modules}) before the first usage of @code{define-syntax} etc. If
859 you are writing a Scheme module, you can alternatively include the form
860 @code{#:use-syntax (ice-9 syncase)} in your @code{define-module}
861 declaration (@pxref{Creating Guile Modules}).
864 * Pattern Language:: The @code{syntax-rules} pattern language.
865 * Define-Syntax:: Top level syntax definitions.
866 * Let-Syntax:: Local syntax definitions.
870 @node Pattern Language
871 @subsubsection The @code{syntax-rules} Pattern Language
875 @subsubsection Top Level Syntax Definitions
877 define-syntax: The gist is
879 (define-syntax <keyword> <transformer-spec>)
881 makes the <keyword> into a macro so that
885 expands at _compile_ or _read_ time (i.e. before any
886 evaluation begins) into some expression that is
887 given by the <transformer-spec>.
891 @subsubsection Local Syntax Definitions
895 @subsection Support for the @code{syntax-case} System
899 @node Internal Macros
900 @subsection Internal Representation of Macros and Syntax
902 Internally, Guile uses three different flavors of macros. The three
903 flavors are called @dfn{acro} (or @dfn{syntax}), @dfn{macro} and
913 with @code{foo} being some flavor of macro, one of the following things
914 will happen when the expression is evaluated.
918 When @code{foo} has been defined to be an @dfn{acro}, the procedure used
919 in the acro definition of @code{foo} is passed the whole expression and
920 the current lexical environment, and whatever that procedure returns is
921 the value of evaluating the expression. You can think of this a
922 procedure that receives its argument as an unevaluated expression.
925 When @code{foo} has been defined to be a @dfn{macro}, the procedure used
926 in the macro definition of @code{foo} is passed the whole expression and
927 the current lexical environment, and whatever that procedure returns is
928 evaluated again. That is, the procedure should return a valid Scheme
932 When @code{foo} has been defined to be a @dfn{mmacro}, the procedure
933 used in the mmacro definition of `foo' is passed the whole expression
934 and the current lexical environment, and whatever that procedure returns
935 replaces the original expression. Evaluation then starts over from the
936 new expression that has just been returned.
939 The key difference between a @dfn{macro} and a @dfn{mmacro} is that the
940 expression returned by a @dfn{mmacro} procedure is remembered (or
941 @dfn{memoized}) so that the expansion does not need to be done again
942 next time the containing code is evaluated.
944 The primitives @code{procedure->syntax}, @code{procedure->macro} and
945 @code{procedure->memoizing-macro} are used to construct acros, macros
946 and mmacros respectively. However, if you do not have a very special
947 reason to use one of these primitives, you should avoid them: they are
948 very specific to Guile's current implementation and therefore likely to
949 change. Use @code{defmacro}, @code{define-macro} (@pxref{Macros}) or
950 @code{define-syntax} (@pxref{Syntax Rules}) instead. (In low level
951 terms, @code{defmacro}, @code{define-macro} and @code{define-syntax} are
952 all implemented as mmacros.)
954 @deffn {Scheme Procedure} procedure->syntax code
955 @deffnx {C Function} scm_makacro (code)
956 Return a macro which, when a symbol defined to this value appears as the
957 first symbol in an expression, returns the result of applying @var{code}
958 to the expression and the environment.
961 @deffn {Scheme Procedure} procedure->macro code
962 @deffnx {C Function} scm_makmacro (code)
963 Return a macro which, when a symbol defined to this value appears as the
964 first symbol in an expression, evaluates the result of applying
965 @var{code} to the expression and the environment. For example:
971 `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))
975 (set! @i{foo} (tracef @i{foo} '@i{foo})).
979 @deffn {Scheme Procedure} procedure->memoizing-macro code
980 @deffnx {C Function} scm_makmmacro (code)
981 Return a macro which, when a symbol defined to this value appears as the
982 first symbol in an expression, evaluates the result of applying
983 @var{code} to the expression and the environment.
984 @code{procedure->memoizing-macro} is the same as
985 @code{procedure->macro}, except that the expression returned by
986 @var{code} replaces the original macro expression in the memoized form
987 of the containing code.
990 In the following primitives, @dfn{acro} flavor macros are referred to
991 as @dfn{syntax transformers}.
993 @deffn {Scheme Procedure} macro? obj
994 @deffnx {C Function} scm_macro_p (obj)
995 Return @code{#t} if @var{obj} is a regular macro, a memoizing macro or a
999 @deffn {Scheme Procedure} macro-type m
1000 @deffnx {C Function} scm_macro_type (m)
1001 Return one of the symbols @code{syntax}, @code{macro} or
1002 @code{macro!}, depending on whether @var{m} is a syntax
1003 transformer, a regular macro, or a memoizing macro,
1004 respectively. If @var{m} is not a macro, @code{#f} is
1008 @deffn {Scheme Procedure} macro-name m
1009 @deffnx {C Function} scm_macro_name (m)
1010 Return the name of the macro @var{m}.
1013 @deffn {Scheme Procedure} macro-transformer m
1014 @deffnx {C Function} scm_macro_transformer (m)
1015 Return the transformer of the macro @var{m}.
1018 @deffn {Scheme Procedure} cons-source xorig x y
1019 @deffnx {C Function} scm_cons_source (xorig, x, y)
1020 Create and return a new pair whose car and cdr are @var{x} and @var{y}.
1021 Any source properties associated with @var{xorig} are also associated
1027 @c TeX-master: "guile.texi"