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-objcode program
165 @deffnx {C Function} scm_program_objcode (program)
166 Returns the object code associated with this program. @xref{Bytecode
167 and Objcode}, for more information.
170 @deffn {Scheme Procedure} program-objects program
171 @deffnx {C Function} scm_program_objects (program)
172 Returns the ``object table'' associated with this program, as a
173 vector. @xref{VM Programs}, for more information.
176 @deffn {Scheme Procedure} program-module program
177 @deffnx {C Function} scm_program_module (program)
178 Returns the module that was current when this program was created. Can
179 return @code{#f} if the compiler could determine that this information
183 @deffn {Scheme Procedure} program-free-variables program
184 @deffnx {C Function} scm_program_free_variables (program)
185 Returns the set of free variables that this program captures in its
186 closure, as a vector. If a closure is code with data, you can get the
187 code from @code{program-objcode}, and the data via
188 @code{program-free-variables}.
190 Some of the values captured are actually in variable ``boxes''.
191 @xref{Variables and the VM}, for more information.
193 Users must not modify the returned value unless they think they're
197 @deffn {Scheme Procedure} program-meta program
198 @deffnx {C Function} scm_program_meta (program)
199 Return the metadata thunk of @var{program}, or @code{#f} if it has no
202 When called, a metadata thunk returns a list of the following form:
203 @code{(@var{bindings} @var{sources} @var{arities} . @var{properties})}. The format
204 of each of these elements is discussed below.
207 @deffn {Scheme Procedure} program-bindings program
208 @deffnx {Scheme Procedure} make-binding name boxed? index start end
209 @deffnx {Scheme Procedure} binding:name binding
210 @deffnx {Scheme Procedure} binding:boxed? binding
211 @deffnx {Scheme Procedure} binding:index binding
212 @deffnx {Scheme Procedure} binding:start binding
213 @deffnx {Scheme Procedure} binding:end binding
214 Bindings annotations for programs, along with their accessors.
216 Bindings declare names and liveness extents for block-local variables.
217 The best way to see what these are is to play around with them at a
218 REPL. @xref{VM Concepts}, for more information.
220 Note that bindings information is stored in a program as part of its
221 metadata thunk, so including it in the generated object code does not
222 impose a runtime performance penalty.
225 @deffn {Scheme Procedure} program-sources program
226 @deffnx {Scheme Procedure} source:addr source
227 @deffnx {Scheme Procedure} source:line source
228 @deffnx {Scheme Procedure} source:column source
229 @deffnx {Scheme Procedure} source:file source
230 Source location annotations for programs, along with their accessors.
232 Source location information propagates through the compiler and ends
233 up being serialized to the program's metadata. This information is
234 keyed by the offset of the instruction pointer within the object code
235 of the program. Specifically, it is keyed on the @code{ip} @emph{just
236 following} an instruction, so that backtraces can find the source
237 location of a call that is in progress.
240 @deffn {Scheme Procedure} program-arities program
241 @deffnx {C Function} scm_program_arities (program)
242 @deffnx {Scheme Procedure} program-arity program ip
243 @deffnx {Scheme Procedure} arity:start arity
244 @deffnx {Scheme Procedure} arity:end arity
245 @deffnx {Scheme Procedure} arity:nreq arity
246 @deffnx {Scheme Procedure} arity:nopt arity
247 @deffnx {Scheme Procedure} arity:rest? arity
248 @deffnx {Scheme Procedure} arity:kw arity
249 @deffnx {Scheme Procedure} arity:allow-other-keys? arity
250 Accessors for a representation of the ``arity'' of a program.
252 The normal case is that a procedure has one arity. For example,
253 @code{(lambda (x) x)}, takes one required argument, and that's it. One
254 could access that number of required arguments via @code{(arity:nreq
255 (program-arities (lambda (x) x)))}. Similarly, @code{arity:nopt} gets
256 the number of optional arguments, and @code{arity:rest?} returns a true
257 value if the procedure has a rest arg.
259 @code{arity:kw} returns a list of @code{(@var{kw} . @var{idx})} pairs,
260 if the procedure has keyword arguments. The @var{idx} refers to the
261 @var{idx}th local variable; @xref{Variables and the VM}, for more
262 information. Finally @code{arity:allow-other-keys?} returns a true
263 value if other keys are allowed. @xref{Optional Arguments}, for more
266 So what about @code{arity:start} and @code{arity:end}, then? They
267 return the range of bytes in the program's bytecode for which a given
268 arity is valid. You see, a procedure can actually have more than one
269 arity. The question, ``what is a procedure's arity'' only really makes
270 sense at certain points in the program, delimited by these
271 @code{arity:start} and @code{arity:end} values.
274 @deffn {Scheme Procedure} program-arguments-alist program [ip]
275 Return an association list describing the arguments that @var{program} accepts, or
276 @code{#f} if the information cannot be obtained.
278 The alist keys that are currently defined are `required', `optional',
279 `keyword', `allow-other-keys?', and `rest'. For example:
282 (program-arguments-alist
283 (lambda* (a b #:optional c #:key (d 1) #:rest e)
287 (keyword . ((#:d . 4)))
288 (allow-other-keys? . #f)
293 @deffn {Scheme Procedure} program-lambda-list program [ip]
294 Return a representation of the arguments of @var{program} as a lambda
295 list, or @code{#f} if this information is not available.
301 (lambda* (a b #:optional c #:key (d 1) #:rest e)
306 @node Optional Arguments
307 @subsection Optional Arguments
309 Scheme procedures, as defined in R5RS, can either handle a fixed number
310 of actual arguments, or a fixed number of actual arguments followed by
311 arbitrarily many additional arguments. Writing procedures of variable
312 arity can be useful, but unfortunately, the syntactic means for handling
313 argument lists of varying length is a bit inconvenient. It is possible
314 to give names to the fixed number of arguments, but the remaining
315 (optional) arguments can be only referenced as a list of values
318 For this reason, Guile provides an extension to @code{lambda},
319 @code{lambda*}, which allows the user to define procedures with
320 optional and keyword arguments. In addition, Guile's virtual machine
321 has low-level support for optional and keyword argument dispatch.
322 Calls to procedures with optional and keyword arguments can be made
323 cheaply, without allocating a rest list.
326 * lambda* and define*:: Creating advanced argument handling procedures.
327 * ice-9 optargs:: (ice-9 optargs) provides some utilities.
331 @node lambda* and define*
332 @subsubsection lambda* and define*.
334 @code{lambda*} is like @code{lambda}, except with some extensions to
335 allow optional and keyword arguments.
337 @deffn {library syntax} lambda* ([var@dots{}] @* @
338 [#:optional vardef@dots{}] @* @
339 [#:key vardef@dots{} [#:allow-other-keys]] @* @
340 [#:rest var | . var]) @* @
343 Create a procedure which takes optional and/or keyword arguments
344 specified with @code{#:optional} and @code{#:key}. For example,
347 (lambda* (a b #:optional c d . e) '())
350 is a procedure with fixed arguments @var{a} and @var{b}, optional
351 arguments @var{c} and @var{d}, and rest argument @var{e}. If the
352 optional arguments are omitted in a call, the variables for them are
356 Likewise, @code{define*} is syntactic sugar for defining procedures
357 using @code{lambda*}.
359 @code{lambda*} can also make procedures with keyword arguments. For
360 example, a procedure defined like this:
363 (define* (sir-yes-sir #:key action how-high)
364 (list action how-high))
367 can be called as @code{(sir-yes-sir #:action 'jump)},
368 @code{(sir-yes-sir #:how-high 13)}, @code{(sir-yes-sir #:action
369 'lay-down #:how-high 0)}, or just @code{(sir-yes-sir)}. Whichever
370 arguments are given as keywords are bound to values (and those not
371 given are @code{#f}).
373 Optional and keyword arguments can also have default values to take
374 when not present in a call, by giving a two-element list of variable
375 name and expression. For example in
378 (define* (frob foo #:optional (bar 42) #:key (baz 73))
382 @var{foo} is a fixed argument, @var{bar} is an optional argument with
383 default value 42, and baz is a keyword argument with default value 73.
384 Default value expressions are not evaluated unless they are needed,
385 and until the procedure is called.
387 Normally it's an error if a call has keywords other than those
388 specified by @code{#:key}, but adding @code{#:allow-other-keys} to the
389 definition (after the keyword argument declarations) will ignore
392 If a call has a keyword given twice, the last value is used. For
396 (define* (flips #:key (heads 0) (tails 0))
397 (display (list heads tails)))
399 (flips #:heads 37 #:tails 42 #:heads 99)
403 @code{#:rest} is a synonym for the dotted syntax rest argument. The
404 argument lists @code{(a . b)} and @code{(a #:rest b)} are equivalent
405 in all respects. This is provided for more similarity to DSSSL,
406 MIT-Scheme and Kawa among others, as well as for refugees from other
409 When @code{#:key} is used together with a rest argument, the keyword
410 parameters in a call all remain in the rest list. This is the same as
411 Common Lisp. For example,
414 ((lambda* (#:key (x 0) #:allow-other-keys #:rest r)
417 @print{} (#:x 123 #:y 456)
420 @code{#:optional} and @code{#:key} establish their bindings
421 successively, from left to right. This means default expressions can
422 refer back to prior parameters, for example
425 (lambda* (start #:optional (end (+ 10 start)))
426 (do ((i start (1+ i)))
431 The exception to this left-to-right scoping rule is the rest argument.
432 If there is a rest argument, it is bound after the optional arguments,
433 but before the keyword arguments.
438 @subsubsection (ice-9 optargs)
440 Before Guile 2.0, @code{lambda*} and @code{define*} were implemented
441 using macros that processed rest list arguments. This was not optimal,
442 as calling procedures with optional arguments had to allocate rest
443 lists at every procedure invocation. Guile 2.0 improved this
444 situation by bringing optional and keyword arguments into Guile's
447 However there are occasions in which you have a list and want to parse
448 it for optional or keyword arguments. Guile's @code{(ice-9 optargs)}
449 provides some macros to help with that task.
451 The syntax @code{let-optional} and @code{let-optional*} are for
452 destructuring rest argument lists and giving names to the various list
453 elements. @code{let-optional} binds all variables simultaneously, while
454 @code{let-optional*} binds them sequentially, consistent with @code{let}
455 and @code{let*} (@pxref{Local Bindings}).
457 @deffn {library syntax} let-optional rest-arg (binding @dots{}) body1 body2 @dots{}
458 @deffnx {library syntax} let-optional* rest-arg (binding @dots{}) body1 body2 @dots{}
459 These two macros give you an optional argument interface that is very
460 @dfn{Schemey} and introduces no fancy syntax. They are compatible with
461 the scsh macros of the same name, but are slightly extended. Each of
462 @var{binding} may be of one of the forms @var{var} or @code{(@var{var}
463 @var{default-value})}. @var{rest-arg} should be the rest-argument of the
464 procedures these are used from. The items in @var{rest-arg} are
465 sequentially bound to the variable names are given. When @var{rest-arg}
466 runs out, the remaining vars are bound either to the default values or
467 @code{#f} if no default value was specified. @var{rest-arg} remains
468 bound to whatever may have been left of @var{rest-arg}.
470 After binding the variables, the expressions @var{body1} @var{body2} @dots{}
471 are evaluated in order.
474 Similarly, @code{let-keywords} and @code{let-keywords*} extract values
475 from keyword style argument lists, binding local variables to those
476 values or to defaults.
478 @deffn {library syntax} let-keywords args allow-other-keys? (binding @dots{}) body1 body2 @dots{}
479 @deffnx {library syntax} let-keywords* args allow-other-keys? (binding @dots{}) body1 body2 @dots{}
480 @var{args} is evaluated and should give a list of the form
481 @code{(#:keyword1 value1 #:keyword2 value2 @dots{})}. The
482 @var{binding}s are variables and default expressions, with the variables
483 to be set (by name) from the keyword values. The @var{body1}
484 @var{body2} @dots{} forms are then evaluated and the last is the
485 result. An example will make the syntax clearest,
488 (define args '(#:xyzzy "hello" #:foo "world"))
490 (let-keywords args #t
491 ((foo "default for foo")
492 (bar (string-append "default" "for" "bar")))
496 @print{} world, defaultforbar
499 The binding for @code{foo} comes from the @code{#:foo} keyword in
500 @code{args}. But the binding for @code{bar} is the default in the
501 @code{let-keywords}, since there's no @code{#:bar} in the args.
503 @var{allow-other-keys?} is evaluated and controls whether unknown
504 keywords are allowed in the @var{args} list. When true other keys are
505 ignored (such as @code{#:xyzzy} in the example), when @code{#f} an
506 error is thrown for anything unknown.
509 @code{(ice-9 optargs)} also provides some more @code{define*} sugar,
510 which is not so useful with modern Guile coding, but still supported:
511 @code{define*-public} is the @code{lambda*} version of
512 @code{define-public}; @code{defmacro*} and @code{defmacro*-public}
513 exist for defining macros with the improved argument list handling
514 possibilities. The @code{-public} versions not only define the
515 procedures/macros, but also export them from the current module.
517 @deffn {library syntax} define*-public formals body1 body2 @dots{}
518 Like a mix of @code{define*} and @code{define-public}.
521 @deffn {library syntax} defmacro* name formals body1 body2 @dots{}
522 @deffnx {library syntax} defmacro*-public name formals body1 body2 @dots{}
523 These are just like @code{defmacro} and @code{defmacro-public} except that they
524 take @code{lambda*}-style extended parameter lists, where @code{#:optional},
525 @code{#:key}, @code{#:allow-other-keys} and @code{#:rest} are allowed with the usual
526 semantics. Here is an example of a macro with an optional argument:
529 (defmacro* transmogrify (a #:optional b)
535 @subsection Case-lambda
537 @cindex variable arity
538 @cindex arity, variable
540 R5RS's rest arguments are indeed useful and very general, but they
541 often aren't the most appropriate or efficient means to get the job
542 done. For example, @code{lambda*} is a much better solution to the
543 optional argument problem than @code{lambda} with rest arguments.
546 Likewise, @code{case-lambda} works well for when you want one
547 procedure to do double duty (or triple, or ...), without the penalty
548 of consing a rest list.
553 (define (make-accum n)
556 ((m) (set! n (+ n m)) n)))
558 (define a (make-accum 20))
564 The value returned by a @code{case-lambda} form is a procedure which
565 matches the number of actual arguments against the formals in the
566 various clauses, in order. The first matching clause is selected, the
567 corresponding values from the actual parameter list are bound to the
568 variable names in the clauses and the body of the clause is evaluated.
569 If no clause matches, an error is signalled.
571 The syntax of the @code{case-lambda} form is defined in the following
572 EBNF grammar. @dfn{Formals} means a formal argument list just like
573 with @code{lambda} (@pxref{Lambda}).
578 --> (case-lambda <case-lambda-clause>*)
579 --> (case-lambda <docstring> <case-lambda-clause>*)
581 --> (<formals> <definition-or-command>*)
584 | (<identifier>* . <identifier>)
589 Rest lists can be useful with @code{case-lambda}:
594 "Return the sum of all arguments."
598 ((a b . rest) (apply plus (+ a b) rest))))
599 (plus 1 2 3) @result{} 6
602 @fnindex case-lambda*
603 Also, for completeness. Guile defines @code{case-lambda*} as well,
604 which is like @code{case-lambda}, except with @code{lambda*} clauses.
605 A @code{case-lambda*} clause matches if the arguments fill the
606 required arguments, but are not too many for the optional and/or rest
609 Keyword arguments are possible with @code{case-lambda*} as well, but
610 they do not contribute to the ``matching'' behavior, and their
611 interactions with required, optional, and rest arguments can be
614 For the purposes of @code{case-lambda*} (and of @code{case-lambda}, as a
615 special case), a clause @dfn{matches} if it has enough required
616 arguments, and not too many positional arguments. The required
617 arguments are any arguments before the @code{#:optional}, @code{#:key},
618 and @code{#:rest} arguments. @dfn{Positional} arguments are the
619 required arguments, together with the optional arguments.
621 In the absence of @code{#:key} or @code{#:rest} arguments, it's easy to
622 see how there could be too many positional arguments: you pass 5
623 arguments to a function that only takes 4 arguments, including optional
624 arguments. If there is a @code{#:rest} argument, there can never be too
625 many positional arguments: any application with enough required
626 arguments for a clause will match that clause, even if there are also
627 @code{#:key} arguments.
629 Otherwise, for applications to a clause with @code{#:key} arguments (and
630 without a @code{#:rest} argument), a clause will match there only if
631 there are enough required arguments and if the next argument after
632 binding required and optional arguments, if any, is a keyword. For
633 efficiency reasons, Guile is currently unable to include keyword
634 arguments in the matching algorithm. Clauses match on positional
635 arguments only, not by comparing a given keyword to the available set of
636 keyword arguments that a function has.
638 Some examples follow.
643 ((a #:optional b) 'clause-1)
644 ((a #:optional b #:key c) 'clause-2)
645 ((a #:key d) 'clause-3)
646 ((#:key e #:rest f) 'clause-4)))
648 (f) @result{} clause-4
649 (f 1) @result{} clause-1
650 (f) @result{} clause-4
654 (f #:a #:b #:c #:d #:e) clause-4
656 ;; clause-2 will match anything that clause-3 would match.
657 (f 1 #:d 2) @result{} error: bad keyword args in clause 2
660 Don't forget that the clauses are matched in order, and the first
661 matching clause will be taken. This can result in a keyword being bound
662 to a required argument, as in the case of @code{f #:e 10}.
665 @node Higher-Order Functions
666 @subsection Higher-Order Functions
668 @cindex higher-order functions
670 As a functional programming language, Scheme allows the definition of
671 @dfn{higher-order functions}, i.e., functions that take functions as
672 arguments and/or return functions. Utilities to derive procedures from
673 other procedures are provided and described below.
675 @deffn {Scheme Procedure} const value
676 Return a procedure that accepts any number of arguments and returns
680 (procedure? (const 3)) @result{} #t
681 ((const 'hello)) @result{} hello
682 ((const 'hello) 'world) @result{} hello
686 @deffn {Scheme Procedure} negate proc
687 Return a procedure with the same arity as @var{proc} that returns the
688 @code{not} of @var{proc}'s result.
691 (procedure? (negate number?)) @result{} #t
692 ((negate odd?) 2) @result{} #t
693 ((negate real?) 'dream) @result{} #t
694 ((negate string-prefix?) "GNU" "GNU Guile")
696 (filter (negate number?) '(a 2 "b"))
701 @deffn {Scheme Procedure} compose proc1 proc2 @dots{}
702 Compose @var{proc1} with the procedures @var{proc2} @dots{} such that
703 the last @var{proc} argument is applied first and @var{proc1} last, and
704 return the resulting procedure. The given procedures must have
708 (procedure? (compose 1+ 1-)) @result{} #t
709 ((compose sqrt 1+ 1+) 2) @result{} 2.0
710 ((compose 1+ sqrt) 3) @result{} 2.73205080756888
711 (eq? (compose 1+) 1+) @result{} #t
713 ((compose zip unzip2) '((1 2) (a b)))
714 @result{} ((1 2) (a b))
718 @deffn {Scheme Procedure} identity x
722 @deffn {Scheme Procedure} and=> value proc
723 When @var{value} is @code{#f}, return @code{#f}. Otherwise, return
724 @code{(@var{proc} @var{value})}.
727 @node Procedure Properties
728 @subsection Procedure Properties and Meta-information
730 In addition to the information that is strictly necessary to run,
731 procedures may have other associated information. For example, the
732 name of a procedure is information not for the procedure, but about
733 the procedure. This meta-information can be accessed via the procedure
734 properties interface.
736 The first group of procedures in this meta-interface are predicates to
737 test whether a Scheme object is a procedure, or a special procedure,
738 respectively. @code{procedure?} is the most general predicates, it
739 returns @code{#t} for any kind of procedure.
742 @deffn {Scheme Procedure} procedure? obj
743 @deffnx {C Function} scm_procedure_p (obj)
744 Return @code{#t} if @var{obj} is a procedure.
747 @deffn {Scheme Procedure} thunk? obj
748 @deffnx {C Function} scm_thunk_p (obj)
749 Return @code{#t} if @var{obj} is a thunk---a procedure that does
750 not accept arguments.
753 @cindex procedure properties
754 Procedure properties are general properties associated with
755 procedures. These can be the name of a procedure or other relevant
756 information, such as debug hints.
758 @deffn {Scheme Procedure} procedure-name proc
759 @deffnx {C Function} scm_procedure_name (proc)
760 Return the name of the procedure @var{proc}
763 @deffn {Scheme Procedure} procedure-source proc
764 @deffnx {C Function} scm_procedure_source (proc)
765 Return the source of the procedure @var{proc}. Returns @code{#f} if
766 the source code is not available.
769 @deffn {Scheme Procedure} procedure-properties proc
770 @deffnx {C Function} scm_procedure_properties (proc)
771 Return the properties associated with @var{proc}, as an association
775 @deffn {Scheme Procedure} procedure-property proc key
776 @deffnx {C Function} scm_procedure_property (proc, key)
777 Return the property of @var{proc} with name @var{key}.
780 @deffn {Scheme Procedure} set-procedure-properties! proc alist
781 @deffnx {C Function} scm_set_procedure_properties_x (proc, alist)
782 Set @var{proc}'s property list to @var{alist}.
785 @deffn {Scheme Procedure} set-procedure-property! proc key value
786 @deffnx {C Function} scm_set_procedure_property_x (proc, key, value)
787 In @var{proc}'s property list, set the property named @var{key} to
791 @cindex procedure documentation
792 Documentation for a procedure can be accessed with the procedure
793 @code{procedure-documentation}.
795 @deffn {Scheme Procedure} procedure-documentation proc
796 @deffnx {C Function} scm_procedure_documentation (proc)
797 Return the documentation string associated with @code{proc}. By
798 convention, if a procedure contains more than one expression and the
799 first expression is a string constant, that string is assumed to contain
800 documentation for that procedure.
804 @node Procedures with Setters
805 @subsection Procedures with Setters
807 @c FIXME::martin: Review me!
809 @c FIXME::martin: Document `operator struct'.
811 @cindex procedure with setter
813 A @dfn{procedure with setter} is a special kind of procedure which
814 normally behaves like any accessor procedure, that is a procedure which
815 accesses a data structure. The difference is that this kind of
816 procedure has a so-called @dfn{setter} attached, which is a procedure
817 for storing something into a data structure.
819 Procedures with setters are treated specially when the procedure appears
820 in the special form @code{set!} (REFFIXME). How it works is best shown
823 Suppose we have a procedure called @code{foo-ref}, which accepts two
824 arguments, a value of type @code{foo} and an integer. The procedure
825 returns the value stored at the given index in the @code{foo} object.
826 Let @code{f} be a variable containing such a @code{foo} data
827 structure.@footnote{Working definitions would be:
829 (define foo-ref vector-ref)
830 (define foo-set! vector-set!)
831 (define f (make-vector 2 #f))
836 (foo-ref f 0) @result{} bar
837 (foo-ref f 1) @result{} braz
840 Also suppose that a corresponding setter procedure called
841 @code{foo-set!} does exist.
845 (foo-ref f 0) @result{} bla
848 Now we could create a new procedure called @code{foo}, which is a
849 procedure with setter, by calling @code{make-procedure-with-setter} with
850 the accessor and setter procedures @code{foo-ref} and @code{foo-set!}.
851 Let us call this new procedure @code{foo}.
854 (define foo (make-procedure-with-setter foo-ref foo-set!))
857 @code{foo} can from now an be used to either read from the data
858 structure stored in @code{f}, or to write into the structure.
861 (set! (foo f 0) 'dum)
862 (foo f 0) @result{} dum
865 @deffn {Scheme Procedure} make-procedure-with-setter procedure setter
866 @deffnx {C Function} scm_make_procedure_with_setter (procedure, setter)
867 Create a new procedure which behaves like @var{procedure}, but
868 with the associated setter @var{setter}.
871 @deffn {Scheme Procedure} procedure-with-setter? obj
872 @deffnx {C Function} scm_procedure_with_setter_p (obj)
873 Return @code{#t} if @var{obj} is a procedure with an
874 associated setter procedure.
877 @deffn {Scheme Procedure} procedure proc
878 @deffnx {C Function} scm_procedure (proc)
879 Return the procedure of @var{proc}, which must be an
883 @deffn {Scheme Procedure} setter proc
884 Return the setter of @var{proc}, which must be either a procedure with
885 setter or an operator struct.
888 @node Inlinable Procedures
889 @subsection Inlinable Procedures
892 @cindex procedure inlining
893 You can define an @dfn{inlinable procedure} by using
894 @code{define-inlinable} instead of @code{define}. An inlinable
895 procedure behaves the same as a regular procedure, but direct calls will
896 result in the procedure body being inlined into the caller.
898 @cindex partial evaluator
899 Bear in mind that starting from version 2.0.3, Guile has a partial
900 evaluator that can inline the body of inner procedures when deemed
904 scheme@@(guile-user)> ,optimize (define (foo x)
905 (define (bar) (+ x 3))
908 (lambda (#@{x 94@}#) (* (+ #@{x 94@}# 3) 2)))
912 The partial evaluator does not inline top-level bindings, though, so
913 this is a situation where you may find it interesting to use
914 @code{define-inlinable}.
916 Procedures defined with @code{define-inlinable} are @emph{always}
917 inlined, at all direct call sites. This eliminates function call
918 overhead at the expense of an increase in code size. Additionally, the
919 caller will not transparently use the new definition if the inline
920 procedure is redefined. It is not possible to trace an inlined
921 procedures or install a breakpoint in it (@pxref{Traps}). For these
922 reasons, you should not make a procedure inlinable unless it
923 demonstrably improves performance in a crucial way.
925 In general, only small procedures should be considered for inlining, as
926 making large procedures inlinable will probably result in an increase in
927 code size. Additionally, the elimination of the call overhead rarely
928 matters for large procedures.
930 @deffn {Scheme Syntax} define-inlinable (name parameter @dots{}) body1 body2 @dots{}
931 Define @var{name} as a procedure with parameters @var{parameter}s and
932 bodies @var{body1}, @var{body2}, @enddots{}.
936 @c TeX-master: "guile.texi"