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 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 @deffnx {Scheme Procedure} program-lambda-list [ip]
275 Accessors for a representation of the arguments of a program, with both
276 names and types (ie. either required, optional or keywords)
278 @code{program-arguments-alist} returns this information in the form of
279 an association list while @code{program-lambda-list} returns the same
280 information in a form similar to a lambda definition.
283 @node Optional Arguments
284 @subsection Optional Arguments
286 Scheme procedures, as defined in R5RS, can either handle a fixed number
287 of actual arguments, or a fixed number of actual arguments followed by
288 arbitrarily many additional arguments. Writing procedures of variable
289 arity can be useful, but unfortunately, the syntactic means for handling
290 argument lists of varying length is a bit inconvenient. It is possible
291 to give names to the fixed number of arguments, but the remaining
292 (optional) arguments can be only referenced as a list of values
295 For this reason, Guile provides an extension to @code{lambda},
296 @code{lambda*}, which allows the user to define procedures with
297 optional and keyword arguments. In addition, Guile's virtual machine
298 has low-level support for optional and keyword argument dispatch.
299 Calls to procedures with optional and keyword arguments can be made
300 cheaply, without allocating a rest list.
303 * lambda* and define*:: Creating advanced argument handling procedures.
304 * ice-9 optargs:: (ice-9 optargs) provides some utilities.
308 @node lambda* and define*
309 @subsubsection lambda* and define*.
311 @code{lambda*} is like @code{lambda}, except with some extensions to
312 allow optional and keyword arguments.
314 @deffn {library syntax} lambda* ([var@dots{}] @* [#:optional vardef@dots{}] @* [#:key vardef@dots{} [#:allow-other-keys]] @* [#:rest var | . var]) @* body
316 Create a procedure which takes optional and/or keyword arguments
317 specified with @code{#:optional} and @code{#:key}. For example,
320 (lambda* (a b #:optional c d . e) '())
323 is a procedure with fixed arguments @var{a} and @var{b}, optional
324 arguments @var{c} and @var{d}, and rest argument @var{e}. If the
325 optional arguments are omitted in a call, the variables for them are
329 Likewise, @code{define*} is syntactic sugar for defining procedures
330 using @code{lambda*}.
332 @code{lambda*} can also make procedures with keyword arguments. For
333 example, a procedure defined like this:
336 (define* (sir-yes-sir #:key action how-high)
337 (list action how-high))
340 can be called as @code{(sir-yes-sir #:action 'jump)},
341 @code{(sir-yes-sir #:how-high 13)}, @code{(sir-yes-sir #:action
342 'lay-down #:how-high 0)}, or just @code{(sir-yes-sir)}. Whichever
343 arguments are given as keywords are bound to values (and those not
344 given are @code{#f}).
346 Optional and keyword arguments can also have default values to take
347 when not present in a call, by giving a two-element list of variable
348 name and expression. For example in
351 (define* (frob foo #:optional (bar 42) #:key (baz 73))
355 @var{foo} is a fixed argument, @var{bar} is an optional argument with
356 default value 42, and baz is a keyword argument with default value 73.
357 Default value expressions are not evaluated unless they are needed,
358 and until the procedure is called.
360 Normally it's an error if a call has keywords other than those
361 specified by @code{#:key}, but adding @code{#:allow-other-keys} to the
362 definition (after the keyword argument declarations) will ignore
365 If a call has a keyword given twice, the last value is used. For
369 (define* (flips #:key (heads 0) (tails 0))
370 (display (list heads tails)))
372 (flips #:heads 37 #:tails 42 #:heads 99)
376 @code{#:rest} is a synonym for the dotted syntax rest argument. The
377 argument lists @code{(a . b)} and @code{(a #:rest b)} are equivalent
378 in all respects. This is provided for more similarity to DSSSL,
379 MIT-Scheme and Kawa among others, as well as for refugees from other
382 When @code{#:key} is used together with a rest argument, the keyword
383 parameters in a call all remain in the rest list. This is the same as
384 Common Lisp. For example,
387 ((lambda* (#:key (x 0) #:allow-other-keys #:rest r)
390 @print{} (#:x 123 #:y 456)
393 @code{#:optional} and @code{#:key} establish their bindings
394 successively, from left to right. This means default expressions can
395 refer back to prior parameters, for example
398 (lambda* (start #:optional (end (+ 10 start)))
399 (do ((i start (1+ i)))
404 The exception to this left-to-right scoping rule is the rest argument.
405 If there is a rest argument, it is bound after the optional arguments,
406 but before the keyword arguments.
411 @subsubsection (ice-9 optargs)
413 Before Guile 2.0, @code{lambda*} and @code{define*} were implemented
414 using macros that processed rest list arguments. This was not optimal,
415 as calling procedures with optional arguments had to allocate rest
416 lists at every procedure invocation. Guile 2.0 improved this
417 situation by bringing optional and keyword arguments into Guile's
420 However there are occasions in which you have a list and want to parse
421 it for optional or keyword arguments. Guile's @code{(ice-9 optargs)}
422 provides some macros to help with that task.
424 The syntax @code{let-optional} and @code{let-optional*} are for
425 destructuring rest argument lists and giving names to the various list
426 elements. @code{let-optional} binds all variables simultaneously, while
427 @code{let-optional*} binds them sequentially, consistent with @code{let}
428 and @code{let*} (@pxref{Local Bindings}).
430 @deffn {library syntax} let-optional rest-arg (binding @dots{}) body1 body2 @dots{}
431 @deffnx {library syntax} let-optional* rest-arg (binding @dots{}) body1 body2 @dots{}
432 These two macros give you an optional argument interface that is very
433 @dfn{Schemey} and introduces no fancy syntax. They are compatible with
434 the scsh macros of the same name, but are slightly extended. Each of
435 @var{binding} may be of one of the forms @var{var} or @code{(@var{var}
436 @var{default-value})}. @var{rest-arg} should be the rest-argument of the
437 procedures these are used from. The items in @var{rest-arg} are
438 sequentially bound to the variable names are given. When @var{rest-arg}
439 runs out, the remaining vars are bound either to the default values or
440 @code{#f} if no default value was specified. @var{rest-arg} remains
441 bound to whatever may have been left of @var{rest-arg}.
443 After binding the variables, the expressions @var{body1} @var{body2} @dots{}
444 are evaluated in order.
447 Similarly, @code{let-keywords} and @code{let-keywords*} extract values
448 from keyword style argument lists, binding local variables to those
449 values or to defaults.
451 @deffn {library syntax} let-keywords args allow-other-keys? (binding @dots{}) body1 body2 @dots{}
452 @deffnx {library syntax} let-keywords* args allow-other-keys? (binding @dots{}) body1 body2 @dots{}
453 @var{args} is evaluated and should give a list of the form
454 @code{(#:keyword1 value1 #:keyword2 value2 @dots{})}. The
455 @var{binding}s are variables and default expressions, with the variables
456 to be set (by name) from the keyword values. The @var{body1}
457 @var{body2} @dots{} forms are then evaluated and the last is the
458 result. An example will make the syntax clearest,
461 (define args '(#:xyzzy "hello" #:foo "world"))
463 (let-keywords args #t
464 ((foo "default for foo")
465 (bar (string-append "default" "for" "bar")))
469 @print{} world, defaultforbar
472 The binding for @code{foo} comes from the @code{#:foo} keyword in
473 @code{args}. But the binding for @code{bar} is the default in the
474 @code{let-keywords}, since there's no @code{#:bar} in the args.
476 @var{allow-other-keys?} is evaluated and controls whether unknown
477 keywords are allowed in the @var{args} list. When true other keys are
478 ignored (such as @code{#:xyzzy} in the example), when @code{#f} an
479 error is thrown for anything unknown.
482 @code{(ice-9 optargs)} also provides some more @code{define*} sugar,
483 which is not so useful with modern Guile coding, but still supported:
484 @code{define*-public} is the @code{lambda*} version of
485 @code{define-public}; @code{defmacro*} and @code{defmacro*-public}
486 exist for defining macros with the improved argument list handling
487 possibilities. The @code{-public} versions not only define the
488 procedures/macros, but also export them from the current module.
490 @deffn {library syntax} define*-public formals body1 body2 @dots{}
491 Like a mix of @code{define*} and @code{define-public}.
494 @deffn {library syntax} defmacro* name formals body1 body2 @dots{}
495 @deffnx {library syntax} defmacro*-public name formals body1 body2 @dots{}
496 These are just like @code{defmacro} and @code{defmacro-public} except that they
497 take @code{lambda*}-style extended parameter lists, where @code{#:optional},
498 @code{#:key}, @code{#:allow-other-keys} and @code{#:rest} are allowed with the usual
499 semantics. Here is an example of a macro with an optional argument:
502 (defmacro* transmogrify (a #:optional b)
508 @subsection Case-lambda
510 @cindex variable arity
511 @cindex arity, variable
513 R5RS's rest arguments are indeed useful and very general, but they
514 often aren't the most appropriate or efficient means to get the job
515 done. For example, @code{lambda*} is a much better solution to the
516 optional argument problem than @code{lambda} with rest arguments.
519 Likewise, @code{case-lambda} works well for when you want one
520 procedure to do double duty (or triple, or ...), without the penalty
521 of consing a rest list.
526 (define (make-accum n)
529 ((m) (set! n (+ n m)) n)))
531 (define a (make-accum 20))
537 The value returned by a @code{case-lambda} form is a procedure which
538 matches the number of actual arguments against the formals in the
539 various clauses, in order. The first matching clause is selected, the
540 corresponding values from the actual parameter list are bound to the
541 variable names in the clauses and the body of the clause is evaluated.
542 If no clause matches, an error is signalled.
544 The syntax of the @code{case-lambda} form is defined in the following
545 EBNF grammar. @dfn{Formals} means a formal argument list just like
546 with @code{lambda} (@pxref{Lambda}).
551 --> (case-lambda <case-lambda-clause>)
553 --> (<formals> <definition-or-command>*)
556 | (<identifier>* . <identifier>)
561 Rest lists can be useful with @code{case-lambda}:
569 ((a b . rest) (apply plus (+ a b) rest))))
570 (plus 1 2 3) @result{} 6
573 @fnindex case-lambda*
574 Also, for completeness. Guile defines @code{case-lambda*} as well,
575 which is like @code{case-lambda}, except with @code{lambda*} clauses.
576 A @code{case-lambda*} clause matches if the arguments fill the
577 required arguments, but are not too many for the optional and/or rest
580 Keyword arguments are possible with @code{case-lambda*}, but they do
581 not contribute to the ``matching'' behavior. That is to say,
582 @code{case-lambda*} matches only on required, optional, and rest
583 arguments, and on the predicate; keyword arguments may be present but
584 do not contribute to the ``success'' of a match. In fact a bad keyword
585 argument list may cause an error to be raised.
587 @node Higher-Order Functions
588 @subsection Higher-Order Functions
590 @cindex higher-order functions
592 As a functional programming language, Scheme allows the definition of
593 @dfn{higher-order functions}, i.e., functions that take functions as
594 arguments and/or return functions. Utilities to derive procedures from
595 other procedures are provided and described below.
597 @deffn {Scheme Procedure} const value
598 Return a procedure that accepts any number of arguments and returns
602 (procedure? (const 3)) @result{} #t
603 ((const 'hello)) @result{} hello
604 ((const 'hello) 'world) @result{} hello
608 @deffn {Scheme Procedure} negate proc
609 Return a procedure with the same arity as @var{proc} that returns the
610 @code{not} of @var{proc}'s result.
613 (procedure? (negate number?)) @result{} #t
614 ((negate odd?) 2) @result{} #t
615 ((negate real?) 'dream) @result{} #t
616 ((negate string-prefix?) "GNU" "GNU Guile")
618 (filter (negate number?) '(a 2 "b"))
623 @deffn {Scheme Procedure} compose proc1 proc2 @dots{}
624 Compose @var{proc1} with the procedures @var{proc2} @dots{} such that
625 the last @var{proc} argument is applied first and @var{proc1} last, and
626 return the resulting procedure. The given procedures must have
630 (procedure? (compose 1+ 1-)) @result{} #t
631 ((compose sqrt 1+ 1+) 2) @result{} 2.0
632 ((compose 1+ sqrt) 3) @result{} 2.73205080756888
633 (eq? (compose 1+) 1+) @result{} #t
635 ((compose zip unzip2) '((1 2) (a b)))
636 @result{} ((1 2) (a b))
640 @deffn {Scheme Procedure} identity x
644 @node Procedure Properties
645 @subsection Procedure Properties and Meta-information
647 In addition to the information that is strictly necessary to run,
648 procedures may have other associated information. For example, the
649 name of a procedure is information not for the procedure, but about
650 the procedure. This meta-information can be accessed via the procedure
651 properties interface.
653 The first group of procedures in this meta-interface are predicates to
654 test whether a Scheme object is a procedure, or a special procedure,
655 respectively. @code{procedure?} is the most general predicates, it
656 returns @code{#t} for any kind of procedure.
659 @deffn {Scheme Procedure} procedure? obj
660 @deffnx {C Function} scm_procedure_p (obj)
661 Return @code{#t} if @var{obj} is a procedure.
664 @deffn {Scheme Procedure} thunk? obj
665 @deffnx {C Function} scm_thunk_p (obj)
666 Return @code{#t} if @var{obj} is a thunk---a procedure that does
667 not accept arguments.
670 @cindex procedure properties
671 Procedure properties are general properties associated with
672 procedures. These can be the name of a procedure or other relevant
673 information, such as debug hints.
675 @deffn {Scheme Procedure} procedure-name proc
676 @deffnx {C Function} scm_procedure_name (proc)
677 Return the name of the procedure @var{proc}
680 @deffn {Scheme Procedure} procedure-source proc
681 @deffnx {C Function} scm_procedure_source (proc)
682 Return the source of the procedure @var{proc}. Returns @code{#f} if
683 the source code is not available.
686 @deffn {Scheme Procedure} procedure-properties proc
687 @deffnx {C Function} scm_procedure_properties (proc)
688 Return the properties associated with @var{proc}, as an association
692 @deffn {Scheme Procedure} procedure-property proc key
693 @deffnx {C Function} scm_procedure_property (proc, key)
694 Return the property of @var{proc} with name @var{key}.
697 @deffn {Scheme Procedure} set-procedure-properties! proc alist
698 @deffnx {C Function} scm_set_procedure_properties_x (proc, alist)
699 Set @var{proc}'s property list to @var{alist}.
702 @deffn {Scheme Procedure} set-procedure-property! proc key value
703 @deffnx {C Function} scm_set_procedure_property_x (proc, key, value)
704 In @var{proc}'s property list, set the property named @var{key} to
708 @cindex procedure documentation
709 Documentation for a procedure can be accessed with the procedure
710 @code{procedure-documentation}.
712 @deffn {Scheme Procedure} procedure-documentation proc
713 @deffnx {C Function} scm_procedure_documentation (proc)
714 Return the documentation string associated with @code{proc}. By
715 convention, if a procedure contains more than one expression and the
716 first expression is a string constant, that string is assumed to contain
717 documentation for that procedure.
721 @node Procedures with Setters
722 @subsection Procedures with Setters
724 @c FIXME::martin: Review me!
726 @c FIXME::martin: Document `operator struct'.
728 @cindex procedure with setter
730 A @dfn{procedure with setter} is a special kind of procedure which
731 normally behaves like any accessor procedure, that is a procedure which
732 accesses a data structure. The difference is that this kind of
733 procedure has a so-called @dfn{setter} attached, which is a procedure
734 for storing something into a data structure.
736 Procedures with setters are treated specially when the procedure appears
737 in the special form @code{set!} (REFFIXME). How it works is best shown
740 Suppose we have a procedure called @code{foo-ref}, which accepts two
741 arguments, a value of type @code{foo} and an integer. The procedure
742 returns the value stored at the given index in the @code{foo} object.
743 Let @code{f} be a variable containing such a @code{foo} data
744 structure.@footnote{Working definitions would be:
746 (define foo-ref vector-ref)
747 (define foo-set! vector-set!)
748 (define f (make-vector 2 #f))
753 (foo-ref f 0) @result{} bar
754 (foo-ref f 1) @result{} braz
757 Also suppose that a corresponding setter procedure called
758 @code{foo-set!} does exist.
762 (foo-ref f 0) @result{} bla
765 Now we could create a new procedure called @code{foo}, which is a
766 procedure with setter, by calling @code{make-procedure-with-setter} with
767 the accessor and setter procedures @code{foo-ref} and @code{foo-set!}.
768 Let us call this new procedure @code{foo}.
771 (define foo (make-procedure-with-setter foo-ref foo-set!))
774 @code{foo} can from now an be used to either read from the data
775 structure stored in @code{f}, or to write into the structure.
778 (set! (foo f 0) 'dum)
779 (foo f 0) @result{} dum
782 @deffn {Scheme Procedure} make-procedure-with-setter procedure setter
783 @deffnx {C Function} scm_make_procedure_with_setter (procedure, setter)
784 Create a new procedure which behaves like @var{procedure}, but
785 with the associated setter @var{setter}.
788 @deffn {Scheme Procedure} procedure-with-setter? obj
789 @deffnx {C Function} scm_procedure_with_setter_p (obj)
790 Return @code{#t} if @var{obj} is a procedure with an
791 associated setter procedure.
794 @deffn {Scheme Procedure} procedure proc
795 @deffnx {C Function} scm_procedure (proc)
796 Return the procedure of @var{proc}, which must be an
800 @deffn {Scheme Procedure} setter proc
801 Return the setter of @var{proc}, which must be either a procedure with
802 setter or an operator struct.
805 @node Inlinable Procedures
806 @subsection Inlinable Procedures
809 @cindex procedure inlining
810 You can define an @dfn{inlinable procedure} by using
811 @code{define-inlinable} instead of @code{define}. An inlinable
812 procedure behaves the same as a regular procedure, but direct calls will
813 result in the procedure body being inlined into the caller.
815 @cindex partial evaluator
816 Bear in mind that starting from version 2.0.3, Guile has a partial
817 evaluator that can inline the body of inner procedures when deemed
821 scheme@@(guile-user)> ,optimize (define (foo x)
822 (define (bar) (+ x 3))
825 (lambda (#@{x 94@}#) (* (+ #@{x 94@}# 3) 2)))
829 The partial evaluator does not inline top-level bindings, though, so
830 this is a situation where you may find it interesting to use
831 @code{define-inlinable}.
833 Procedures defined with @code{define-inlinable} are @emph{always}
834 inlined, at all direct call sites. This eliminates function call
835 overhead at the expense of an increase in code size. Additionally, the
836 caller will not transparently use the new definition if the inline
837 procedure is redefined. It is not possible to trace an inlined
838 procedures or install a breakpoint in it (@pxref{Traps}). For these
839 reasons, you should not make a procedure inlinable unless it
840 demonstrably improves performance in a crucial way.
842 In general, only small procedures should be considered for inlining, as
843 making large procedures inlinable will probably result in an increase in
844 code size. Additionally, the elimination of the call overhead rarely
845 matters for large procedures.
847 @deffn {Scheme Syntax} define-inlinable (name parameter @dots{}) body1 body2 @dots{}
848 Define @var{name} as a procedure with parameters @var{parameter}s and
849 bodies @var{body1}, @var{body2}, @enddots{}.
853 @c TeX-master: "guile.texi"