2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2010,
4 @c 2011, 2012, 2013 Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
11 * Lambda:: Basic procedure creation using lambda.
12 * Primitive Procedures:: Procedures defined in C.
13 * Compiled Procedures:: Scheme procedures can be compiled.
14 * Optional Arguments:: Handling keyword, optional and rest arguments.
15 * Case-lambda:: One function, multiple arities.
16 * Higher-Order Functions:: Function that take or return functions.
17 * Procedure Properties:: Procedure properties and meta-information.
18 * Procedures with Setters:: Procedures with setters.
19 * Inlinable Procedures:: Procedures that can be inlined.
24 @subsection Lambda: Basic Procedure Creation
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}).
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
36 the @code{lambda} expression is evaluated sequentially. The result of
37 the last expression in the procedure body is then the result of the
40 The following examples will show how procedures can be created using
41 @code{lambda}, and what you can do with these procedures.
44 (lambda (x) (+ x x)) @result{} @r{a procedure}
45 ((lambda (x) (+ x x)) 4) @result{} 8
48 The fact that the environment in effect when creating a procedure is
49 enclosed in the procedure is shown with this example:
54 (lambda (y) (+ x y))))
59 @deffn syntax lambda formals body
60 @var{formals} should be a formal argument list as described in the
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
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.
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}).
90 @var{body} is a sequence of Scheme expressions which are evaluated in
91 order when the procedure is invoked.
94 @node Primitive Procedures
95 @subsection Primitive Procedures
97 @cindex primitive procedures
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}).
105 @deftypefun SCM scm_c_make_gsubr (const char *name, int req, int opt, int rst, fcn)
106 Register a C procedure @var{fcn} as a ``subr'' --- a primitive
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
112 to @var{fcn}, but may not exceed 10. The number of rest arguments should be 0 or 1.
113 @code{scm_c_make_gsubr} returns a value of type @code{SCM} which is a
114 ``handle'' for the procedure.
117 @deftypefun SCM scm_c_define_gsubr (const char *name, int req, int opt, int rst, fcn)
118 Register a C procedure @var{fcn}, as for @code{scm_c_make_gsubr}
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
126 @node Compiled Procedures
127 @subsection Compiled Procedures
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.
134 Most procedures are compiled, however. This means that Guile has done
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.
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.
146 Compiled procedures, also known as @dfn{programs}, respond all
147 procedures that operate on procedures. In addition, there are a few
148 more accessors for low-level details on programs.
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:
155 (use-modules (system vm program))
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.
163 @deffn {Scheme Procedure} program-objcode program
164 @deffnx {C Function} scm_program_objcode (program)
165 Returns the object code associated with this program. @xref{Bytecode
166 and Objcode}, for more information.
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.
175 @deffn {Scheme Procedure} program-module program
176 @deffnx {C Function} scm_program_module (program)
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
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}.
189 Some of the values captured are actually in variable ``boxes''.
190 @xref{Variables and the VM}, for more information.
192 Users must not modify the returned value unless they think they're
196 @deffn {Scheme Procedure} program-meta program
197 @deffnx {C Function} scm_program_meta (program)
198 Return the metadata thunk of @var{program}, or @code{#f} if it has no
201 When called, a metadata thunk returns a list of the following form:
202 @code{(@var{bindings} @var{sources} @var{arities} . @var{properties})}. The format
203 of each of these elements is discussed below.
206 @deffn {Scheme Procedure} program-bindings program
207 @deffnx {Scheme Procedure} make-binding name boxed? index start end
208 @deffnx {Scheme Procedure} binding:name binding
209 @deffnx {Scheme Procedure} binding:boxed? binding
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.
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
217 REPL. @xref{VM Concepts}, for more information.
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.
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.
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.
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.
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.
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
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.
273 @deffn {Scheme Procedure} program-arguments-alist program [ip]
274 Return an association list describing the arguments that @var{program} accepts, or
275 @code{#f} if the information cannot be obtained.
277 The alist keys that are currently defined are `required', `optional',
278 `keyword', `allow-other-keys?', and `rest'. For example:
281 (program-arguments-alist
282 (lambda* (a b #:optional c #:key (d 1) #:rest e)
286 (keyword . ((#:d . 4)))
287 (allow-other-keys? . #f)
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.
299 (program-lambda-alist
300 (lambda* (a b #:optional c #:key (d 1) #:rest e)
305 @node Optional Arguments
306 @subsection Optional Arguments
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
313 to give names to the fixed number of arguments, but the remaining
314 (optional) arguments can be only referenced as a list of values
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.
325 * lambda* and define*:: Creating advanced argument handling procedures.
326 * ice-9 optargs:: (ice-9 optargs) provides some utilities.
330 @node lambda* and define*
331 @subsubsection lambda* and define*.
333 @code{lambda*} is like @code{lambda}, except with some extensions to
334 allow optional and keyword arguments.
336 @deffn {library syntax} lambda* ([var@dots{}] @* [#:optional vardef@dots{}] @* [#:key vardef@dots{} [#:allow-other-keys]] @* [#:rest var | . var]) @* body
338 Create a procedure which takes optional and/or keyword arguments
339 specified with @code{#:optional} and @code{#:key}. For example,
342 (lambda* (a b #:optional c d . e) '())
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
347 optional arguments are omitted in a call, the variables for them are
351 Likewise, @code{define*} is syntactic sugar for defining procedures
352 using @code{lambda*}.
354 @code{lambda*} can also make procedures with keyword arguments. For
355 example, a procedure defined like this:
358 (define* (sir-yes-sir #:key action how-high)
359 (list action how-high))
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}).
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
373 (define* (frob foo #:optional (bar 42) #:key (baz 73))
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.
379 Default value expressions are not evaluated unless they are needed,
380 and until the procedure is called.
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
387 If a call has a keyword given twice, the last value is used. For
391 (define* (flips #:key (heads 0) (tails 0))
392 (display (list heads tails)))
394 (flips #:heads 37 #:tails 42 #:heads 99)
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
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,
409 ((lambda* (#:key (x 0) #:allow-other-keys #:rest r)
412 @print{} (#:x 123 #:y 456)
415 @code{#:optional} and @code{#:key} establish their bindings
416 successively, from left to right. This means default expressions can
417 refer back to prior parameters, for example
420 (lambda* (start #:optional (end (+ 10 start)))
421 (do ((i start (1+ i)))
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.
433 @subsubsection (ice-9 optargs)
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
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.
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}).
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{}
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}.
465 After binding the variables, the expressions @var{body1} @var{body2} @dots{}
466 are evaluated in order.
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.
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{}
475 @var{args} is evaluated and should give a list of the form
476 @code{(#:keyword1 value1 #:keyword2 value2 @dots{})}. The
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,
483 (define args '(#:xyzzy "hello" #:foo "world"))
485 (let-keywords args #t
486 ((foo "default for foo")
487 (bar (string-append "default" "for" "bar")))
491 @print{} world, defaultforbar
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.
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.
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.
512 @deffn {library syntax} define*-public formals body1 body2 @dots{}
513 Like a mix of @code{define*} and @code{define-public}.
516 @deffn {library syntax} defmacro* name formals body1 body2 @dots{}
517 @deffnx {library syntax} defmacro*-public name formals body1 body2 @dots{}
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:
524 (defmacro* transmogrify (a #:optional b)
530 @subsection Case-lambda
532 @cindex variable arity
533 @cindex arity, variable
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.
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.
548 (define (make-accum n)
551 ((m) (set! n (+ n m)) n)))
553 (define a (make-accum 20))
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.
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}).
573 --> (case-lambda <case-lambda-clause>)
575 --> (<formals> <definition-or-command>*)
578 | (<identifier>* . <identifier>)
583 Rest lists can be useful with @code{case-lambda}:
591 ((a b . rest) (apply plus (+ a b) rest))))
592 (plus 1 2 3) @result{} 6
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
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
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.
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.
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.
631 Some examples follow.
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)))
641 (f) @result{} clause-4
642 (f 1) @result{} clause-1
643 (f) @result{} clause-4
647 (f #:a #:b #:c #:d #:e) clause-4
649 ;; clause-2 will match anything that clause-3 would match.
650 (f 1 #:d 2) @result{} error: bad keyword args in clause 2
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}.
658 @node Higher-Order Functions
659 @subsection Higher-Order Functions
661 @cindex higher-order functions
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.
668 @deffn {Scheme Procedure} const value
669 Return a procedure that accepts any number of arguments and returns
673 (procedure? (const 3)) @result{} #t
674 ((const 'hello)) @result{} hello
675 ((const 'hello) 'world) @result{} hello
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.
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")
689 (filter (negate number?) '(a 2 "b"))
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
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
706 ((compose zip unzip2) '((1 2) (a b)))
707 @result{} ((1 2) (a b))
711 @deffn {Scheme Procedure} identity x
715 @node Procedure Properties
716 @subsection Procedure Properties and Meta-information
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.
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,
726 respectively. @code{procedure?} is the most general predicates, it
727 returns @code{#t} for any kind of 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.
735 @deffn {Scheme Procedure} thunk? obj
736 @deffnx {C Function} scm_thunk_p (obj)
737 Return @code{#t} if @var{obj} is a thunk---a procedure that does
738 not accept arguments.
741 @cindex procedure properties
742 Procedure properties are general properties associated with
743 procedures. These can be the name of a procedure or other relevant
744 information, such as debug hints.
746 @deffn {Scheme Procedure} procedure-name proc
747 @deffnx {C Function} scm_procedure_name (proc)
748 Return the name of the procedure @var{proc}
751 @deffn {Scheme Procedure} procedure-source proc
752 @deffnx {C Function} scm_procedure_source (proc)
753 Return the source of the procedure @var{proc}. Returns @code{#f} if
754 the source code is not available.
757 @deffn {Scheme Procedure} procedure-properties proc
758 @deffnx {C Function} scm_procedure_properties (proc)
759 Return the properties associated with @var{proc}, as an association
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}.
768 @deffn {Scheme Procedure} set-procedure-properties! proc alist
769 @deffnx {C Function} scm_set_procedure_properties_x (proc, alist)
770 Set @var{proc}'s property list to @var{alist}.
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
779 @cindex procedure documentation
780 Documentation for a procedure can be accessed with the procedure
781 @code{procedure-documentation}.
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.
792 @node Procedures with Setters
793 @subsection Procedures with Setters
795 @c FIXME::martin: Review me!
797 @c FIXME::martin: Document `operator struct'.
799 @cindex procedure with 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.
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
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:
817 (define foo-ref vector-ref)
818 (define foo-set! vector-set!)
819 (define f (make-vector 2 #f))
824 (foo-ref f 0) @result{} bar
825 (foo-ref f 1) @result{} braz
828 Also suppose that a corresponding setter procedure called
829 @code{foo-set!} does exist.
833 (foo-ref f 0) @result{} bla
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}.
842 (define foo (make-procedure-with-setter foo-ref foo-set!))
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.
849 (set! (foo f 0) 'dum)
850 (foo f 0) @result{} dum
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}.
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.
865 @deffn {Scheme Procedure} procedure proc
866 @deffnx {C Function} scm_procedure (proc)
867 Return the procedure of @var{proc}, which must be an
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.
876 @node Inlinable Procedures
877 @subsection Inlinable Procedures
880 @cindex procedure inlining
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.
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
892 scheme@@(guile-user)> ,optimize (define (foo x)
893 (define (bar) (+ x 3))
896 (lambda (#@{x 94@}#) (* (+ #@{x 94@}# 3) 2)))
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}.
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.
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
916 matters for large procedures.
918 @deffn {Scheme Syntax} define-inlinable (name parameter @dots{}) body1 body2 @dots{}
919 Define @var{name} as a procedure with parameters @var{parameter}s and
920 bodies @var{body1}, @var{body2}, @enddots{}.
924 @c TeX-master: "guile.texi"