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.
274 @node Optional Arguments
275 @subsection Optional Arguments
277 Scheme procedures, as defined in R5RS, can either handle a fixed number
278 of actual arguments, or a fixed number of actual arguments followed by
279 arbitrarily many additional arguments. Writing procedures of variable
280 arity can be useful, but unfortunately, the syntactic means for handling
281 argument lists of varying length is a bit inconvenient. It is possible
282 to give names to the fixed number of arguments, but the remaining
283 (optional) arguments can be only referenced as a list of values
286 For this reason, Guile provides an extension to @code{lambda},
287 @code{lambda*}, which allows the user to define procedures with
288 optional and keyword arguments. In addition, Guile's virtual machine
289 has low-level support for optional and keyword argument dispatch.
290 Calls to procedures with optional and keyword arguments can be made
291 cheaply, without allocating a rest list.
294 * lambda* and define*:: Creating advanced argument handling procedures.
295 * ice-9 optargs:: (ice-9 optargs) provides some utilities.
299 @node lambda* and define*
300 @subsubsection lambda* and define*.
302 @code{lambda*} is like @code{lambda}, except with some extensions to
303 allow optional and keyword arguments.
305 @deffn {library syntax} lambda* ([var@dots{}] @* [#:optional vardef@dots{}] @* [#:key vardef@dots{} [#:allow-other-keys]] @* [#:rest var | . var]) @* body
307 Create a procedure which takes optional and/or keyword arguments
308 specified with @code{#:optional} and @code{#:key}. For example,
311 (lambda* (a b #:optional c d . e) '())
314 is a procedure with fixed arguments @var{a} and @var{b}, optional
315 arguments @var{c} and @var{d}, and rest argument @var{e}. If the
316 optional arguments are omitted in a call, the variables for them are
320 Likewise, @code{define*} is syntactic sugar for defining procedures
321 using @code{lambda*}.
323 @code{lambda*} can also make procedures with keyword arguments. For
324 example, a procedure defined like this:
327 (define* (sir-yes-sir #:key action how-high)
328 (list action how-high))
331 can be called as @code{(sir-yes-sir #:action 'jump)},
332 @code{(sir-yes-sir #:how-high 13)}, @code{(sir-yes-sir #:action
333 'lay-down #:how-high 0)}, or just @code{(sir-yes-sir)}. Whichever
334 arguments are given as keywords are bound to values (and those not
335 given are @code{#f}).
337 Optional and keyword arguments can also have default values to take
338 when not present in a call, by giving a two-element list of variable
339 name and expression. For example in
342 (define* (frob foo #:optional (bar 42) #:key (baz 73))
346 @var{foo} is a fixed argument, @var{bar} is an optional argument with
347 default value 42, and baz is a keyword argument with default value 73.
348 Default value expressions are not evaluated unless they are needed,
349 and until the procedure is called.
351 Normally it's an error if a call has keywords other than those
352 specified by @code{#:key}, but adding @code{#:allow-other-keys} to the
353 definition (after the keyword argument declarations) will ignore
356 If a call has a keyword given twice, the last value is used. For
360 (define* (flips #:key (heads 0) (tails 0))
361 (display (list heads tails)))
363 (flips #:heads 37 #:tails 42 #:heads 99)
367 @code{#:rest} is a synonym for the dotted syntax rest argument. The
368 argument lists @code{(a . b)} and @code{(a #:rest b)} are equivalent
369 in all respects. This is provided for more similarity to DSSSL,
370 MIT-Scheme and Kawa among others, as well as for refugees from other
373 When @code{#:key} is used together with a rest argument, the keyword
374 parameters in a call all remain in the rest list. This is the same as
375 Common Lisp. For example,
378 ((lambda* (#:key (x 0) #:allow-other-keys #:rest r)
381 @print{} (#:x 123 #:y 456)
384 @code{#:optional} and @code{#:key} establish their bindings
385 successively, from left to right. This means default expressions can
386 refer back to prior parameters, for example
389 (lambda* (start #:optional (end (+ 10 start)))
390 (do ((i start (1+ i)))
395 The exception to this left-to-right scoping rule is the rest argument.
396 If there is a rest argument, it is bound after the optional arguments,
397 but before the keyword arguments.
402 @subsubsection (ice-9 optargs)
404 Before Guile 2.0, @code{lambda*} and @code{define*} were implemented
405 using macros that processed rest list arguments. This was not optimal,
406 as calling procedures with optional arguments had to allocate rest
407 lists at every procedure invocation. Guile 2.0 improved this
408 situation by bringing optional and keyword arguments into Guile's
411 However there are occasions in which you have a list and want to parse
412 it for optional or keyword arguments. Guile's @code{(ice-9 optargs)}
413 provides some macros to help with that task.
415 The syntax @code{let-optional} and @code{let-optional*} are for
416 destructuring rest argument lists and giving names to the various list
417 elements. @code{let-optional} binds all variables simultaneously, while
418 @code{let-optional*} binds them sequentially, consistent with @code{let}
419 and @code{let*} (@pxref{Local Bindings}).
421 @deffn {library syntax} let-optional rest-arg (binding @dots{}) body1 body2 @dots{}
422 @deffnx {library syntax} let-optional* rest-arg (binding @dots{}) body1 body2 @dots{}
423 These two macros give you an optional argument interface that is very
424 @dfn{Schemey} and introduces no fancy syntax. They are compatible with
425 the scsh macros of the same name, but are slightly extended. Each of
426 @var{binding} may be of one of the forms @var{var} or @code{(@var{var}
427 @var{default-value})}. @var{rest-arg} should be the rest-argument of the
428 procedures these are used from. The items in @var{rest-arg} are
429 sequentially bound to the variable names are given. When @var{rest-arg}
430 runs out, the remaining vars are bound either to the default values or
431 @code{#f} if no default value was specified. @var{rest-arg} remains
432 bound to whatever may have been left of @var{rest-arg}.
434 After binding the variables, the expressions @var{body1} @var{body2} @dots{}
435 are evaluated in order.
438 Similarly, @code{let-keywords} and @code{let-keywords*} extract values
439 from keyword style argument lists, binding local variables to those
440 values or to defaults.
442 @deffn {library syntax} let-keywords args allow-other-keys? (binding @dots{}) body1 body2 @dots{}
443 @deffnx {library syntax} let-keywords* args allow-other-keys? (binding @dots{}) body1 body2 @dots{}
444 @var{args} is evaluated and should give a list of the form
445 @code{(#:keyword1 value1 #:keyword2 value2 @dots{})}. The
446 @var{binding}s are variables and default expressions, with the variables
447 to be set (by name) from the keyword values. The @var{body1}
448 @var{body2} @dots{} forms are then evaluated and the last is the
449 result. An example will make the syntax clearest,
452 (define args '(#:xyzzy "hello" #:foo "world"))
454 (let-keywords args #t
455 ((foo "default for foo")
456 (bar (string-append "default" "for" "bar")))
460 @print{} world, defaultforbar
463 The binding for @code{foo} comes from the @code{#:foo} keyword in
464 @code{args}. But the binding for @code{bar} is the default in the
465 @code{let-keywords}, since there's no @code{#:bar} in the args.
467 @var{allow-other-keys?} is evaluated and controls whether unknown
468 keywords are allowed in the @var{args} list. When true other keys are
469 ignored (such as @code{#:xyzzy} in the example), when @code{#f} an
470 error is thrown for anything unknown.
473 @code{(ice-9 optargs)} also provides some more @code{define*} sugar,
474 which is not so useful with modern Guile coding, but still supported:
475 @code{define*-public} is the @code{lambda*} version of
476 @code{define-public}; @code{defmacro*} and @code{defmacro*-public}
477 exist for defining macros with the improved argument list handling
478 possibilities. The @code{-public} versions not only define the
479 procedures/macros, but also export them from the current module.
481 @deffn {library syntax} define*-public formals body1 body2 @dots{}
482 Like a mix of @code{define*} and @code{define-public}.
485 @deffn {library syntax} defmacro* name formals body1 body2 @dots{}
486 @deffnx {library syntax} defmacro*-public name formals body1 body2 @dots{}
487 These are just like @code{defmacro} and @code{defmacro-public} except that they
488 take @code{lambda*}-style extended parameter lists, where @code{#:optional},
489 @code{#:key}, @code{#:allow-other-keys} and @code{#:rest} are allowed with the usual
490 semantics. Here is an example of a macro with an optional argument:
493 (defmacro* transmogrify (a #:optional b)
499 @subsection Case-lambda
501 @cindex variable arity
502 @cindex arity, variable
504 R5RS's rest arguments are indeed useful and very general, but they
505 often aren't the most appropriate or efficient means to get the job
506 done. For example, @code{lambda*} is a much better solution to the
507 optional argument problem than @code{lambda} with rest arguments.
510 Likewise, @code{case-lambda} works well for when you want one
511 procedure to do double duty (or triple, or ...), without the penalty
512 of consing a rest list.
517 (define (make-accum n)
520 ((m) (set! n (+ n m)) n)))
522 (define a (make-accum 20))
528 The value returned by a @code{case-lambda} form is a procedure which
529 matches the number of actual arguments against the formals in the
530 various clauses, in order. The first matching clause is selected, the
531 corresponding values from the actual parameter list are bound to the
532 variable names in the clauses and the body of the clause is evaluated.
533 If no clause matches, an error is signalled.
535 The syntax of the @code{case-lambda} form is defined in the following
536 EBNF grammar. @dfn{Formals} means a formal argument list just like
537 with @code{lambda} (@pxref{Lambda}).
542 --> (case-lambda <case-lambda-clause>)
544 --> (<formals> <definition-or-command>*)
547 | (<identifier>* . <identifier>)
552 Rest lists can be useful with @code{case-lambda}:
560 ((a b . rest) (apply plus (+ a b) rest))))
561 (plus 1 2 3) @result{} 6
564 @fnindex case-lambda*
565 Also, for completeness. Guile defines @code{case-lambda*} as well,
566 which is like @code{case-lambda}, except with @code{lambda*} clauses.
567 A @code{case-lambda*} clause matches if the arguments fill the
568 required arguments, but are not too many for the optional and/or rest
571 Keyword arguments are possible with @code{case-lambda*}, but they do
572 not contribute to the ``matching'' behavior. That is to say,
573 @code{case-lambda*} matches only on required, optional, and rest
574 arguments, and on the predicate; keyword arguments may be present but
575 do not contribute to the ``success'' of a match. In fact a bad keyword
576 argument list may cause an error to be raised.
578 @node Higher-Order Functions
579 @subsection Higher-Order Functions
581 @cindex higher-order functions
583 As a functional programming language, Scheme allows the definition of
584 @dfn{higher-order functions}, i.e., functions that take functions as
585 arguments and/or return functions. Utilities to derive procedures from
586 other procedures are provided and described below.
588 @deffn {Scheme Procedure} const value
589 Return a procedure that accepts any number of arguments and returns
593 (procedure? (const 3)) @result{} #t
594 ((const 'hello)) @result{} hello
595 ((const 'hello) 'world) @result{} hello
599 @deffn {Scheme Procedure} negate proc
600 Return a procedure with the same arity as @var{proc} that returns the
601 @code{not} of @var{proc}'s result.
604 (procedure? (negate number?)) @result{} #t
605 ((negate odd?) 2) @result{} #t
606 ((negate real?) 'dream) @result{} #t
607 ((negate string-prefix?) "GNU" "GNU Guile")
609 (filter (negate number?) '(a 2 "b"))
614 @deffn {Scheme Procedure} compose proc1 proc2 @dots{}
615 Compose @var{proc1} with the procedures @var{proc2} @dots{} such that
616 the last @var{proc} argument is applied first and @var{proc1} last, and
617 return the resulting procedure. The given procedures must have
621 (procedure? (compose 1+ 1-)) @result{} #t
622 ((compose sqrt 1+ 1+) 2) @result{} 2.0
623 ((compose 1+ sqrt) 3) @result{} 2.73205080756888
624 (eq? (compose 1+) 1+) @result{} #t
626 ((compose zip unzip2) '((1 2) (a b)))
627 @result{} ((1 2) (a b))
631 @deffn {Scheme Procedure} identity x
635 @node Procedure Properties
636 @subsection Procedure Properties and Meta-information
638 In addition to the information that is strictly necessary to run,
639 procedures may have other associated information. For example, the
640 name of a procedure is information not for the procedure, but about
641 the procedure. This meta-information can be accessed via the procedure
642 properties interface.
644 The first group of procedures in this meta-interface are predicates to
645 test whether a Scheme object is a procedure, or a special procedure,
646 respectively. @code{procedure?} is the most general predicates, it
647 returns @code{#t} for any kind of procedure. @code{closure?} does not
648 return @code{#t} for primitive procedures, and @code{thunk?} only
649 returns @code{#t} for procedures which do not accept any arguments.
652 @deffn {Scheme Procedure} procedure? obj
653 @deffnx {C Function} scm_procedure_p (obj)
654 Return @code{#t} if @var{obj} is a procedure.
657 @deffn {Scheme Procedure} thunk? obj
658 @deffnx {C Function} scm_thunk_p (obj)
659 Return @code{#t} if @var{obj} is a thunk.
662 @cindex procedure properties
663 Procedure properties are general properties associated with
664 procedures. These can be the name of a procedure or other relevant
665 information, such as debug hints.
667 @deffn {Scheme Procedure} procedure-name proc
668 @deffnx {C Function} scm_procedure_name (proc)
669 Return the name of the procedure @var{proc}
672 @deffn {Scheme Procedure} procedure-source proc
673 @deffnx {C Function} scm_procedure_source (proc)
674 Return the source of the procedure @var{proc}. Returns @code{#f} if
675 the source code is not available.
678 @deffn {Scheme Procedure} procedure-properties proc
679 @deffnx {C Function} scm_procedure_properties (proc)
680 Return the properties associated with @var{proc}, as an association
684 @deffn {Scheme Procedure} procedure-property proc key
685 @deffnx {C Function} scm_procedure_property (proc, key)
686 Return the property of @var{proc} with name @var{key}.
689 @deffn {Scheme Procedure} set-procedure-properties! proc alist
690 @deffnx {C Function} scm_set_procedure_properties_x (proc, alist)
691 Set @var{proc}'s property list to @var{alist}.
694 @deffn {Scheme Procedure} set-procedure-property! proc key value
695 @deffnx {C Function} scm_set_procedure_property_x (proc, key, value)
696 In @var{proc}'s property list, set the property named @var{key} to
700 @cindex procedure documentation
701 Documentation for a procedure can be accessed with the procedure
702 @code{procedure-documentation}.
704 @deffn {Scheme Procedure} procedure-documentation proc
705 @deffnx {C Function} scm_procedure_documentation (proc)
706 Return the documentation string associated with @code{proc}. By
707 convention, if a procedure contains more than one expression and the
708 first expression is a string constant, that string is assumed to contain
709 documentation for that procedure.
713 @node Procedures with Setters
714 @subsection Procedures with Setters
716 @c FIXME::martin: Review me!
718 @c FIXME::martin: Document `operator struct'.
720 @cindex procedure with setter
722 A @dfn{procedure with setter} is a special kind of procedure which
723 normally behaves like any accessor procedure, that is a procedure which
724 accesses a data structure. The difference is that this kind of
725 procedure has a so-called @dfn{setter} attached, which is a procedure
726 for storing something into a data structure.
728 Procedures with setters are treated specially when the procedure appears
729 in the special form @code{set!} (REFFIXME). How it works is best shown
732 Suppose we have a procedure called @code{foo-ref}, which accepts two
733 arguments, a value of type @code{foo} and an integer. The procedure
734 returns the value stored at the given index in the @code{foo} object.
735 Let @code{f} be a variable containing such a @code{foo} data
736 structure.@footnote{Working definitions would be:
738 (define foo-ref vector-ref)
739 (define foo-set! vector-set!)
740 (define f (make-vector 2 #f))
745 (foo-ref f 0) @result{} bar
746 (foo-ref f 1) @result{} braz
749 Also suppose that a corresponding setter procedure called
750 @code{foo-set!} does exist.
754 (foo-ref f 0) @result{} bla
757 Now we could create a new procedure called @code{foo}, which is a
758 procedure with setter, by calling @code{make-procedure-with-setter} with
759 the accessor and setter procedures @code{foo-ref} and @code{foo-set!}.
760 Let us call this new procedure @code{foo}.
763 (define foo (make-procedure-with-setter foo-ref foo-set!))
766 @code{foo} can from now an be used to either read from the data
767 structure stored in @code{f}, or to write into the structure.
770 (set! (foo f 0) 'dum)
771 (foo f 0) @result{} dum
774 @deffn {Scheme Procedure} make-procedure-with-setter procedure setter
775 @deffnx {C Function} scm_make_procedure_with_setter (procedure, setter)
776 Create a new procedure which behaves like @var{procedure}, but
777 with the associated setter @var{setter}.
780 @deffn {Scheme Procedure} procedure-with-setter? obj
781 @deffnx {C Function} scm_procedure_with_setter_p (obj)
782 Return @code{#t} if @var{obj} is a procedure with an
783 associated setter procedure.
786 @deffn {Scheme Procedure} procedure proc
787 @deffnx {C Function} scm_procedure (proc)
788 Return the procedure of @var{proc}, which must be an
792 @deffn {Scheme Procedure} setter proc
793 Return the setter of @var{proc}, which must be either a procedure with
794 setter or an operator struct.
797 @node Inlinable Procedures
798 @subsection Inlinable Procedures
801 @cindex procedure inlining
802 You can define an @dfn{inlinable procedure} by using
803 @code{define-inlinable} instead of @code{define}. An inlinable
804 procedure behaves the same as a regular procedure, but direct calls will
805 result in the procedure body being inlined into the caller.
807 @cindex partial evaluator
808 Bear in mind that starting from version 2.0.3, Guile has a partial
809 evaluator that can inline the body of inner procedures when deemed
813 scheme@@(guile-user)> ,optimize (define (foo x)
814 (define (bar) (+ x 3))
817 (lambda (#@{x 94@}#) (* (+ #@{x 94@}# 3) 2)))
821 The partial evaluator does not inline top-level bindings, though, so
822 this is a situation where you may find it interesting to use
823 @code{define-inlinable}.
825 Procedures defined with @code{define-inlinable} are @emph{always}
826 inlined, at all direct call sites. This eliminates function call
827 overhead at the expense of an increase in code size. Additionally, the
828 caller will not transparently use the new definition if the inline
829 procedure is redefined. It is not possible to trace an inlined
830 procedures or install a breakpoint in it (@pxref{Traps}). For these
831 reasons, you should not make a procedure inlinable unless it
832 demonstrably improves performance in a crucial way.
834 In general, only small procedures should be considered for inlining, as
835 making large procedures inlinable will probably result in an increase in
836 code size. Additionally, the elimination of the call overhead rarely
837 matters for large procedures.
839 @deffn {Scheme Syntax} define-inlinable (name parameter @dots{}) body1 body2 @dots{}
840 Define @var{name} as a procedure with parameters @var{parameter}s and
841 bodies @var{body1}, @var{body2}, @enddots{}.
845 @c TeX-master: "guile.texi"