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} if @var{obj} is a compiled procedure, or @code{#f}
164 @deffn {Scheme Procedure} program-code program
165 @deffnx {C Function} scm_program_code (program)
166 Returns the address of the program's entry, as an integer. This address
167 is mostly useful to procedures in @code{(system vm debug)}.
170 @deffn {Scheme Procedure} program-num-free-variable program
171 @deffnx {C Function} scm_program_num_free_variables (program)
172 Return the number of free variables captured by this program.
175 @deffn {Scheme Procedure} program-free-variable-ref program n
176 @deffnx {C Function} scm_program_free_variable-ref (program, n)
177 @deffnx {Scheme Procedure} program-free-variable-set! program n val
178 @deffnx {C Function} scm_program_free_variable_set_x (program, n, val)
179 Accessors for a program's free variables. Some of the values captured
180 are actually in variable ``boxes''. @xref{Variables and the VM}, for
183 Users must not modify the returned value unless they think they're
189 @deffn {Scheme Procedure} program-bindings program
190 @deffnx {Scheme Procedure} make-binding name boxed? index start end
191 @deffnx {Scheme Procedure} binding:name binding
192 @deffnx {Scheme Procedure} binding:boxed? binding
193 @deffnx {Scheme Procedure} binding:index binding
194 @deffnx {Scheme Procedure} binding:start binding
195 @deffnx {Scheme Procedure} binding:end binding
196 Bindings annotations for programs, along with their accessors.
198 Bindings declare names and liveness extents for block-local variables.
199 The best way to see what these are is to play around with them at a
200 REPL. @xref{VM Concepts}, for more information.
202 Note that bindings information is stored in a program as part of its
203 metadata thunk, so including it in the generated object code does not
204 impose a runtime performance penalty.
207 @deffn {Scheme Procedure} program-sources program
208 @deffnx {Scheme Procedure} source:addr source
209 @deffnx {Scheme Procedure} source:line source
210 @deffnx {Scheme Procedure} source:column source
211 @deffnx {Scheme Procedure} source:file source
212 Source location annotations for programs, along with their accessors.
214 Source location information propagates through the compiler and ends
215 up being serialized to the program's metadata. This information is
216 keyed by the offset of the instruction pointer within the object code
217 of the program. Specifically, it is keyed on the @code{ip} @emph{just
218 following} an instruction, so that backtraces can find the source
219 location of a call that is in progress.
222 @deffn {Scheme Procedure} program-arities program
223 @deffnx {C Function} scm_program_arities (program)
224 @deffnx {Scheme Procedure} program-arity program ip
225 @deffnx {Scheme Procedure} arity:start arity
226 @deffnx {Scheme Procedure} arity:end arity
227 @deffnx {Scheme Procedure} arity:nreq arity
228 @deffnx {Scheme Procedure} arity:nopt arity
229 @deffnx {Scheme Procedure} arity:rest? arity
230 @deffnx {Scheme Procedure} arity:kw arity
231 @deffnx {Scheme Procedure} arity:allow-other-keys? arity
232 Accessors for a representation of the ``arity'' of a program.
234 The normal case is that a procedure has one arity. For example,
235 @code{(lambda (x) x)}, takes one required argument, and that's it. One
236 could access that number of required arguments via @code{(arity:nreq
237 (program-arities (lambda (x) x)))}. Similarly, @code{arity:nopt} gets
238 the number of optional arguments, and @code{arity:rest?} returns a true
239 value if the procedure has a rest arg.
241 @code{arity:kw} returns a list of @code{(@var{kw} . @var{idx})} pairs,
242 if the procedure has keyword arguments. The @var{idx} refers to the
243 @var{idx}th local variable; @xref{Variables and the VM}, for more
244 information. Finally @code{arity:allow-other-keys?} returns a true
245 value if other keys are allowed. @xref{Optional Arguments}, for more
248 So what about @code{arity:start} and @code{arity:end}, then? They
249 return the range of bytes in the program's bytecode for which a given
250 arity is valid. You see, a procedure can actually have more than one
251 arity. The question, ``what is a procedure's arity'' only really makes
252 sense at certain points in the program, delimited by these
253 @code{arity:start} and @code{arity:end} values.
256 @deffn {Scheme Procedure} program-arguments-alist program [ip]
257 Return an association list describing the arguments that @var{program} accepts, or
258 @code{#f} if the information cannot be obtained.
260 The alist keys that are currently defined are `required', `optional',
261 `keyword', `allow-other-keys?', and `rest'. For example:
264 (program-arguments-alist
265 (lambda* (a b #:optional c #:key (d 1) #:rest e)
269 (keyword . ((#:d . 4)))
270 (allow-other-keys? . #f)
275 @deffn {Scheme Procedure} program-lambda-list program [ip]
276 Return a representation of the arguments of @var{program} as a lambda
277 list, or @code{#f} if this information is not available.
283 (lambda* (a b #:optional c #:key (d 1) #:rest e)
288 @node Optional Arguments
289 @subsection Optional Arguments
291 Scheme procedures, as defined in R5RS, can either handle a fixed number
292 of actual arguments, or a fixed number of actual arguments followed by
293 arbitrarily many additional arguments. Writing procedures of variable
294 arity can be useful, but unfortunately, the syntactic means for handling
295 argument lists of varying length is a bit inconvenient. It is possible
296 to give names to the fixed number of arguments, but the remaining
297 (optional) arguments can be only referenced as a list of values
300 For this reason, Guile provides an extension to @code{lambda},
301 @code{lambda*}, which allows the user to define procedures with
302 optional and keyword arguments. In addition, Guile's virtual machine
303 has low-level support for optional and keyword argument dispatch.
304 Calls to procedures with optional and keyword arguments can be made
305 cheaply, without allocating a rest list.
308 * lambda* and define*:: Creating advanced argument handling procedures.
309 * ice-9 optargs:: (ice-9 optargs) provides some utilities.
313 @node lambda* and define*
314 @subsubsection lambda* and define*.
316 @code{lambda*} is like @code{lambda}, except with some extensions to
317 allow optional and keyword arguments.
319 @deffn {library syntax} lambda* ([var@dots{}] @* @
320 [#:optional vardef@dots{}] @* @
321 [#:key vardef@dots{} [#:allow-other-keys]] @* @
322 [#:rest var | . var]) @* @
325 Create a procedure which takes optional and/or keyword arguments
326 specified with @code{#:optional} and @code{#:key}. For example,
329 (lambda* (a b #:optional c d . e) '())
332 is a procedure with fixed arguments @var{a} and @var{b}, optional
333 arguments @var{c} and @var{d}, and rest argument @var{e}. If the
334 optional arguments are omitted in a call, the variables for them are
338 Likewise, @code{define*} is syntactic sugar for defining procedures
339 using @code{lambda*}.
341 @code{lambda*} can also make procedures with keyword arguments. For
342 example, a procedure defined like this:
345 (define* (sir-yes-sir #:key action how-high)
346 (list action how-high))
349 can be called as @code{(sir-yes-sir #:action 'jump)},
350 @code{(sir-yes-sir #:how-high 13)}, @code{(sir-yes-sir #:action
351 'lay-down #:how-high 0)}, or just @code{(sir-yes-sir)}. Whichever
352 arguments are given as keywords are bound to values (and those not
353 given are @code{#f}).
355 Optional and keyword arguments can also have default values to take
356 when not present in a call, by giving a two-element list of variable
357 name and expression. For example in
360 (define* (frob foo #:optional (bar 42) #:key (baz 73))
364 @var{foo} is a fixed argument, @var{bar} is an optional argument with
365 default value 42, and baz is a keyword argument with default value 73.
366 Default value expressions are not evaluated unless they are needed,
367 and until the procedure is called.
369 Normally it's an error if a call has keywords other than those
370 specified by @code{#:key}, but adding @code{#:allow-other-keys} to the
371 definition (after the keyword argument declarations) will ignore
374 If a call has a keyword given twice, the last value is used. For
378 (define* (flips #:key (heads 0) (tails 0))
379 (display (list heads tails)))
381 (flips #:heads 37 #:tails 42 #:heads 99)
385 @code{#:rest} is a synonym for the dotted syntax rest argument. The
386 argument lists @code{(a . b)} and @code{(a #:rest b)} are equivalent
387 in all respects. This is provided for more similarity to DSSSL,
388 MIT-Scheme and Kawa among others, as well as for refugees from other
391 When @code{#:key} is used together with a rest argument, the keyword
392 parameters in a call all remain in the rest list. This is the same as
393 Common Lisp. For example,
396 ((lambda* (#:key (x 0) #:allow-other-keys #:rest r)
399 @print{} (#:x 123 #:y 456)
402 @code{#:optional} and @code{#:key} establish their bindings
403 successively, from left to right. This means default expressions can
404 refer back to prior parameters, for example
407 (lambda* (start #:optional (end (+ 10 start)))
408 (do ((i start (1+ i)))
413 The exception to this left-to-right scoping rule is the rest argument.
414 If there is a rest argument, it is bound after the optional arguments,
415 but before the keyword arguments.
420 @subsubsection (ice-9 optargs)
422 Before Guile 2.0, @code{lambda*} and @code{define*} were implemented
423 using macros that processed rest list arguments. This was not optimal,
424 as calling procedures with optional arguments had to allocate rest
425 lists at every procedure invocation. Guile 2.0 improved this
426 situation by bringing optional and keyword arguments into Guile's
429 However there are occasions in which you have a list and want to parse
430 it for optional or keyword arguments. Guile's @code{(ice-9 optargs)}
431 provides some macros to help with that task.
433 The syntax @code{let-optional} and @code{let-optional*} are for
434 destructuring rest argument lists and giving names to the various list
435 elements. @code{let-optional} binds all variables simultaneously, while
436 @code{let-optional*} binds them sequentially, consistent with @code{let}
437 and @code{let*} (@pxref{Local Bindings}).
439 @deffn {library syntax} let-optional rest-arg (binding @dots{}) body1 body2 @dots{}
440 @deffnx {library syntax} let-optional* rest-arg (binding @dots{}) body1 body2 @dots{}
441 These two macros give you an optional argument interface that is very
442 @dfn{Schemey} and introduces no fancy syntax. They are compatible with
443 the scsh macros of the same name, but are slightly extended. Each of
444 @var{binding} may be of one of the forms @var{var} or @code{(@var{var}
445 @var{default-value})}. @var{rest-arg} should be the rest-argument of the
446 procedures these are used from. The items in @var{rest-arg} are
447 sequentially bound to the variable names are given. When @var{rest-arg}
448 runs out, the remaining vars are bound either to the default values or
449 @code{#f} if no default value was specified. @var{rest-arg} remains
450 bound to whatever may have been left of @var{rest-arg}.
452 After binding the variables, the expressions @var{body1} @var{body2} @dots{}
453 are evaluated in order.
456 Similarly, @code{let-keywords} and @code{let-keywords*} extract values
457 from keyword style argument lists, binding local variables to those
458 values or to defaults.
460 @deffn {library syntax} let-keywords args allow-other-keys? (binding @dots{}) body1 body2 @dots{}
461 @deffnx {library syntax} let-keywords* args allow-other-keys? (binding @dots{}) body1 body2 @dots{}
462 @var{args} is evaluated and should give a list of the form
463 @code{(#:keyword1 value1 #:keyword2 value2 @dots{})}. The
464 @var{binding}s are variables and default expressions, with the variables
465 to be set (by name) from the keyword values. The @var{body1}
466 @var{body2} @dots{} forms are then evaluated and the last is the
467 result. An example will make the syntax clearest,
470 (define args '(#:xyzzy "hello" #:foo "world"))
472 (let-keywords args #t
473 ((foo "default for foo")
474 (bar (string-append "default" "for" "bar")))
478 @print{} world, defaultforbar
481 The binding for @code{foo} comes from the @code{#:foo} keyword in
482 @code{args}. But the binding for @code{bar} is the default in the
483 @code{let-keywords}, since there's no @code{#:bar} in the args.
485 @var{allow-other-keys?} is evaluated and controls whether unknown
486 keywords are allowed in the @var{args} list. When true other keys are
487 ignored (such as @code{#:xyzzy} in the example), when @code{#f} an
488 error is thrown for anything unknown.
491 @code{(ice-9 optargs)} also provides some more @code{define*} sugar,
492 which is not so useful with modern Guile coding, but still supported:
493 @code{define*-public} is the @code{lambda*} version of
494 @code{define-public}; @code{defmacro*} and @code{defmacro*-public}
495 exist for defining macros with the improved argument list handling
496 possibilities. The @code{-public} versions not only define the
497 procedures/macros, but also export them from the current module.
499 @deffn {library syntax} define*-public formals body1 body2 @dots{}
500 Like a mix of @code{define*} and @code{define-public}.
503 @deffn {library syntax} defmacro* name formals body1 body2 @dots{}
504 @deffnx {library syntax} defmacro*-public name formals body1 body2 @dots{}
505 These are just like @code{defmacro} and @code{defmacro-public} except that they
506 take @code{lambda*}-style extended parameter lists, where @code{#:optional},
507 @code{#:key}, @code{#:allow-other-keys} and @code{#:rest} are allowed with the usual
508 semantics. Here is an example of a macro with an optional argument:
511 (defmacro* transmogrify (a #:optional b)
517 @subsection Case-lambda
519 @cindex variable arity
520 @cindex arity, variable
522 R5RS's rest arguments are indeed useful and very general, but they
523 often aren't the most appropriate or efficient means to get the job
524 done. For example, @code{lambda*} is a much better solution to the
525 optional argument problem than @code{lambda} with rest arguments.
528 Likewise, @code{case-lambda} works well for when you want one
529 procedure to do double duty (or triple, or ...), without the penalty
530 of consing a rest list.
535 (define (make-accum n)
538 ((m) (set! n (+ n m)) n)))
540 (define a (make-accum 20))
546 The value returned by a @code{case-lambda} form is a procedure which
547 matches the number of actual arguments against the formals in the
548 various clauses, in order. The first matching clause is selected, the
549 corresponding values from the actual parameter list are bound to the
550 variable names in the clauses and the body of the clause is evaluated.
551 If no clause matches, an error is signalled.
553 The syntax of the @code{case-lambda} form is defined in the following
554 EBNF grammar. @dfn{Formals} means a formal argument list just like
555 with @code{lambda} (@pxref{Lambda}).
560 --> (case-lambda <case-lambda-clause>*)
561 --> (case-lambda <docstring> <case-lambda-clause>*)
563 --> (<formals> <definition-or-command>*)
566 | (<identifier>* . <identifier>)
571 Rest lists can be useful with @code{case-lambda}:
576 "Return the sum of all arguments."
580 ((a b . rest) (apply plus (+ a b) rest))))
581 (plus 1 2 3) @result{} 6
584 @fnindex case-lambda*
585 Also, for completeness. Guile defines @code{case-lambda*} as well,
586 which is like @code{case-lambda}, except with @code{lambda*} clauses.
587 A @code{case-lambda*} clause matches if the arguments fill the
588 required arguments, but are not too many for the optional and/or rest
591 Keyword arguments are possible with @code{case-lambda*} as well, but
592 they do not contribute to the ``matching'' behavior, and their
593 interactions with required, optional, and rest arguments can be
596 For the purposes of @code{case-lambda*} (and of @code{case-lambda}, as a
597 special case), a clause @dfn{matches} if it has enough required
598 arguments, and not too many positional arguments. The required
599 arguments are any arguments before the @code{#:optional}, @code{#:key},
600 and @code{#:rest} arguments. @dfn{Positional} arguments are the
601 required arguments, together with the optional arguments.
603 In the absence of @code{#:key} or @code{#:rest} arguments, it's easy to
604 see how there could be too many positional arguments: you pass 5
605 arguments to a function that only takes 4 arguments, including optional
606 arguments. If there is a @code{#:rest} argument, there can never be too
607 many positional arguments: any application with enough required
608 arguments for a clause will match that clause, even if there are also
609 @code{#:key} arguments.
611 Otherwise, for applications to a clause with @code{#:key} arguments (and
612 without a @code{#:rest} argument), a clause will match there only if
613 there are enough required arguments and if the next argument after
614 binding required and optional arguments, if any, is a keyword. For
615 efficiency reasons, Guile is currently unable to include keyword
616 arguments in the matching algorithm. Clauses match on positional
617 arguments only, not by comparing a given keyword to the available set of
618 keyword arguments that a function has.
620 Some examples follow.
625 ((a #:optional b) 'clause-1)
626 ((a #:optional b #:key c) 'clause-2)
627 ((a #:key d) 'clause-3)
628 ((#:key e #:rest f) 'clause-4)))
630 (f) @result{} clause-4
631 (f 1) @result{} clause-1
632 (f) @result{} clause-4
636 (f #:a #:b #:c #:d #:e) clause-4
638 ;; clause-2 will match anything that clause-3 would match.
639 (f 1 #:d 2) @result{} error: bad keyword args in clause 2
642 Don't forget that the clauses are matched in order, and the first
643 matching clause will be taken. This can result in a keyword being bound
644 to a required argument, as in the case of @code{f #:e 10}.
647 @node Higher-Order Functions
648 @subsection Higher-Order Functions
650 @cindex higher-order functions
652 As a functional programming language, Scheme allows the definition of
653 @dfn{higher-order functions}, i.e., functions that take functions as
654 arguments and/or return functions. Utilities to derive procedures from
655 other procedures are provided and described below.
657 @deffn {Scheme Procedure} const value
658 Return a procedure that accepts any number of arguments and returns
662 (procedure? (const 3)) @result{} #t
663 ((const 'hello)) @result{} hello
664 ((const 'hello) 'world) @result{} hello
668 @deffn {Scheme Procedure} negate proc
669 Return a procedure with the same arity as @var{proc} that returns the
670 @code{not} of @var{proc}'s result.
673 (procedure? (negate number?)) @result{} #t
674 ((negate odd?) 2) @result{} #t
675 ((negate real?) 'dream) @result{} #t
676 ((negate string-prefix?) "GNU" "GNU Guile")
678 (filter (negate number?) '(a 2 "b"))
683 @deffn {Scheme Procedure} compose proc1 proc2 @dots{}
684 Compose @var{proc1} with the procedures @var{proc2} @dots{} such that
685 the last @var{proc} argument is applied first and @var{proc1} last, and
686 return the resulting procedure. The given procedures must have
690 (procedure? (compose 1+ 1-)) @result{} #t
691 ((compose sqrt 1+ 1+) 2) @result{} 2.0
692 ((compose 1+ sqrt) 3) @result{} 2.73205080756888
693 (eq? (compose 1+) 1+) @result{} #t
695 ((compose zip unzip2) '((1 2) (a b)))
696 @result{} ((1 2) (a b))
700 @deffn {Scheme Procedure} identity x
704 @deffn {Scheme Procedure} and=> value proc
705 When @var{value} is @code{#f}, return @code{#f}. Otherwise, return
706 @code{(@var{proc} @var{value})}.
709 @node Procedure Properties
710 @subsection Procedure Properties and Meta-information
712 In addition to the information that is strictly necessary to run,
713 procedures may have other associated information. For example, the
714 name of a procedure is information not for the procedure, but about
715 the procedure. This meta-information can be accessed via the procedure
716 properties interface.
718 The first group of procedures in this meta-interface are predicates to
719 test whether a Scheme object is a procedure, or a special procedure,
720 respectively. @code{procedure?} is the most general predicates, it
721 returns @code{#t} for any kind of procedure.
724 @deffn {Scheme Procedure} procedure? obj
725 @deffnx {C Function} scm_procedure_p (obj)
726 Return @code{#t} if @var{obj} is a procedure.
729 @deffn {Scheme Procedure} thunk? obj
730 @deffnx {C Function} scm_thunk_p (obj)
731 Return @code{#t} if @var{obj} is a thunk---a procedure that does
732 not accept arguments.
735 @cindex procedure properties
736 Procedure properties are general properties associated with
737 procedures. These can be the name of a procedure or other relevant
738 information, such as debug hints.
740 @deffn {Scheme Procedure} procedure-name proc
741 @deffnx {C Function} scm_procedure_name (proc)
742 Return the name of the procedure @var{proc}
745 @deffn {Scheme Procedure} procedure-source proc
746 @deffnx {C Function} scm_procedure_source (proc)
747 Return the source of the procedure @var{proc}. Returns @code{#f} if
748 the source code is not available.
751 @deffn {Scheme Procedure} procedure-properties proc
752 @deffnx {C Function} scm_procedure_properties (proc)
753 Return the properties associated with @var{proc}, as an association
757 @deffn {Scheme Procedure} procedure-property proc key
758 @deffnx {C Function} scm_procedure_property (proc, key)
759 Return the property of @var{proc} with name @var{key}.
762 @deffn {Scheme Procedure} set-procedure-properties! proc alist
763 @deffnx {C Function} scm_set_procedure_properties_x (proc, alist)
764 Set @var{proc}'s property list to @var{alist}.
767 @deffn {Scheme Procedure} set-procedure-property! proc key value
768 @deffnx {C Function} scm_set_procedure_property_x (proc, key, value)
769 In @var{proc}'s property list, set the property named @var{key} to
773 @cindex procedure documentation
774 Documentation for a procedure can be accessed with the procedure
775 @code{procedure-documentation}.
777 @deffn {Scheme Procedure} procedure-documentation proc
778 @deffnx {C Function} scm_procedure_documentation (proc)
779 Return the documentation string associated with @code{proc}. By
780 convention, if a procedure contains more than one expression and the
781 first expression is a string constant, that string is assumed to contain
782 documentation for that procedure.
786 @node Procedures with Setters
787 @subsection Procedures with Setters
789 @c FIXME::martin: Review me!
791 @c FIXME::martin: Document `operator struct'.
793 @cindex procedure with setter
795 A @dfn{procedure with setter} is a special kind of procedure which
796 normally behaves like any accessor procedure, that is a procedure which
797 accesses a data structure. The difference is that this kind of
798 procedure has a so-called @dfn{setter} attached, which is a procedure
799 for storing something into a data structure.
801 Procedures with setters are treated specially when the procedure appears
802 in the special form @code{set!} (REFFIXME). How it works is best shown
805 Suppose we have a procedure called @code{foo-ref}, which accepts two
806 arguments, a value of type @code{foo} and an integer. The procedure
807 returns the value stored at the given index in the @code{foo} object.
808 Let @code{f} be a variable containing such a @code{foo} data
809 structure.@footnote{Working definitions would be:
811 (define foo-ref vector-ref)
812 (define foo-set! vector-set!)
813 (define f (make-vector 2 #f))
818 (foo-ref f 0) @result{} bar
819 (foo-ref f 1) @result{} braz
822 Also suppose that a corresponding setter procedure called
823 @code{foo-set!} does exist.
827 (foo-ref f 0) @result{} bla
830 Now we could create a new procedure called @code{foo}, which is a
831 procedure with setter, by calling @code{make-procedure-with-setter} with
832 the accessor and setter procedures @code{foo-ref} and @code{foo-set!}.
833 Let us call this new procedure @code{foo}.
836 (define foo (make-procedure-with-setter foo-ref foo-set!))
839 @code{foo} can from now an be used to either read from the data
840 structure stored in @code{f}, or to write into the structure.
843 (set! (foo f 0) 'dum)
844 (foo f 0) @result{} dum
847 @deffn {Scheme Procedure} make-procedure-with-setter procedure setter
848 @deffnx {C Function} scm_make_procedure_with_setter (procedure, setter)
849 Create a new procedure which behaves like @var{procedure}, but
850 with the associated setter @var{setter}.
853 @deffn {Scheme Procedure} procedure-with-setter? obj
854 @deffnx {C Function} scm_procedure_with_setter_p (obj)
855 Return @code{#t} if @var{obj} is a procedure with an
856 associated setter procedure.
859 @deffn {Scheme Procedure} procedure proc
860 @deffnx {C Function} scm_procedure (proc)
861 Return the procedure of @var{proc}, which must be an
865 @deffn {Scheme Procedure} setter proc
866 Return the setter of @var{proc}, which must be either a procedure with
867 setter or an operator struct.
870 @node Inlinable Procedures
871 @subsection Inlinable Procedures
874 @cindex procedure inlining
875 You can define an @dfn{inlinable procedure} by using
876 @code{define-inlinable} instead of @code{define}. An inlinable
877 procedure behaves the same as a regular procedure, but direct calls will
878 result in the procedure body being inlined into the caller.
880 @cindex partial evaluator
881 Bear in mind that starting from version 2.0.3, Guile has a partial
882 evaluator that can inline the body of inner procedures when deemed
886 scheme@@(guile-user)> ,optimize (define (foo x)
887 (define (bar) (+ x 3))
890 (lambda (#@{x 94@}#) (* (+ #@{x 94@}# 3) 2)))
894 The partial evaluator does not inline top-level bindings, though, so
895 this is a situation where you may find it interesting to use
896 @code{define-inlinable}.
898 Procedures defined with @code{define-inlinable} are @emph{always}
899 inlined, at all direct call sites. This eliminates function call
900 overhead at the expense of an increase in code size. Additionally, the
901 caller will not transparently use the new definition if the inline
902 procedure is redefined. It is not possible to trace an inlined
903 procedures or install a breakpoint in it (@pxref{Traps}). For these
904 reasons, you should not make a procedure inlinable unless it
905 demonstrably improves performance in a crucial way.
907 In general, only small procedures should be considered for inlining, as
908 making large procedures inlinable will probably result in an increase in
909 code size. Additionally, the elimination of the call overhead rarely
910 matters for large procedures.
912 @deffn {Scheme Syntax} define-inlinable (name parameter @dots{}) body1 body2 @dots{}
913 Define @var{name} as a procedure with parameters @var{parameter}s and
914 bodies @var{body1}, @var{body2}, @enddots{}.
918 @c TeX-master: "guile.texi"