Commit | Line | Data |
---|---|---|
2da09c3f MV |
1 | @c -*-texinfo-*- |
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. | |
6 | ||
a0e07ba4 NJ |
7 | @page |
8 | @node Procedures and Macros | |
9 | @chapter Procedures and Macros | |
10 | ||
11 | @menu | |
12 | * Lambda:: Basic procedure creation using lambda. | |
f631e15e | 13 | * Primitive Procedures:: Procedures defined in C. |
a0e07ba4 | 14 | * Optional Arguments:: Handling keyword, optional and rest arguments. |
85a9b4ed | 15 | * Procedure Properties:: Procedure properties and meta-information. |
a0e07ba4 NJ |
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. | |
21 | @end menu | |
22 | ||
23 | ||
24 | @node Lambda | |
25 | @section Lambda: Basic Procedure Creation | |
a44758e7 | 26 | @cindex lambda |
a0e07ba4 NJ |
27 | |
28 | @c FIXME::martin: Review me! | |
29 | ||
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}). | |
34 | ||
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 | |
41 | procedure invocation. | |
42 | ||
43 | The following examples will show how procedures can be created using | |
44 | @code{lambda}, and what you can do with these procedures. | |
45 | ||
46 | @lisp | |
47 | (lambda (x) (+ x x)) @result{} @r{a procedure} | |
48 | ((lambda (x) (+ x x)) 4) @result{} 8 | |
49 | @end lisp | |
50 | ||
51 | The fact that the environment in effect when creating a procedure is | |
52 | enclosed in the procedure is shown with this example: | |
53 | ||
54 | @lisp | |
55 | (define add4 | |
56 | (let ((x 4)) | |
57 | (lambda (y) (+ x y)))) | |
58 | (add4 6) @result{} 10 | |
59 | @end lisp | |
60 | ||
61 | ||
62 | @deffn syntax lambda formals body | |
63 | @var{formals} should be a formal argument list as described in the | |
64 | following table. | |
65 | ||
66 | @table @code | |
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 | |
70 | the formal variables. | |
71 | @item @var{variable} | |
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 | |
85a9b4ed | 77 | procedure takes @var{n} or more variables where @var{n} is the number |
a0e07ba4 NJ |
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. | |
85 | @end table | |
86 | ||
ed3bd25b KR |
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}). | |
92 | ||
a0e07ba4 NJ |
93 | @var{body} is a sequence of Scheme expressions which are evaluated in |
94 | order when the procedure is invoked. | |
95 | @end deffn | |
96 | ||
f631e15e GH |
97 | @node Primitive Procedures |
98 | @section Primitive Procedures | |
99 | @cindex primitives | |
100 | @cindex primitive procedures | |
101 | ||
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}). | |
107 | ||
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. | |
118 | @end deftypefun | |
119 | ||
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 | |
126 | required. | |
127 | @end deftypefun | |
128 | ||
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. | |
a0e07ba4 NJ |
133 | |
134 | @node Optional Arguments | |
135 | @section Optional Arguments | |
136 | ||
137 | @c FIXME::martin: Review me! | |
138 | ||
923d5b87 | 139 | Scheme procedures, as defined in R5RS, can either handle a fixed number |
a0e07ba4 NJ |
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 | |
146 | (@pxref{Lambda}). | |
147 | ||
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 | |
151 | (@pxref{Keywords}). | |
152 | ||
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: | |
155 | ||
a44758e7 | 156 | @cindex @code{optargs} |
a0e07ba4 NJ |
157 | @lisp |
158 | (use-modules (ice-9 optargs)) | |
159 | @end lisp | |
160 | ||
161 | @menu | |
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. | |
166 | @end menu | |
167 | ||
168 | ||
169 | @node let-optional Reference | |
170 | @subsection let-optional Reference | |
171 | ||
172 | @c FIXME::martin: Review me! | |
173 | ||
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}). | |
179 | ||
9c4dd6f4 | 180 | @deffn {library syntax} let-optional rest-arg (binding @dots{}) expr @dots{} |
a0e07ba4 NJ |
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 | |
77c16d83 | 190 | @code{#f} if no default value was specified. @var{rest-arg} remains |
a0e07ba4 NJ |
191 | bound to whatever may have been left of @var{rest-arg}. |
192 | ||
193 | After binding the variables, the expressions @var{expr} @dots{} are | |
194 | evaluated in order. | |
195 | @end deffn | |
196 | ||
197 | ||
198 | @node let-keywords Reference | |
199 | @subsection let-keywords Reference | |
200 | ||
201 | @c FIXME::martin: Review me! | |
202 | ||
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. | |
206 | ||
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}). | |
210 | ||
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. | |
222 | ||
223 | After binding the variables, the expressions @var{expr} @dots{} are | |
224 | evaluated in order. | |
225 | @end deffn | |
226 | ||
227 | ||
228 | @node lambda* Reference | |
229 | @subsection lambda* Reference | |
230 | ||
231 | @c FIXME::martin: Review me! | |
232 | ||
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. | |
237 | ||
238 | For quick reference, here is the syntax of the formal argument list for | |
239 | @code{lambda*} (brackets are used to indicate grouping only): | |
240 | ||
241 | @example | |
242 | ext-param-list ::= [identifier]* [#:optional [ext-var-decl]+]? | |
243 | [#:key [ext-var-decl]+ [#:allow-other-keys]?]? | |
244 | [[#:rest identifier]|[. identifier]]? | |
245 | ||
246 | ext-var-decl ::= identifier | ( identifier expression ) | |
247 | @end example | |
248 | ||
249 | The characters `*', `+' and `?' are not to be taken literally; they mean | |
85a9b4ed TTN |
250 | respectively, zero or more occurrences, one or more occurrences, and one |
251 | or zero occurrences. | |
a0e07ba4 NJ |
252 | |
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 | |
85a9b4ed | 256 | parameter list, but before any dotted rest argument. For example, |
a0e07ba4 NJ |
257 | |
258 | @lisp | |
259 | (lambda* (a b #:optional c d . e) '()) | |
260 | @end lisp | |
261 | ||
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 | |
77c16d83 | 265 | bound to @code{#f}. |
a0e07ba4 NJ |
266 | |
267 | @code{lambda*} can also take keyword arguments. For example, a procedure | |
268 | defined like this: | |
269 | ||
270 | @lisp | |
271 | (lambda* (#:key xyzzy larch) '()) | |
272 | @end lisp | |
273 | ||
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. | |
277 | ||
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: | |
281 | ||
282 | @lisp | |
283 | (lambda* (foo #:optional (bar 42) #:key (baz 73)) | |
284 | (list foo bar baz)) | |
285 | @end lisp | |
286 | ||
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. | |
291 | ||
292 | @code{lambda*} also supports two more special parameter list keywords. | |
293 | ||
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, | |
301 | ||
302 | @lisp | |
303 | ((lambda* (#:key (heads 0) (tails 0)) (display (list heads tails))) | |
304 | #:heads 37 #:tails 42 #:heads 99) | |
305 | @end lisp | |
306 | ||
307 | would result in (99 47) being displayed. | |
308 | ||
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. | |
314 | @end deffn | |
315 | ||
a0e07ba4 NJ |
316 | |
317 | @node define* Reference | |
318 | @subsection define* Reference | |
319 | ||
320 | @c FIXME::martin: Review me! | |
321 | ||
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*}. | |
325 | ||
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. | |
331 | ||
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: | |
337 | ||
338 | @lisp | |
339 | (define* (x y #:optional a (z 3) #:key w . u) | |
340 | (display (list y z u))) | |
341 | @end lisp | |
342 | defines a procedure @code{x} with a fixed argument @var{y}, an optional | |
85a9b4ed | 343 | argument @var{a}, another optional argument @var{z} with default value 3, |
a0e07ba4 NJ |
344 | a keyword argument @var{w}, and a rest argument @var{u}. |
345 | ||
346 | @lisp | |
347 | (define-public* ((foo #:optional bar) #:optional baz) '()) | |
348 | @end lisp | |
349 | ||
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}. | |
353 | ||
354 | Of course, @code{define*[-public]} also supports @code{#:rest} and | |
355 | @code{#:allow-other-keys} in the same way as @code{lambda*}. | |
356 | @end deffn | |
357 | ||
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 | |
85a9b4ed | 361 | take @code{lambda*}-style extended parameter lists, where @code{#:optional}, |
a0e07ba4 NJ |
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: | |
364 | ||
365 | @lisp | |
366 | (defmacro* transmorgify (a #:optional b) | |
367 | (a 1)) | |
368 | @end lisp | |
369 | @end deffn | |
370 | ||
371 | ||
372 | @node Procedure Properties | |
85a9b4ed | 373 | @section Procedure Properties and Meta-information |
a0e07ba4 NJ |
374 | |
375 | @c FIXME::martin: Review me! | |
376 | ||
377 | Procedures always have attached the environment in which they were | |
378 | created and information about how to apply them to actual arguments. In | |
85a9b4ed | 379 | addition to that, properties and meta-information can be stored with |
a0e07ba4 NJ |
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. | |
383 | ||
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. | |
390 | ||
391 | @rnindex procedure? | |
8f85c0c6 NJ |
392 | @deffn {Scheme Procedure} procedure? obj |
393 | @deffnx {C Function} scm_procedure_p (obj) | |
a0e07ba4 NJ |
394 | Return @code{#t} if @var{obj} is a procedure. |
395 | @end deffn | |
396 | ||
8f85c0c6 NJ |
397 | @deffn {Scheme Procedure} closure? obj |
398 | @deffnx {C Function} scm_closure_p (obj) | |
a0e07ba4 NJ |
399 | Return @code{#t} if @var{obj} is a closure. |
400 | @end deffn | |
401 | ||
8f85c0c6 NJ |
402 | @deffn {Scheme Procedure} thunk? obj |
403 | @deffnx {C Function} scm_thunk_p (obj) | |
a0e07ba4 NJ |
404 | Return @code{#t} if @var{obj} is a thunk. |
405 | @end deffn | |
406 | ||
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. | |
412 | ||
f2ba76ae NJ |
413 | @deffn {Scheme Procedure} procedure-name proc |
414 | @deffnx {C Function} scm_procedure_name (proc) | |
415 | Return the name of the procedure @var{proc} | |
416 | @end deffn | |
417 | ||
418 | @deffn {Scheme Procedure} procedure-source proc | |
419 | @deffnx {C Function} scm_procedure_source (proc) | |
420 | Return the source of the procedure @var{proc}. | |
421 | @end deffn | |
422 | ||
423 | @deffn {Scheme Procedure} procedure-environment proc | |
424 | @deffnx {C Function} scm_procedure_environment (proc) | |
425 | Return the environment of the procedure @var{proc}. | |
426 | @end deffn | |
427 | ||
8f85c0c6 NJ |
428 | @deffn {Scheme Procedure} procedure-properties proc |
429 | @deffnx {C Function} scm_procedure_properties (proc) | |
a0e07ba4 NJ |
430 | Return @var{obj}'s property list. |
431 | @end deffn | |
432 | ||
8f85c0c6 NJ |
433 | @deffn {Scheme Procedure} procedure-property obj key |
434 | @deffnx {C Function} scm_procedure_property (obj, key) | |
a0e07ba4 NJ |
435 | Return the property of @var{obj} with name @var{key}. |
436 | @end deffn | |
437 | ||
8f85c0c6 NJ |
438 | @deffn {Scheme Procedure} set-procedure-properties! proc alist |
439 | @deffnx {C Function} scm_set_procedure_properties_x (proc, alist) | |
a0e07ba4 NJ |
440 | Set @var{obj}'s property list to @var{alist}. |
441 | @end deffn | |
442 | ||
8f85c0c6 NJ |
443 | @deffn {Scheme Procedure} set-procedure-property! obj key value |
444 | @deffnx {C Function} scm_set_procedure_property_x (obj, key, value) | |
a0e07ba4 NJ |
445 | In @var{obj}'s property list, set the property named @var{key} to |
446 | @var{value}. | |
447 | @end deffn | |
448 | ||
449 | @cindex procedure documentation | |
450 | Documentation for a procedure can be accessed with the procedure | |
451 | @code{procedure-documentation}. | |
452 | ||
8f85c0c6 NJ |
453 | @deffn {Scheme Procedure} procedure-documentation proc |
454 | @deffnx {C Function} scm_procedure_documentation (proc) | |
a0e07ba4 NJ |
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. | |
459 | @end deffn | |
460 | ||
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. | |
465 | ||
8f85c0c6 NJ |
466 | @deffn {Scheme Procedure} set-source-properties! obj plist |
467 | @deffnx {C Function} scm_set_source_properties_x (obj, plist) | |
a0e07ba4 NJ |
468 | Install the association list @var{plist} as the source property |
469 | list for @var{obj}. | |
470 | @end deffn | |
471 | ||
8f85c0c6 NJ |
472 | @deffn {Scheme Procedure} set-source-property! obj key datum |
473 | @deffnx {C Function} scm_set_source_property_x (obj, key, datum) | |
a0e07ba4 NJ |
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. | |
476 | @end deffn | |
477 | ||
8f85c0c6 NJ |
478 | @deffn {Scheme Procedure} source-properties obj |
479 | @deffnx {C Function} scm_source_properties (obj) | |
a0e07ba4 NJ |
480 | Return the source property association list of @var{obj}. |
481 | @end deffn | |
482 | ||
483 | ||
8f85c0c6 NJ |
484 | @deffn {Scheme Procedure} source-property obj key |
485 | @deffnx {C Function} scm_source_property (obj, key) | |
a0e07ba4 NJ |
486 | Return the source property specified by @var{key} from |
487 | @var{obj}'s source property list. | |
488 | @end deffn | |
489 | ||
490 | ||
491 | @node Procedures with Setters | |
492 | @section Procedures with Setters | |
493 | ||
494 | @c FIXME::martin: Review me! | |
495 | ||
496 | @c FIXME::martin: Document `operator struct'. | |
497 | ||
498 | @cindex procedure with setter | |
499 | @cindex setter | |
500 | A @dfn{procedure with setter} is a special kind of procedure which | |
85a9b4ed | 501 | normally behaves like any accessor procedure, that is a procedure which |
a0e07ba4 NJ |
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. | |
505 | ||
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 | |
508 | by example. | |
509 | ||
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: | |
515 | @lisp | |
516 | (define foo-ref vector-ref) | |
517 | (define foo-set! vector-set!) | |
518 | (define f (make-vector 2 #f)) | |
519 | @end lisp | |
520 | } | |
521 | ||
522 | @lisp | |
523 | (foo-ref f 0) @result{} bar | |
524 | (foo-ref f 1) @result{} braz | |
525 | @end lisp | |
526 | ||
527 | Also suppose that a corresponding setter procedure called | |
528 | @code{foo-set!} does exist. | |
529 | ||
530 | @lisp | |
531 | (foo-set! f 0 'bla) | |
532 | (foo-ref f 0) @result{} bla | |
533 | @end lisp | |
534 | ||
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}. | |
539 | ||
540 | @lisp | |
541 | (define foo (make-procedure-with-setter foo-ref foo-set!)) | |
542 | @end lisp | |
543 | ||
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. | |
546 | ||
547 | @lisp | |
548 | (set! (foo f 0) 'dum) | |
549 | (foo f 0) @result{} dum | |
550 | @end lisp | |
551 | ||
8f85c0c6 NJ |
552 | @deffn {Scheme Procedure} make-procedure-with-setter procedure setter |
553 | @deffnx {C Function} scm_make_procedure_with_setter (procedure, setter) | |
a0e07ba4 NJ |
554 | Create a new procedure which behaves like @var{procedure}, but |
555 | with the associated setter @var{setter}. | |
556 | @end deffn | |
557 | ||
8f85c0c6 NJ |
558 | @deffn {Scheme Procedure} procedure-with-setter? obj |
559 | @deffnx {C Function} scm_procedure_with_setter_p (obj) | |
a0e07ba4 NJ |
560 | Return @code{#t} if @var{obj} is a procedure with an |
561 | associated setter procedure. | |
562 | @end deffn | |
563 | ||
8f85c0c6 NJ |
564 | @deffn {Scheme Procedure} procedure proc |
565 | @deffnx {C Function} scm_procedure (proc) | |
a0e07ba4 NJ |
566 | Return the procedure of @var{proc}, which must be either a |
567 | procedure with setter, or an operator struct. | |
568 | @end deffn | |
569 | ||
8f85c0c6 | 570 | @deffn {Scheme Procedure} setter proc |
a0e07ba4 NJ |
571 | Return the setter of @var{proc}, which must be either a procedure with |
572 | setter or an operator struct. | |
573 | @end deffn | |
574 | ||
575 | ||
576 | @node Macros | |
577 | @section Lisp Style Macro Definitions | |
578 | ||
579 | @cindex macros | |
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: | |
585 | ||
586 | @lisp | |
587 | (@var{macro-name} @var{macro-args} @dots{}) | |
588 | @end lisp | |
589 | ||
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 | |
597 | @code{define}. | |
598 | ||
599 | @fnindex defmacro | |
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: | |
604 | ||
605 | @lisp | |
606 | (defmacro @var{name} (@var{args} @dots{}) @var{body} @dots{}) | |
607 | @end lisp | |
608 | ||
609 | @noindent | |
610 | is the same as | |
611 | ||
612 | @lisp | |
613 | (define-macro (@var{name} @var{args} @dots{}) @var{body} @dots{}) | |
614 | @end lisp | |
615 | ||
616 | @noindent | |
617 | The difference is analogous to the corresponding difference between | |
618 | Lisp's @code{defun} and Scheme's @code{define}. | |
619 | ||
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 | |
622 | @code{defmacro}: | |
623 | ||
624 | @lisp | |
625 | (defmacro false-if-exception (expr) | |
626 | `(catch #t | |
627 | (lambda () ,expr) | |
628 | (lambda args #f))) | |
629 | @end lisp | |
630 | ||
631 | @noindent | |
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. | |
635 | For example: | |
636 | ||
637 | @lisp | |
638 | (false-if-exception (open-input-file "may-not-exist")) | |
639 | @equiv{} | |
640 | (catch #t | |
641 | (lambda () (open-input-file "may-not-exist")) | |
642 | (lambda args #f)) | |
643 | @end lisp | |
644 | ||
645 | ||
646 | @node Syntax Rules | |
647 | @section The R5RS @code{syntax-rules} System | |
a5504089 | 648 | @cindex R5RS syntax-rules system |
a0e07ba4 NJ |
649 | |
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}. | |
653 | ||
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 | |
658 | ||
659 | @itemize @bullet | |
660 | @item | |
661 | does not require complicated quoting and extraction of components of the | |
662 | source expression using @code{caddr} etc. | |
663 | ||
664 | @item | |
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. | |
668 | @end itemize | |
669 | ||
670 | @noindent | |
671 | The last point is commonly referred to as being @dfn{hygienic}: the R5RS | |
672 | @code{syntax-case} system provides @dfn{hygienic macros}. | |
673 | ||
674 | For example, the R5RS pattern language for the @code{false-if-exception} | |
675 | example of the previous section looks like this: | |
676 | ||
677 | @lisp | |
678 | (syntax-rules () | |
679 | ((_ expr) | |
680 | (catch #t | |
681 | (lambda () expr) | |
682 | (lambda args #f)))) | |
683 | @end lisp | |
684 | ||
a44758e7 | 685 | @cindex @code{syncase} |
a0e07ba4 NJ |
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, | |
f2ba76ae NJ |
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} | |
a0e07ba4 NJ |
692 | declaration (@pxref{Creating Guile Modules}). |
693 | ||
694 | @menu | |
695 | * Pattern Language:: The @code{syntax-rules} pattern language. | |
696 | * Define-Syntax:: Top level syntax definitions. | |
697 | * Let-Syntax:: Local syntax definitions. | |
698 | @end menu | |
699 | ||
700 | ||
701 | @node Pattern Language | |
702 | @subsection The @code{syntax-rules} Pattern Language | |
703 | ||
704 | ||
705 | @node Define-Syntax | |
706 | @subsection Top Level Syntax Definitions | |
707 | ||
708 | define-syntax: The gist is | |
709 | ||
710 | (define-syntax <keyword> <transformer-spec>) | |
711 | ||
712 | makes the <keyword> into a macro so that | |
713 | ||
714 | (<keyword> ...) | |
715 | ||
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>. | |
719 | ||
720 | ||
721 | @node Let-Syntax | |
722 | @subsection Local Syntax Definitions | |
723 | ||
724 | ||
725 | @node Syntax Case | |
726 | @section Support for the @code{syntax-case} System | |
727 | ||
728 | ||
729 | ||
730 | @node Internal Macros | |
731 | @section Internal Representation of Macros and Syntax | |
732 | ||
85a9b4ed TTN |
733 | Internally, Guile uses three different flavors of macros. The three |
734 | flavors are called @dfn{acro} (or @dfn{syntax}), @dfn{macro} and | |
a0e07ba4 NJ |
735 | @dfn{mmacro}. |
736 | ||
737 | Given the expression | |
738 | ||
739 | @lisp | |
740 | (foo @dots{}) | |
741 | @end lisp | |
742 | ||
743 | @noindent | |
85a9b4ed | 744 | with @code{foo} being some flavor of macro, one of the following things |
a0e07ba4 NJ |
745 | will happen when the expression is evaluated. |
746 | ||
747 | @itemize @bullet | |
748 | @item | |
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. | |
754 | ||
755 | @item | |
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 | |
760 | expression. | |
761 | ||
762 | @item | |
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. | |
768 | @end itemize | |
769 | ||
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. | |
774 | ||
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.) | |
784 | ||
8f85c0c6 NJ |
785 | @deffn {Scheme Procedure} procedure->syntax code |
786 | @deffnx {C Function} scm_makacro (code) | |
e8f1ff71 NJ |
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. | |
a0e07ba4 NJ |
790 | @end deffn |
791 | ||
8f85c0c6 NJ |
792 | @deffn {Scheme Procedure} procedure->macro code |
793 | @deffnx {C Function} scm_makmacro (code) | |
e8f1ff71 NJ |
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: | |
a0e07ba4 NJ |
797 | |
798 | @lisp | |
799 | (define trace | |
800 | (procedure->macro | |
e8f1ff71 NJ |
801 | (lambda (x env) |
802 | `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x)))))) | |
a0e07ba4 | 803 | |
e8f1ff71 NJ |
804 | (trace @i{foo}) |
805 | @equiv{} | |
806 | (set! @i{foo} (tracef @i{foo} '@i{foo})). | |
a0e07ba4 NJ |
807 | @end lisp |
808 | @end deffn | |
809 | ||
8f85c0c6 NJ |
810 | @deffn {Scheme Procedure} procedure->memoizing-macro code |
811 | @deffnx {C Function} scm_makmmacro (code) | |
a0e07ba4 NJ |
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. | |
819 | @end deffn | |
820 | ||
85a9b4ed | 821 | In the following primitives, @dfn{acro} flavor macros are referred to |
a0e07ba4 NJ |
822 | as @dfn{syntax transformers}. |
823 | ||
8f85c0c6 NJ |
824 | @deffn {Scheme Procedure} macro? obj |
825 | @deffnx {C Function} scm_macro_p (obj) | |
a0e07ba4 NJ |
826 | Return @code{#t} if @var{obj} is a regular macro, a memoizing macro or a |
827 | syntax transformer. | |
828 | @end deffn | |
829 | ||
8f85c0c6 NJ |
830 | @deffn {Scheme Procedure} macro-type m |
831 | @deffnx {C Function} scm_macro_type (m) | |
a0e07ba4 NJ |
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 | |
836 | returned. | |
837 | @end deffn | |
838 | ||
8f85c0c6 NJ |
839 | @deffn {Scheme Procedure} macro-name m |
840 | @deffnx {C Function} scm_macro_name (m) | |
a0e07ba4 NJ |
841 | Return the name of the macro @var{m}. |
842 | @end deffn | |
843 | ||
8f85c0c6 NJ |
844 | @deffn {Scheme Procedure} macro-transformer m |
845 | @deffnx {C Function} scm_macro_transformer (m) | |
a0e07ba4 NJ |
846 | Return the transformer of the macro @var{m}. |
847 | @end deffn | |
848 | ||
8f85c0c6 NJ |
849 | @deffn {Scheme Procedure} cons-source xorig x y |
850 | @deffnx {C Function} scm_cons_source (xorig, x, y) | |
a0e07ba4 NJ |
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 | |
853 | with the new pair. | |
854 | @end deffn | |
855 | ||
856 | ||
857 | @c Local Variables: | |
858 | @c TeX-master: "guile.texi" | |
859 | @c End: |