Commit | Line | Data |
---|---|---|
07d83abe MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
b3da54d1 | 3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2010, |
9f17d967 | 4 | @c 2011, 2012, 2013 Free Software Foundation, Inc. |
07d83abe MV |
5 | @c See the file guile.texi for copying conditions. |
6 | ||
e4955559 AW |
7 | @node Procedures |
8 | @section Procedures | |
07d83abe MV |
9 | |
10 | @menu | |
11 | * Lambda:: Basic procedure creation using lambda. | |
12 | * Primitive Procedures:: Procedures defined in C. | |
00ce5125 | 13 | * Compiled Procedures:: Scheme procedures can be compiled. |
07d83abe | 14 | * Optional Arguments:: Handling keyword, optional and rest arguments. |
f916cbc4 | 15 | * Case-lambda:: One function, multiple arities. |
18f06db9 | 16 | * Higher-Order Functions:: Function that take or return functions. |
07d83abe MV |
17 | * Procedure Properties:: Procedure properties and meta-information. |
18 | * Procedures with Setters:: Procedures with setters. | |
165b10dd | 19 | * Inlinable Procedures:: Procedures that can be inlined. |
07d83abe MV |
20 | @end menu |
21 | ||
22 | ||
23 | @node Lambda | |
24 | @subsection Lambda: Basic Procedure Creation | |
25 | @cindex lambda | |
26 | ||
07d83abe MV |
27 | A @code{lambda} expression evaluates to a procedure. The environment |
28 | which is in effect when a @code{lambda} expression is evaluated is | |
29 | enclosed in the newly created procedure, this is referred to as a | |
30 | @dfn{closure} (@pxref{About Closure}). | |
31 | ||
32 | When a procedure created by @code{lambda} is called with some actual | |
33 | arguments, the environment enclosed in the procedure is extended by | |
34 | binding the variables named in the formal argument list to new locations | |
35 | and storing the actual arguments into these locations. Then the body of | |
2e4ef7ed | 36 | the @code{lambda} expression is evaluated sequentially. The result of |
07d83abe MV |
37 | the last expression in the procedure body is then the result of the |
38 | procedure invocation. | |
39 | ||
40 | The following examples will show how procedures can be created using | |
41 | @code{lambda}, and what you can do with these procedures. | |
42 | ||
43 | @lisp | |
44 | (lambda (x) (+ x x)) @result{} @r{a procedure} | |
45 | ((lambda (x) (+ x x)) 4) @result{} 8 | |
46 | @end lisp | |
47 | ||
48 | The fact that the environment in effect when creating a procedure is | |
49 | enclosed in the procedure is shown with this example: | |
50 | ||
51 | @lisp | |
52 | (define add4 | |
53 | (let ((x 4)) | |
54 | (lambda (y) (+ x y)))) | |
55 | (add4 6) @result{} 10 | |
56 | @end lisp | |
57 | ||
58 | ||
59 | @deffn syntax lambda formals body | |
60 | @var{formals} should be a formal argument list as described in the | |
61 | following table. | |
62 | ||
63 | @table @code | |
64 | @item (@var{variable1} @dots{}) | |
65 | The procedure takes a fixed number of arguments; when the procedure is | |
66 | called, the arguments will be stored into the newly created location for | |
67 | the formal variables. | |
68 | @item @var{variable} | |
69 | The procedure takes any number of arguments; when the procedure is | |
70 | called, the sequence of actual arguments will converted into a list and | |
71 | stored into the newly created location for the formal variable. | |
72 | @item (@var{variable1} @dots{} @var{variablen} . @var{variablen+1}) | |
73 | If a space-delimited period precedes the last variable, then the | |
74 | procedure takes @var{n} or more variables where @var{n} is the number | |
75 | of formal arguments before the period. There must be at least one | |
76 | argument before the period. The first @var{n} actual arguments will be | |
77 | stored into the newly allocated locations for the first @var{n} formal | |
78 | arguments and the sequence of the remaining actual arguments is | |
79 | converted into a list and the stored into the location for the last | |
80 | formal argument. If there are exactly @var{n} actual arguments, the | |
81 | empty list is stored into the location of the last formal argument. | |
82 | @end table | |
83 | ||
84 | The list in @var{variable} or @var{variablen+1} is always newly | |
85 | created and the procedure can modify it if desired. This is the case | |
86 | even when the procedure is invoked via @code{apply}, the required part | |
87 | of the list argument there will be copied (@pxref{Fly Evaluation,, | |
88 | Procedures for On the Fly Evaluation}). | |
89 | ||
90 | @var{body} is a sequence of Scheme expressions which are evaluated in | |
91 | order when the procedure is invoked. | |
92 | @end deffn | |
93 | ||
94 | @node Primitive Procedures | |
95 | @subsection Primitive Procedures | |
96 | @cindex primitives | |
97 | @cindex primitive procedures | |
98 | ||
99 | Procedures written in C can be registered for use from Scheme, | |
100 | provided they take only arguments of type @code{SCM} and return | |
101 | @code{SCM} values. @code{scm_c_define_gsubr} is likely to be the most | |
102 | useful mechanism, combining the process of registration | |
103 | (@code{scm_c_make_gsubr}) and definition (@code{scm_define}). | |
104 | ||
105 | @deftypefun SCM scm_c_make_gsubr (const char *name, int req, int opt, int rst, fcn) | |
64de6db5 | 106 | Register a C procedure @var{fcn} as a ``subr'' --- a primitive |
07d83abe MV |
107 | subroutine that can be called from Scheme. It will be associated with |
108 | the given @var{name} but no environment binding will be created. The | |
109 | arguments @var{req}, @var{opt} and @var{rst} specify the number of | |
110 | required, optional and ``rest'' arguments respectively. The total | |
111 | number of these arguments should match the actual number of arguments | |
4adf9a7e | 112 | to @var{fcn}, but may not exceed 10. The number of rest arguments should be 0 or 1. |
07d83abe MV |
113 | @code{scm_c_make_gsubr} returns a value of type @code{SCM} which is a |
114 | ``handle'' for the procedure. | |
115 | @end deftypefun | |
116 | ||
117 | @deftypefun SCM scm_c_define_gsubr (const char *name, int req, int opt, int rst, fcn) | |
64de6db5 | 118 | Register a C procedure @var{fcn}, as for @code{scm_c_make_gsubr} |
07d83abe MV |
119 | above, and additionally create a top-level Scheme binding for the |
120 | procedure in the ``current environment'' using @code{scm_define}. | |
121 | @code{scm_c_define_gsubr} returns a handle for the procedure in the | |
122 | same way as @code{scm_c_make_gsubr}, which is usually not further | |
123 | required. | |
124 | @end deftypefun | |
125 | ||
00ce5125 AW |
126 | @node Compiled Procedures |
127 | @subsection Compiled Procedures | |
128 | ||
7545ddd4 AW |
129 | The evaluation strategy given in @ref{Lambda} describes how procedures |
130 | are @dfn{interpreted}. Interpretation operates directly on expanded | |
131 | Scheme source code, recursively calling the evaluator to obtain the | |
132 | value of nested expressions. | |
f916cbc4 AW |
133 | |
134 | Most procedures are compiled, however. This means that Guile has done | |
7545ddd4 AW |
135 | some pre-computation on the procedure, to determine what it will need to |
136 | do each time the procedure runs. Compiled procedures run faster than | |
137 | interpreted procedures. | |
00ce5125 | 138 | |
f916cbc4 AW |
139 | Loading files is the normal way that compiled procedures come to |
140 | being. If Guile sees that a file is uncompiled, or that its compiled | |
141 | file is out of date, it will attempt to compile the file when it is | |
142 | loaded, and save the result to disk. Procedures can be compiled at | |
143 | runtime as well. @xref{Read/Load/Eval/Compile}, for more information | |
144 | on runtime compilation. | |
00ce5125 | 145 | |
5a069042 AW |
146 | Compiled procedures, also known as @dfn{programs}, respond all |
147 | procedures that operate on procedures. In addition, there are a few | |
46d666d4 | 148 | more accessors for low-level details on programs. |
5a069042 | 149 | |
46d666d4 AW |
150 | Most people won't need to use the routines described in this section, |
151 | but it's good to have them documented. You'll have to include the | |
152 | appropriate module first, though: | |
5a069042 AW |
153 | |
154 | @example | |
155 | (use-modules (system vm program)) | |
156 | @end example | |
157 | ||
46d666d4 AW |
158 | @deffn {Scheme Procedure} program? obj |
159 | @deffnx {C Function} scm_program_p (obj) | |
160 | Returns @code{#t} iff @var{obj} is a compiled procedure. | |
161 | @end deffn | |
162 | ||
81fd3152 AW |
163 | @deffn {Scheme Procedure} program-objcode program |
164 | @deffnx {C Function} scm_program_objcode (program) | |
73643339 AW |
165 | Returns the object code associated with this program. @xref{Bytecode |
166 | and Objcode}, for more information. | |
46d666d4 AW |
167 | @end deffn |
168 | ||
169 | @deffn {Scheme Procedure} program-objects program | |
170 | @deffnx {C Function} scm_program_objects (program) | |
171 | Returns the ``object table'' associated with this program, as a | |
172 | vector. @xref{VM Programs}, for more information. | |
5a069042 AW |
173 | @end deffn |
174 | ||
46d666d4 AW |
175 | @deffn {Scheme Procedure} program-module program |
176 | @deffnx {C Function} scm_program_module (program) | |
81fd3152 AW |
177 | Returns the module that was current when this program was created. Can |
178 | return @code{#f} if the compiler could determine that this information | |
179 | was unnecessary. | |
46d666d4 AW |
180 | @end deffn |
181 | ||
f916cbc4 AW |
182 | @deffn {Scheme Procedure} program-free-variables program |
183 | @deffnx {C Function} scm_program_free_variables (program) | |
184 | Returns the set of free variables that this program captures in its | |
185 | closure, as a vector. If a closure is code with data, you can get the | |
186 | code from @code{program-objcode}, and the data via | |
187 | @code{program-free-variables}. | |
188 | ||
189 | Some of the values captured are actually in variable ``boxes''. | |
190 | @xref{Variables and the VM}, for more information. | |
46d666d4 AW |
191 | |
192 | Users must not modify the returned value unless they think they're | |
193 | really clever. | |
194 | @end deffn | |
195 | ||
46d666d4 | 196 | @deffn {Scheme Procedure} program-meta program |
f916cbc4 | 197 | @deffnx {C Function} scm_program_meta (program) |
46d666d4 AW |
198 | Return the metadata thunk of @var{program}, or @code{#f} if it has no |
199 | metadata. | |
200 | ||
201 | When called, a metadata thunk returns a list of the following form: | |
f916cbc4 | 202 | @code{(@var{bindings} @var{sources} @var{arities} . @var{properties})}. The format |
46d666d4 AW |
203 | of each of these elements is discussed below. |
204 | @end deffn | |
205 | ||
5a069042 | 206 | @deffn {Scheme Procedure} program-bindings program |
f916cbc4 | 207 | @deffnx {Scheme Procedure} make-binding name boxed? index start end |
5a069042 | 208 | @deffnx {Scheme Procedure} binding:name binding |
f916cbc4 | 209 | @deffnx {Scheme Procedure} binding:boxed? binding |
5a069042 AW |
210 | @deffnx {Scheme Procedure} binding:index binding |
211 | @deffnx {Scheme Procedure} binding:start binding | |
212 | @deffnx {Scheme Procedure} binding:end binding | |
213 | Bindings annotations for programs, along with their accessors. | |
214 | ||
215 | Bindings declare names and liveness extents for block-local variables. | |
216 | The best way to see what these are is to play around with them at a | |
f916cbc4 | 217 | REPL. @xref{VM Concepts}, for more information. |
5a069042 | 218 | |
81fd3152 AW |
219 | Note that bindings information is stored in a program as part of its |
220 | metadata thunk, so including it in the generated object code does not | |
221 | impose a runtime performance penalty. | |
5a069042 AW |
222 | @end deffn |
223 | ||
224 | @deffn {Scheme Procedure} program-sources program | |
225 | @deffnx {Scheme Procedure} source:addr source | |
226 | @deffnx {Scheme Procedure} source:line source | |
227 | @deffnx {Scheme Procedure} source:column source | |
228 | @deffnx {Scheme Procedure} source:file source | |
229 | Source location annotations for programs, along with their accessors. | |
230 | ||
46d666d4 AW |
231 | Source location information propagates through the compiler and ends |
232 | up being serialized to the program's metadata. This information is | |
233 | keyed by the offset of the instruction pointer within the object code | |
234 | of the program. Specifically, it is keyed on the @code{ip} @emph{just | |
235 | following} an instruction, so that backtraces can find the source | |
236 | location of a call that is in progress. | |
5a069042 AW |
237 | @end deffn |
238 | ||
f916cbc4 AW |
239 | @deffn {Scheme Procedure} program-arities program |
240 | @deffnx {C Function} scm_program_arities (program) | |
241 | @deffnx {Scheme Procedure} program-arity program ip | |
242 | @deffnx {Scheme Procedure} arity:start arity | |
243 | @deffnx {Scheme Procedure} arity:end arity | |
244 | @deffnx {Scheme Procedure} arity:nreq arity | |
245 | @deffnx {Scheme Procedure} arity:nopt arity | |
246 | @deffnx {Scheme Procedure} arity:rest? arity | |
247 | @deffnx {Scheme Procedure} arity:kw arity | |
248 | @deffnx {Scheme Procedure} arity:allow-other-keys? arity | |
249 | Accessors for a representation of the ``arity'' of a program. | |
250 | ||
251 | The normal case is that a procedure has one arity. For example, | |
252 | @code{(lambda (x) x)}, takes one required argument, and that's it. One | |
253 | could access that number of required arguments via @code{(arity:nreq | |
254 | (program-arities (lambda (x) x)))}. Similarly, @code{arity:nopt} gets | |
255 | the number of optional arguments, and @code{arity:rest?} returns a true | |
256 | value if the procedure has a rest arg. | |
257 | ||
258 | @code{arity:kw} returns a list of @code{(@var{kw} . @var{idx})} pairs, | |
259 | if the procedure has keyword arguments. The @var{idx} refers to the | |
260 | @var{idx}th local variable; @xref{Variables and the VM}, for more | |
261 | information. Finally @code{arity:allow-other-keys?} returns a true | |
262 | value if other keys are allowed. @xref{Optional Arguments}, for more | |
263 | information. | |
264 | ||
265 | So what about @code{arity:start} and @code{arity:end}, then? They | |
266 | return the range of bytes in the program's bytecode for which a given | |
267 | arity is valid. You see, a procedure can actually have more than one | |
268 | arity. The question, ``what is a procedure's arity'' only really makes | |
269 | sense at certain points in the program, delimited by these | |
270 | @code{arity:start} and @code{arity:end} values. | |
271 | @end deffn | |
272 | ||
6fca8730 | 273 | @deffn {Scheme Procedure} program-arguments-alist program [ip] |
9f17d967 AW |
274 | Return an association list describing the arguments that @var{program} accepts, or |
275 | @code{#f} if the information cannot be obtained. | |
276 | ||
4dbac5e0 AW |
277 | The alist keys that are currently defined are `required', `optional', |
278 | `keyword', `allow-other-keys?', and `rest'. For example: | |
279 | ||
9f17d967 AW |
280 | @example |
281 | (program-arguments-alist | |
282 | (lambda* (a b #:optional c #:key (d 1) #:rest e) | |
283 | #t)) @result{} | |
284 | ((required . (a b)) | |
285 | (optional . (c)) | |
286 | (keyword . ((#:d . 4))) | |
287 | (allow-other-keys? . #f) | |
288 | (rest . d)) | |
289 | @end example | |
4dbac5e0 | 290 | @end deffn |
9f17d967 | 291 | |
4dbac5e0 AW |
292 | @deffn {Scheme Procedure} program-lambda-list program [ip] |
293 | Return a representation of the arguments of @var{program} as a lambda | |
294 | list, or @code{#f} if this information is not available. | |
9f17d967 | 295 | |
4dbac5e0 | 296 | For example: |
6fca8730 | 297 | |
4dbac5e0 AW |
298 | @example |
299 | (program-lambda-alist | |
300 | (lambda* (a b #:optional c #:key (d 1) #:rest e) | |
301 | #t)) @result{} | |
302 | @end example | |
6fca8730 | 303 | @end deffn |
00ce5125 | 304 | |
07d83abe MV |
305 | @node Optional Arguments |
306 | @subsection Optional Arguments | |
307 | ||
07d83abe MV |
308 | Scheme procedures, as defined in R5RS, can either handle a fixed number |
309 | of actual arguments, or a fixed number of actual arguments followed by | |
310 | arbitrarily many additional arguments. Writing procedures of variable | |
311 | arity can be useful, but unfortunately, the syntactic means for handling | |
312 | argument lists of varying length is a bit inconvenient. It is possible | |
f916cbc4 | 313 | to give names to the fixed number of arguments, but the remaining |
07d83abe MV |
314 | (optional) arguments can be only referenced as a list of values |
315 | (@pxref{Lambda}). | |
316 | ||
f916cbc4 AW |
317 | For this reason, Guile provides an extension to @code{lambda}, |
318 | @code{lambda*}, which allows the user to define procedures with | |
319 | optional and keyword arguments. In addition, Guile's virtual machine | |
320 | has low-level support for optional and keyword argument dispatch. | |
321 | Calls to procedures with optional and keyword arguments can be made | |
322 | cheaply, without allocating a rest list. | |
07d83abe MV |
323 | |
324 | @menu | |
f916cbc4 AW |
325 | * lambda* and define*:: Creating advanced argument handling procedures. |
326 | * ice-9 optargs:: (ice-9 optargs) provides some utilities. | |
07d83abe MV |
327 | @end menu |
328 | ||
329 | ||
f916cbc4 AW |
330 | @node lambda* and define* |
331 | @subsubsection lambda* and define*. | |
07d83abe | 332 | |
f916cbc4 AW |
333 | @code{lambda*} is like @code{lambda}, except with some extensions to |
334 | allow optional and keyword arguments. | |
07d83abe | 335 | |
edcd3e83 KR |
336 | @deffn {library syntax} lambda* ([var@dots{}] @* [#:optional vardef@dots{}] @* [#:key vardef@dots{} [#:allow-other-keys]] @* [#:rest var | . var]) @* body |
337 | @sp 1 | |
338 | Create a procedure which takes optional and/or keyword arguments | |
339 | specified with @code{#:optional} and @code{#:key}. For example, | |
07d83abe MV |
340 | |
341 | @lisp | |
342 | (lambda* (a b #:optional c d . e) '()) | |
343 | @end lisp | |
344 | ||
edcd3e83 KR |
345 | is a procedure with fixed arguments @var{a} and @var{b}, optional |
346 | arguments @var{c} and @var{d}, and rest argument @var{e}. If the | |
07d83abe MV |
347 | optional arguments are omitted in a call, the variables for them are |
348 | bound to @code{#f}. | |
349 | ||
f916cbc4 AW |
350 | @fnindex define* |
351 | Likewise, @code{define*} is syntactic sugar for defining procedures | |
352 | using @code{lambda*}. | |
353 | ||
354 | @code{lambda*} can also make procedures with keyword arguments. For | |
355 | example, a procedure defined like this: | |
07d83abe MV |
356 | |
357 | @lisp | |
f916cbc4 AW |
358 | (define* (sir-yes-sir #:key action how-high) |
359 | (list action how-high)) | |
07d83abe MV |
360 | @end lisp |
361 | ||
f916cbc4 AW |
362 | can be called as @code{(sir-yes-sir #:action 'jump)}, |
363 | @code{(sir-yes-sir #:how-high 13)}, @code{(sir-yes-sir #:action | |
364 | 'lay-down #:how-high 0)}, or just @code{(sir-yes-sir)}. Whichever | |
365 | arguments are given as keywords are bound to values (and those not | |
366 | given are @code{#f}). | |
07d83abe | 367 | |
edcd3e83 KR |
368 | Optional and keyword arguments can also have default values to take |
369 | when not present in a call, by giving a two-element list of variable | |
370 | name and expression. For example in | |
07d83abe MV |
371 | |
372 | @lisp | |
f916cbc4 AW |
373 | (define* (frob foo #:optional (bar 42) #:key (baz 73)) |
374 | (list foo bar baz)) | |
07d83abe MV |
375 | @end lisp |
376 | ||
377 | @var{foo} is a fixed argument, @var{bar} is an optional argument with | |
378 | default value 42, and baz is a keyword argument with default value 73. | |
edcd3e83 KR |
379 | Default value expressions are not evaluated unless they are needed, |
380 | and until the procedure is called. | |
07d83abe | 381 | |
edcd3e83 KR |
382 | Normally it's an error if a call has keywords other than those |
383 | specified by @code{#:key}, but adding @code{#:allow-other-keys} to the | |
384 | definition (after the keyword argument declarations) will ignore | |
385 | unknown keywords. | |
07d83abe | 386 | |
edcd3e83 KR |
387 | If a call has a keyword given twice, the last value is used. For |
388 | example, | |
07d83abe MV |
389 | |
390 | @lisp | |
f916cbc4 AW |
391 | (define* (flips #:key (heads 0) (tails 0)) |
392 | (display (list heads tails))) | |
393 | ||
394 | (flips #:heads 37 #:tails 42 #:heads 99) | |
edcd3e83 | 395 | @print{} (99 42) |
07d83abe MV |
396 | @end lisp |
397 | ||
edcd3e83 KR |
398 | @code{#:rest} is a synonym for the dotted syntax rest argument. The |
399 | argument lists @code{(a . b)} and @code{(a #:rest b)} are equivalent | |
400 | in all respects. This is provided for more similarity to DSSSL, | |
401 | MIT-Scheme and Kawa among others, as well as for refugees from other | |
402 | Lisp dialects. | |
403 | ||
404 | When @code{#:key} is used together with a rest argument, the keyword | |
405 | parameters in a call all remain in the rest list. This is the same as | |
406 | Common Lisp. For example, | |
07d83abe | 407 | |
edcd3e83 KR |
408 | @lisp |
409 | ((lambda* (#:key (x 0) #:allow-other-keys #:rest r) | |
410 | (display r)) | |
411 | #:x 123 #:y 456) | |
412 | @print{} (#:x 123 #:y 456) | |
413 | @end lisp | |
414 | ||
415 | @code{#:optional} and @code{#:key} establish their bindings | |
f916cbc4 AW |
416 | successively, from left to right. This means default expressions can |
417 | refer back to prior parameters, for example | |
edcd3e83 KR |
418 | |
419 | @lisp | |
420 | (lambda* (start #:optional (end (+ 10 start))) | |
421 | (do ((i start (1+ i))) | |
422 | ((> i end)) | |
423 | (display i))) | |
424 | @end lisp | |
f916cbc4 AW |
425 | |
426 | The exception to this left-to-right scoping rule is the rest argument. | |
427 | If there is a rest argument, it is bound after the optional arguments, | |
428 | but before the keyword arguments. | |
07d83abe MV |
429 | @end deffn |
430 | ||
431 | ||
f916cbc4 AW |
432 | @node ice-9 optargs |
433 | @subsubsection (ice-9 optargs) | |
07d83abe | 434 | |
f916cbc4 AW |
435 | Before Guile 2.0, @code{lambda*} and @code{define*} were implemented |
436 | using macros that processed rest list arguments. This was not optimal, | |
437 | as calling procedures with optional arguments had to allocate rest | |
438 | lists at every procedure invocation. Guile 2.0 improved this | |
439 | situation by bringing optional and keyword arguments into Guile's | |
440 | core. | |
07d83abe | 441 | |
f916cbc4 AW |
442 | However there are occasions in which you have a list and want to parse |
443 | it for optional or keyword arguments. Guile's @code{(ice-9 optargs)} | |
444 | provides some macros to help with that task. | |
07d83abe | 445 | |
f916cbc4 AW |
446 | The syntax @code{let-optional} and @code{let-optional*} are for |
447 | destructuring rest argument lists and giving names to the various list | |
448 | elements. @code{let-optional} binds all variables simultaneously, while | |
449 | @code{let-optional*} binds them sequentially, consistent with @code{let} | |
450 | and @code{let*} (@pxref{Local Bindings}). | |
451 | ||
df0a1002 BT |
452 | @deffn {library syntax} let-optional rest-arg (binding @dots{}) body1 body2 @dots{} |
453 | @deffnx {library syntax} let-optional* rest-arg (binding @dots{}) body1 body2 @dots{} | |
f916cbc4 AW |
454 | These two macros give you an optional argument interface that is very |
455 | @dfn{Schemey} and introduces no fancy syntax. They are compatible with | |
456 | the scsh macros of the same name, but are slightly extended. Each of | |
457 | @var{binding} may be of one of the forms @var{var} or @code{(@var{var} | |
458 | @var{default-value})}. @var{rest-arg} should be the rest-argument of the | |
459 | procedures these are used from. The items in @var{rest-arg} are | |
460 | sequentially bound to the variable names are given. When @var{rest-arg} | |
461 | runs out, the remaining vars are bound either to the default values or | |
462 | @code{#f} if no default value was specified. @var{rest-arg} remains | |
463 | bound to whatever may have been left of @var{rest-arg}. | |
07d83abe | 464 | |
df0a1002 BT |
465 | After binding the variables, the expressions @var{body1} @var{body2} @dots{} |
466 | are evaluated in order. | |
f916cbc4 | 467 | @end deffn |
07d83abe | 468 | |
f916cbc4 AW |
469 | Similarly, @code{let-keywords} and @code{let-keywords*} extract values |
470 | from keyword style argument lists, binding local variables to those | |
471 | values or to defaults. | |
07d83abe | 472 | |
df0a1002 BT |
473 | @deffn {library syntax} let-keywords args allow-other-keys? (binding @dots{}) body1 body2 @dots{} |
474 | @deffnx {library syntax} let-keywords* args allow-other-keys? (binding @dots{}) body1 body2 @dots{} | |
f916cbc4 AW |
475 | @var{args} is evaluated and should give a list of the form |
476 | @code{(#:keyword1 value1 #:keyword2 value2 @dots{})}. The | |
df0a1002 BT |
477 | @var{binding}s are variables and default expressions, with the variables |
478 | to be set (by name) from the keyword values. The @var{body1} | |
479 | @var{body2} @dots{} forms are then evaluated and the last is the | |
480 | result. An example will make the syntax clearest, | |
f916cbc4 AW |
481 | |
482 | @example | |
483 | (define args '(#:xyzzy "hello" #:foo "world")) | |
07d83abe | 484 | |
f916cbc4 AW |
485 | (let-keywords args #t |
486 | ((foo "default for foo") | |
487 | (bar (string-append "default" "for" "bar"))) | |
488 | (display foo) | |
489 | (display ", ") | |
490 | (display bar)) | |
491 | @print{} world, defaultforbar | |
492 | @end example | |
07d83abe | 493 | |
f916cbc4 AW |
494 | The binding for @code{foo} comes from the @code{#:foo} keyword in |
495 | @code{args}. But the binding for @code{bar} is the default in the | |
496 | @code{let-keywords}, since there's no @code{#:bar} in the args. | |
497 | ||
498 | @var{allow-other-keys?} is evaluated and controls whether unknown | |
499 | keywords are allowed in the @var{args} list. When true other keys are | |
500 | ignored (such as @code{#:xyzzy} in the example), when @code{#f} an | |
501 | error is thrown for anything unknown. | |
502 | @end deffn | |
503 | ||
504 | @code{(ice-9 optargs)} also provides some more @code{define*} sugar, | |
505 | which is not so useful with modern Guile coding, but still supported: | |
506 | @code{define*-public} is the @code{lambda*} version of | |
507 | @code{define-public}; @code{defmacro*} and @code{defmacro*-public} | |
508 | exist for defining macros with the improved argument list handling | |
509 | possibilities. The @code{-public} versions not only define the | |
510 | procedures/macros, but also export them from the current module. | |
511 | ||
df0a1002 | 512 | @deffn {library syntax} define*-public formals body1 body2 @dots{} |
f916cbc4 | 513 | Like a mix of @code{define*} and @code{define-public}. |
07d83abe MV |
514 | @end deffn |
515 | ||
df0a1002 BT |
516 | @deffn {library syntax} defmacro* name formals body1 body2 @dots{} |
517 | @deffnx {library syntax} defmacro*-public name formals body1 body2 @dots{} | |
07d83abe MV |
518 | These are just like @code{defmacro} and @code{defmacro-public} except that they |
519 | take @code{lambda*}-style extended parameter lists, where @code{#:optional}, | |
520 | @code{#:key}, @code{#:allow-other-keys} and @code{#:rest} are allowed with the usual | |
521 | semantics. Here is an example of a macro with an optional argument: | |
522 | ||
523 | @lisp | |
ecb87335 | 524 | (defmacro* transmogrify (a #:optional b) |
f916cbc4 | 525 | (a 1)) |
07d83abe MV |
526 | @end lisp |
527 | @end deffn | |
528 | ||
f916cbc4 AW |
529 | @node Case-lambda |
530 | @subsection Case-lambda | |
531 | @cindex SRFI-16 | |
532 | @cindex variable arity | |
533 | @cindex arity, variable | |
534 | ||
535 | R5RS's rest arguments are indeed useful and very general, but they | |
536 | often aren't the most appropriate or efficient means to get the job | |
537 | done. For example, @code{lambda*} is a much better solution to the | |
538 | optional argument problem than @code{lambda} with rest arguments. | |
539 | ||
540 | @fnindex case-lambda | |
541 | Likewise, @code{case-lambda} works well for when you want one | |
542 | procedure to do double duty (or triple, or ...), without the penalty | |
543 | of consing a rest list. | |
544 | ||
545 | For example: | |
546 | ||
547 | @lisp | |
548 | (define (make-accum n) | |
549 | (case-lambda | |
550 | (() n) | |
551 | ((m) (set! n (+ n m)) n))) | |
552 | ||
553 | (define a (make-accum 20)) | |
554 | (a) @result{} 20 | |
555 | (a 10) @result{} 30 | |
556 | (a) @result{} 30 | |
557 | @end lisp | |
558 | ||
559 | The value returned by a @code{case-lambda} form is a procedure which | |
560 | matches the number of actual arguments against the formals in the | |
561 | various clauses, in order. The first matching clause is selected, the | |
562 | corresponding values from the actual parameter list are bound to the | |
563 | variable names in the clauses and the body of the clause is evaluated. | |
564 | If no clause matches, an error is signalled. | |
565 | ||
566 | The syntax of the @code{case-lambda} form is defined in the following | |
567 | EBNF grammar. @dfn{Formals} means a formal argument list just like | |
568 | with @code{lambda} (@pxref{Lambda}). | |
569 | ||
570 | @example | |
571 | @group | |
572 | <case-lambda> | |
573 | --> (case-lambda <case-lambda-clause>) | |
574 | <case-lambda-clause> | |
575 | --> (<formals> <definition-or-command>*) | |
576 | <formals> | |
577 | --> (<identifier>*) | |
578 | | (<identifier>* . <identifier>) | |
579 | | <identifier> | |
580 | @end group | |
581 | @end example | |
582 | ||
583 | Rest lists can be useful with @code{case-lambda}: | |
584 | ||
585 | @lisp | |
586 | (define plus | |
587 | (case-lambda | |
588 | (() 0) | |
589 | ((a) a) | |
590 | ((a b) (+ a b)) | |
591 | ((a b . rest) (apply plus (+ a b) rest)))) | |
592 | (plus 1 2 3) @result{} 6 | |
593 | @end lisp | |
594 | ||
595 | @fnindex case-lambda* | |
596 | Also, for completeness. Guile defines @code{case-lambda*} as well, | |
597 | which is like @code{case-lambda}, except with @code{lambda*} clauses. | |
598 | A @code{case-lambda*} clause matches if the arguments fill the | |
599 | required arguments, but are not too many for the optional and/or rest | |
600 | arguments. | |
601 | ||
581f410f AW |
602 | Keyword arguments are possible with @code{case-lambda*} as well, but |
603 | they do not contribute to the ``matching'' behavior, and their | |
604 | interactions with required, optional, and rest arguments can be | |
605 | surprising. | |
606 | ||
607 | For the purposes of @code{case-lambda*} (and of @code{case-lambda}, as a | |
608 | special case), a clause @dfn{matches} if it has enough required | |
609 | arguments, and not too many positional arguments. The required | |
610 | arguments are any arguments before the @code{#:optional}, @code{#:key}, | |
611 | and @code{#:rest} arguments. @dfn{Positional} arguments are the | |
612 | required arguments, together with the optional arguments. | |
613 | ||
614 | In the absence of @code{#:key} or @code{#:rest} arguments, it's easy to | |
615 | see how there could be too many positional arguments: you pass 5 | |
616 | arguments to a function that only takes 4 arguments, including optional | |
617 | arguments. If there is a @code{#:rest} argument, there can never be too | |
618 | many positional arguments: any application with enough required | |
619 | arguments for a clause will match that clause, even if there are also | |
620 | @code{#:key} arguments. | |
621 | ||
622 | Otherwise, for applications to a clause with @code{#:key} arguments (and | |
623 | without a @code{#:rest} argument), a clause will match there only if | |
624 | there are enough required arguments and if the next argument after | |
625 | binding required and optional arguments, if any, is a keyword. For | |
626 | efficiency reasons, Guile is currently unable to include keyword | |
627 | arguments in the matching algorithm. Clauses match on positional | |
628 | arguments only, not by comparing a given keyword to the available set of | |
629 | keyword arguments that a function has. | |
630 | ||
631 | Some examples follow. | |
632 | ||
633 | @example | |
634 | (define f | |
635 | (case-lambda* | |
636 | ((a #:optional b) 'clause-1) | |
637 | ((a #:optional b #:key c) 'clause-2) | |
638 | ((a #:key d) 'clause-3) | |
639 | ((#:key e #:rest f) 'clause-4))) | |
640 | ||
641 | (f) @result{} clause-4 | |
642 | (f 1) @result{} clause-1 | |
643 | (f) @result{} clause-4 | |
644 | (f #:e 10) clause-1 | |
645 | (f 1 #:foo) clause-1 | |
646 | (f 1 #:c 2) clause-2 | |
647 | (f #:a #:b #:c #:d #:e) clause-4 | |
648 | ||
649 | ;; clause-2 will match anything that clause-3 would match. | |
650 | (f 1 #:d 2) @result{} error: bad keyword args in clause 2 | |
651 | @end example | |
652 | ||
653 | Don't forget that the clauses are matched in order, and the first | |
654 | matching clause will be taken. This can result in a keyword being bound | |
655 | to a required argument, as in the case of @code{f #:e 10}. | |
656 | ||
07d83abe | 657 | |
18f06db9 LC |
658 | @node Higher-Order Functions |
659 | @subsection Higher-Order Functions | |
660 | ||
661 | @cindex higher-order functions | |
662 | ||
663 | As a functional programming language, Scheme allows the definition of | |
664 | @dfn{higher-order functions}, i.e., functions that take functions as | |
665 | arguments and/or return functions. Utilities to derive procedures from | |
666 | other procedures are provided and described below. | |
667 | ||
668 | @deffn {Scheme Procedure} const value | |
669 | Return a procedure that accepts any number of arguments and returns | |
670 | @var{value}. | |
671 | ||
672 | @lisp | |
673 | (procedure? (const 3)) @result{} #t | |
674 | ((const 'hello)) @result{} hello | |
675 | ((const 'hello) 'world) @result{} hello | |
676 | @end lisp | |
677 | @end deffn | |
678 | ||
679 | @deffn {Scheme Procedure} negate proc | |
680 | Return a procedure with the same arity as @var{proc} that returns the | |
681 | @code{not} of @var{proc}'s result. | |
682 | ||
683 | @lisp | |
684 | (procedure? (negate number?)) @result{} #t | |
685 | ((negate odd?) 2) @result{} #t | |
686 | ((negate real?) 'dream) @result{} #t | |
687 | ((negate string-prefix?) "GNU" "GNU Guile") | |
688 | @result{} #f | |
689 | (filter (negate number?) '(a 2 "b")) | |
690 | @result{} (a "b") | |
691 | @end lisp | |
692 | @end deffn | |
693 | ||
df0a1002 BT |
694 | @deffn {Scheme Procedure} compose proc1 proc2 @dots{} |
695 | Compose @var{proc1} with the procedures @var{proc2} @dots{} such that | |
696 | the last @var{proc} argument is applied first and @var{proc1} last, and | |
697 | return the resulting procedure. The given procedures must have | |
698 | compatible arity. | |
18f06db9 LC |
699 | |
700 | @lisp | |
701 | (procedure? (compose 1+ 1-)) @result{} #t | |
702 | ((compose sqrt 1+ 1+) 2) @result{} 2.0 | |
703 | ((compose 1+ sqrt) 3) @result{} 2.73205080756888 | |
704 | (eq? (compose 1+) 1+) @result{} #t | |
705 | ||
706 | ((compose zip unzip2) '((1 2) (a b))) | |
707 | @result{} ((1 2) (a b)) | |
708 | @end lisp | |
709 | @end deffn | |
710 | ||
711 | @deffn {Scheme Procedure} identity x | |
712 | Return X. | |
713 | @end deffn | |
714 | ||
07d83abe MV |
715 | @node Procedure Properties |
716 | @subsection Procedure Properties and Meta-information | |
717 | ||
f916cbc4 AW |
718 | In addition to the information that is strictly necessary to run, |
719 | procedures may have other associated information. For example, the | |
720 | name of a procedure is information not for the procedure, but about | |
721 | the procedure. This meta-information can be accessed via the procedure | |
722 | properties interface. | |
07d83abe | 723 | |
f916cbc4 AW |
724 | The first group of procedures in this meta-interface are predicates to |
725 | test whether a Scheme object is a procedure, or a special procedure, | |
bd5dea48 LC |
726 | respectively. @code{procedure?} is the most general predicates, it |
727 | returns @code{#t} for any kind of procedure. | |
07d83abe MV |
728 | |
729 | @rnindex procedure? | |
730 | @deffn {Scheme Procedure} procedure? obj | |
731 | @deffnx {C Function} scm_procedure_p (obj) | |
732 | Return @code{#t} if @var{obj} is a procedure. | |
733 | @end deffn | |
734 | ||
07d83abe MV |
735 | @deffn {Scheme Procedure} thunk? obj |
736 | @deffnx {C Function} scm_thunk_p (obj) | |
bd5dea48 LC |
737 | Return @code{#t} if @var{obj} is a thunk---a procedure that does |
738 | not accept arguments. | |
07d83abe MV |
739 | @end deffn |
740 | ||
07d83abe | 741 | @cindex procedure properties |
f916cbc4 AW |
742 | Procedure properties are general properties associated with |
743 | procedures. These can be the name of a procedure or other relevant | |
07d83abe MV |
744 | information, such as debug hints. |
745 | ||
746 | @deffn {Scheme Procedure} procedure-name proc | |
747 | @deffnx {C Function} scm_procedure_name (proc) | |
748 | Return the name of the procedure @var{proc} | |
749 | @end deffn | |
750 | ||
751 | @deffn {Scheme Procedure} procedure-source proc | |
752 | @deffnx {C Function} scm_procedure_source (proc) | |
f916cbc4 AW |
753 | Return the source of the procedure @var{proc}. Returns @code{#f} if |
754 | the source code is not available. | |
07d83abe MV |
755 | @end deffn |
756 | ||
07d83abe MV |
757 | @deffn {Scheme Procedure} procedure-properties proc |
758 | @deffnx {C Function} scm_procedure_properties (proc) | |
f916cbc4 AW |
759 | Return the properties associated with @var{proc}, as an association |
760 | list. | |
07d83abe MV |
761 | @end deffn |
762 | ||
f916cbc4 AW |
763 | @deffn {Scheme Procedure} procedure-property proc key |
764 | @deffnx {C Function} scm_procedure_property (proc, key) | |
765 | Return the property of @var{proc} with name @var{key}. | |
07d83abe MV |
766 | @end deffn |
767 | ||
768 | @deffn {Scheme Procedure} set-procedure-properties! proc alist | |
769 | @deffnx {C Function} scm_set_procedure_properties_x (proc, alist) | |
f916cbc4 | 770 | Set @var{proc}'s property list to @var{alist}. |
07d83abe MV |
771 | @end deffn |
772 | ||
f916cbc4 AW |
773 | @deffn {Scheme Procedure} set-procedure-property! proc key value |
774 | @deffnx {C Function} scm_set_procedure_property_x (proc, key, value) | |
775 | In @var{proc}'s property list, set the property named @var{key} to | |
07d83abe MV |
776 | @var{value}. |
777 | @end deffn | |
778 | ||
779 | @cindex procedure documentation | |
780 | Documentation for a procedure can be accessed with the procedure | |
781 | @code{procedure-documentation}. | |
782 | ||
783 | @deffn {Scheme Procedure} procedure-documentation proc | |
784 | @deffnx {C Function} scm_procedure_documentation (proc) | |
785 | Return the documentation string associated with @code{proc}. By | |
786 | convention, if a procedure contains more than one expression and the | |
787 | first expression is a string constant, that string is assumed to contain | |
788 | documentation for that procedure. | |
789 | @end deffn | |
790 | ||
07d83abe MV |
791 | |
792 | @node Procedures with Setters | |
793 | @subsection Procedures with Setters | |
794 | ||
795 | @c FIXME::martin: Review me! | |
796 | ||
797 | @c FIXME::martin: Document `operator struct'. | |
798 | ||
799 | @cindex procedure with setter | |
800 | @cindex setter | |
801 | A @dfn{procedure with setter} is a special kind of procedure which | |
802 | normally behaves like any accessor procedure, that is a procedure which | |
803 | accesses a data structure. The difference is that this kind of | |
804 | procedure has a so-called @dfn{setter} attached, which is a procedure | |
805 | for storing something into a data structure. | |
806 | ||
807 | Procedures with setters are treated specially when the procedure appears | |
808 | in the special form @code{set!} (REFFIXME). How it works is best shown | |
809 | by example. | |
810 | ||
811 | Suppose we have a procedure called @code{foo-ref}, which accepts two | |
812 | arguments, a value of type @code{foo} and an integer. The procedure | |
813 | returns the value stored at the given index in the @code{foo} object. | |
814 | Let @code{f} be a variable containing such a @code{foo} data | |
815 | structure.@footnote{Working definitions would be: | |
816 | @lisp | |
817 | (define foo-ref vector-ref) | |
818 | (define foo-set! vector-set!) | |
819 | (define f (make-vector 2 #f)) | |
820 | @end lisp | |
821 | } | |
822 | ||
823 | @lisp | |
824 | (foo-ref f 0) @result{} bar | |
825 | (foo-ref f 1) @result{} braz | |
826 | @end lisp | |
827 | ||
828 | Also suppose that a corresponding setter procedure called | |
829 | @code{foo-set!} does exist. | |
830 | ||
831 | @lisp | |
832 | (foo-set! f 0 'bla) | |
833 | (foo-ref f 0) @result{} bla | |
834 | @end lisp | |
835 | ||
836 | Now we could create a new procedure called @code{foo}, which is a | |
837 | procedure with setter, by calling @code{make-procedure-with-setter} with | |
838 | the accessor and setter procedures @code{foo-ref} and @code{foo-set!}. | |
839 | Let us call this new procedure @code{foo}. | |
840 | ||
841 | @lisp | |
842 | (define foo (make-procedure-with-setter foo-ref foo-set!)) | |
843 | @end lisp | |
844 | ||
845 | @code{foo} can from now an be used to either read from the data | |
846 | structure stored in @code{f}, or to write into the structure. | |
847 | ||
848 | @lisp | |
849 | (set! (foo f 0) 'dum) | |
850 | (foo f 0) @result{} dum | |
851 | @end lisp | |
852 | ||
853 | @deffn {Scheme Procedure} make-procedure-with-setter procedure setter | |
854 | @deffnx {C Function} scm_make_procedure_with_setter (procedure, setter) | |
855 | Create a new procedure which behaves like @var{procedure}, but | |
856 | with the associated setter @var{setter}. | |
857 | @end deffn | |
858 | ||
859 | @deffn {Scheme Procedure} procedure-with-setter? obj | |
860 | @deffnx {C Function} scm_procedure_with_setter_p (obj) | |
861 | Return @code{#t} if @var{obj} is a procedure with an | |
862 | associated setter procedure. | |
863 | @end deffn | |
864 | ||
865 | @deffn {Scheme Procedure} procedure proc | |
866 | @deffnx {C Function} scm_procedure (proc) | |
3323ec06 NJ |
867 | Return the procedure of @var{proc}, which must be an |
868 | applicable struct. | |
07d83abe MV |
869 | @end deffn |
870 | ||
871 | @deffn {Scheme Procedure} setter proc | |
872 | Return the setter of @var{proc}, which must be either a procedure with | |
873 | setter or an operator struct. | |
874 | @end deffn | |
875 | ||
165b10dd AR |
876 | @node Inlinable Procedures |
877 | @subsection Inlinable Procedures | |
878 | ||
43e53d64 LC |
879 | @cindex inlining |
880 | @cindex procedure inlining | |
165b10dd AR |
881 | You can define an @dfn{inlinable procedure} by using |
882 | @code{define-inlinable} instead of @code{define}. An inlinable | |
883 | procedure behaves the same as a regular procedure, but direct calls will | |
884 | result in the procedure body being inlined into the caller. | |
885 | ||
43e53d64 LC |
886 | @cindex partial evaluator |
887 | Bear in mind that starting from version 2.0.3, Guile has a partial | |
888 | evaluator that can inline the body of inner procedures when deemed | |
889 | appropriate: | |
890 | ||
891 | @example | |
892 | scheme@@(guile-user)> ,optimize (define (foo x) | |
893 | (define (bar) (+ x 3)) | |
894 | (* (bar) 2)) | |
895 | $1 = (define foo | |
896 | (lambda (#@{x 94@}#) (* (+ #@{x 94@}# 3) 2))) | |
897 | @end example | |
898 | ||
899 | @noindent | |
900 | The partial evaluator does not inline top-level bindings, though, so | |
901 | this is a situation where you may find it interesting to use | |
902 | @code{define-inlinable}. | |
903 | ||
165b10dd AR |
904 | Procedures defined with @code{define-inlinable} are @emph{always} |
905 | inlined, at all direct call sites. This eliminates function call | |
906 | overhead at the expense of an increase in code size. Additionally, the | |
907 | caller will not transparently use the new definition if the inline | |
908 | procedure is redefined. It is not possible to trace an inlined | |
909 | procedures or install a breakpoint in it (@pxref{Traps}). For these | |
910 | reasons, you should not make a procedure inlinable unless it | |
911 | demonstrably improves performance in a crucial way. | |
912 | ||
913 | In general, only small procedures should be considered for inlining, as | |
914 | making large procedures inlinable will probably result in an increase in | |
915 | code size. Additionally, the elimination of the call overhead rarely | |
b3da54d1 | 916 | matters for large procedures. |
165b10dd | 917 | |
df0a1002 | 918 | @deffn {Scheme Syntax} define-inlinable (name parameter @dots{}) body1 body2 @dots{} |
165b10dd | 919 | Define @var{name} as a procedure with parameters @var{parameter}s and |
df0a1002 | 920 | bodies @var{body1}, @var{body2}, @enddots{}. |
165b10dd | 921 | @end deffn |
07d83abe | 922 | |
07d83abe MV |
923 | @c Local Variables: |
924 | @c TeX-master: "guile.texi" | |
925 | @c End: |