Procedures
==========

Lambda: Basic Procedure Creation
--------------------------------

A lambda expression evaluates to a procedure.  The environment which is in effect when a lambda expression is evaluated is enclosed in the newly created procedure, this is referred to as a closure (see About Closure).

When a procedure created by lambda is called with some actual arguments, the environment enclosed in the procedure is extended by binding the variables named in the formal argument list to new locations and storing the actual arguments into these locations.  Then the body of the lambda expression is evaluated sequentially.  The result of the last expression in the procedure body is then the result of the procedure invocation.

The following examples will show how procedures can be created using lambda, and what you can do with these procedures.

     (lambda (x) (+ x x))       => a procedure
     ((lambda (x) (+ x x)) 4)   => 8

The fact that the environment in effect when creating a procedure is enclosed in the procedure is shown with this example:

     (define add4
       (let ((x 4))
         (lambda (y) (+ x y))))
     (add4 6)                   => 10

 -- syntax: lambda formals body
     FORMALS should be a formal argument list as described in the following table.

     (VARIABLE1 ...)
          The procedure takes a fixed number of arguments; when the procedure is called, the arguments will be stored into the newly created location for the formal variables.

     VARIABLE
          The procedure takes any number of arguments; when the procedure is called, the sequence of actual arguments will converted into a list and stored into the newly created location for the formal variable.

     (VARIABLE1 ... VARIABLEN . VARIABLEN+1)
          If a space-delimited period precedes the last variable, then the procedure takes N or more variables where N is the number of formal arguments before the period.  There must be at least one argument before the period.  The first N actual arguments will be stored into the newly allocated locations for the first N formal arguments and the sequence of the remaining actual arguments is converted into a list and the stored into the location for the last formal argument.  If there are exactly N actual arguments, the empty list is stored into the location of the last formal argument.

     The list in VARIABLE or VARIABLEN+1 is always newly created and the procedure can modify it if desired.  This is the case even when the procedure is invoked via apply, the required part of the list argument there will be copied (see Procedures for On the Fly Evaluation).

     BODY is a sequence of Scheme expressions which are evaluated in order when the procedure is invoked.

Primitive Procedures
--------------------

Procedures written in C can be registered for use from Scheme, provided they take only arguments of type SCM and return SCM values.  scm_c_define_gsubr is likely to be the most useful mechanism, combining the process of registration (scm_c_make_gsubr) and definition (scm_define).

 -- Function: SCM scm_c_make_gsubr (const char *name, int req, int opt, int rst, fcn)
     Register a C procedure FCN as a ``subr'' --- a primitive subroutine that can be called from Scheme.  It will be associated with the given NAME but no environment binding will be created.  The arguments REQ, OPT and RST specify the number of required, optional and ``rest'' arguments respectively.  The total number of these arguments should match the actual number of arguments to FCN, but may not exceed 10.  The number of rest arguments should be 0 or 1. scm_c_make_gsubr returns a value of type SCM which is a ``handle'' for the procedure.

 -- Function: SCM scm_c_define_gsubr (const char *name, int req, int opt, int rst, fcn)
     Register a C procedure FCN, as for scm_c_make_gsubr above, and additionally create a top-level Scheme binding for the procedure in the ``current environment'' using scm_define. scm_c_define_gsubr returns a handle for the procedure in the same way as scm_c_make_gsubr, which is usually not further required.

scm_c_make_gsubr and scm_c_define_gsubr automatically use scm_c_make_subr and also scm_makcclo if necessary. It is advisable to use the gsubr variants since they provide a slightly higher-level abstraction of the Guile implementation.

Compiled Procedures
-------------------

In Guile, procedures can be executed by directly interpreting their source code. Scheme source code is a set of nested lists, after all, with each list representing a procedure call.

Most procedures are compiled, however. This means that Guile has done some pre-computation on the procedure, to determine what it will need to do each time the procedure runs. Compiled procedures run faster than interpreted procedures.

Loading files is the normal way that compiled procedures come to being. If Guile sees that a file is uncompiled, or that its compiled file is out of date, it will attempt to compile the file when it is loaded, and save the result to disk. Procedures can be compiled at runtime as well. See Read/Load/Eval/Compile, for more information on runtime compilation.

Compiled procedures, also known as programs, respond all procedures that operate on procedures. In addition, there are a few more accessors for low-level details on programs.

Most people won't need to use the routines described in this section, but it's good to have them documented. You'll have to include the appropriate module first, though:

     (use-modules (system vm program))

 -- Scheme Procedure: program? obj
 -- C Function: scm_program_p (obj)
     Returns #t iff OBJ is a compiled procedure.

 -- Scheme Procedure: program-objcode program
 -- C Function: scm_program_objcode (program)
     Returns the object code associated with this program. See Bytecode and Objcode, for more information.

 -- Scheme Procedure: program-objects program
 -- C Function: scm_program_objects (program)
     Returns the ``object table'' associated with this program, as a vector. See VM Programs, for more information.

 -- Scheme Procedure: program-module program
 -- C Function: scm_program_module (program)
     Returns the module that was current when this program was created. Can return #f if the compiler could determine that this information was unnecessary.

 -- Scheme Procedure: program-free-variables program
 -- C Function: scm_program_free_variables (program)
     Returns the set of free variables that this program captures in its closure, as a vector. If a closure is code with data, you can get the code from program-objcode, and the data via program-free-variables.

     Some of the values captured are actually in variable ``boxes''. See Variables and the VM, for more information.

     Users must not modify the returned value unless they think they're really clever.

 -- Scheme Procedure: program-meta program
 -- C Function: scm_program_meta (program)
     Return the metadata thunk of PROGRAM, or #f if it has no metadata.

     When called, a metadata thunk returns a list of the following form: (BINDINGS SOURCES ARITIES . PROPERTIES). The format of each of these elements is discussed below.

 -- Scheme Procedure: program-bindings program
 -- Scheme Procedure: make-binding name boxed? index start end
 -- Scheme Procedure: binding:name binding
 -- Scheme Procedure: binding:boxed? binding
 -- Scheme Procedure: binding:index binding
 -- Scheme Procedure: binding:start binding
 -- Scheme Procedure: binding:end binding
     Bindings annotations for programs, along with their accessors.

     Bindings declare names and liveness extents for block-local variables. The best way to see what these are is to play around with them at a REPL. See VM Concepts, for more information.

     Note that bindings information is stored in a program as part of its metadata thunk, so including it in the generated object code does not impose a runtime performance penalty.

 -- Scheme Procedure: program-sources program
 -- Scheme Procedure: source:addr source
 -- Scheme Procedure: source:line source
 -- Scheme Procedure: source:column source
 -- Scheme Procedure: source:file source
     Source location annotations for programs, along with their accessors.

     Source location information propagates through the compiler and ends up being serialized to the program's metadata. This information is keyed by the offset of the instruction pointer within the object code of the program. Specifically, it is keyed on the ip just following an instruction, so that backtraces can find the source location of a call that is in progress.

 -- Scheme Procedure: program-arities program
 -- C Function: scm_program_arities (program)
 -- Scheme Procedure: program-arity program ip
 -- Scheme Procedure: arity:start arity
 -- Scheme Procedure: arity:end arity
 -- Scheme Procedure: arity:nreq arity
 -- Scheme Procedure: arity:nopt arity
 -- Scheme Procedure: arity:rest? arity
 -- Scheme Procedure: arity:kw arity
 -- Scheme Procedure: arity:allow-other-keys? arity
     Accessors for a representation of the ``arity'' of a program.

     The normal case is that a procedure has one arity. For example, (lambda (x) x), takes one required argument, and that's it. One could access that number of required arguments via (arity:nreq (program-arities (lambda (x) x))). Similarly, arity:nopt gets the number of optional arguments, and arity:rest? returns a true value if the procedure has a rest arg.

     arity:kw returns a list of (KW . IDX) pairs, if the procedure has keyword arguments. The IDX refers to the IDXth local variable; see Variables and the VM, for more information. Finally arity:allow-other-keys? returns a true value if other keys are allowed. See Optional Arguments, for more information.

     So what about arity:start and arity:end, then? They return the range of bytes in the program's bytecode for which a given arity is valid. You see, a procedure can actually have more than one arity. The question, ``what is a procedure's arity'' only really makes sense at certain points in the program, delimited by these arity:start and arity:end values.

 -- Scheme Procedure: program-properties program
     Return the properties of a program as an association list, keyed by property name (a symbol).

     Some interesting properties include:

       * name, the name of the procedure

       * documentation, the procedure's docstring

 -- Scheme Procedure: program-property program name
     Access a program's property by name, returning #f if not found.

 -- Scheme Procedure: program-documentation program
 -- Scheme Procedure: program-name program
     Accessors for specific properties.

Optional Arguments
------------------

Scheme procedures, as defined in R5RS, can either handle a fixed number of actual arguments, or a fixed number of actual arguments followed by arbitrarily many additional arguments.  Writing procedures of variable arity can be useful, but unfortunately, the syntactic means for handling argument lists of varying length is a bit inconvenient.  It is possible to give names to the fixed number of arguments, but the remaining (optional) arguments can be only referenced as a list of values (see Lambda).

For this reason, Guile provides an extension to lambda, lambda*, which allows the user to define procedures with optional and keyword arguments. In addition, Guile's virtual machine has low-level support for optional and keyword argument dispatch. Calls to procedures with optional and keyword arguments can be made cheaply, without allocating a rest list.

lambda* and define*.
....................

lambda* is like lambda, except with some extensions to allow optional and keyword arguments.

 -- library syntax: lambda* ([var...]
 [#:optional vardef...]
 [#:key vardef... [#:allow-other-keys]]
 [#:rest var | . var])
 body

     Create a procedure which takes optional and/or keyword arguments specified with #:optional and #:key.  For example,

          (lambda* (a b #:optional c d . e) '())

     is a procedure with fixed arguments A and B, optional arguments C and D, and rest argument E.  If the optional arguments are omitted in a call, the variables for them are bound to #f.

     Likewise, define* is syntactic sugar for defining procedures using lambda*.

     lambda* can also make procedures with keyword arguments. For example, a procedure defined like this:

          (define* (sir-yes-sir #:key action how-high)
            (list action how-high))

     can be called as (sir-yes-sir #:action 'jump), (sir-yes-sir #:how-high 13), (sir-yes-sir #:action 'lay-down #:how-high 0), or just (sir-yes-sir). Whichever arguments are given as keywords are bound to values (and those not given are #f).

     Optional and keyword arguments can also have default values to take when not present in a call, by giving a two-element list of variable name and expression.  For example in

          (define* (frob foo #:optional (bar 42) #:key (baz 73))
            (list foo bar baz))

     FOO is a fixed argument, BAR is an optional argument with default value 42, and baz is a keyword argument with default value 73. Default value expressions are not evaluated unless they are needed, and until the procedure is called.

     Normally it's an error if a call has keywords other than those specified by #:key, but adding #:allow-other-keys to the definition (after the keyword argument declarations) will ignore unknown keywords.

     If a call has a keyword given twice, the last value is used.  For example,

          (define* (flips #:key (heads 0) (tails 0))
            (display (list heads tails)))

          (flips #:heads 37 #:tails 42 #:heads 99)
          -| (99 42)

     #:rest is a synonym for the dotted syntax rest argument.  The argument lists (a . b) and (a #:rest b) are equivalent in all respects.  This is provided for more similarity to DSSSL, MIT-Scheme and Kawa among others, as well as for refugees from other Lisp dialects.

     When #:key is used together with a rest argument, the keyword parameters in a call all remain in the rest list.  This is the same as Common Lisp.  For example,

          ((lambda* (#:key (x 0) #:allow-other-keys #:rest r)
             (display r))
           #:x 123 #:y 456)
          -| (#:x 123 #:y 456)

     #:optional and #:key establish their bindings successively, from left to right. This means default expressions can refer back to prior parameters, for example

          (lambda* (start #:optional (end (+ 10 start)))
            (do ((i start (1+ i)))
                ((> i end))
              (display i)))

     The exception to this left-to-right scoping rule is the rest argument. If there is a rest argument, it is bound after the optional arguments, but before the keyword arguments.

(ice-9 optargs)
...............

Before Guile 2.0, lambda* and define* were implemented using macros that processed rest list arguments. This was not optimal, as calling procedures with optional arguments had to allocate rest lists at every procedure invocation. Guile 2.0 improved this situation by bringing optional and keyword arguments into Guile's core.

However there are occasions in which you have a list and want to parse it for optional or keyword arguments. Guile's (ice-9 optargs) provides some macros to help with that task.

The syntax let-optional and let-optional* are for destructuring rest argument lists and giving names to the various list elements.  let-optional binds all variables simultaneously, while let-optional* binds them sequentially, consistent with let and let* (see Local Bindings).

 -- library syntax: let-optional rest-arg (binding ...) expr ...
 -- library syntax: let-optional* rest-arg (binding ...) expr ...
     These two macros give you an optional argument interface that is very Schemey and introduces no fancy syntax. They are compatible with the scsh macros of the same name, but are slightly extended. Each of BINDING may be of one of the forms VAR or (VAR DEFAULT-VALUE). REST-ARG should be the rest-argument of the procedures these are used from.  The items in REST-ARG are sequentially bound to the variable names are given. When REST-ARG runs out, the remaining vars are bound either to the default values or #f if no default value was specified. REST-ARG remains bound to whatever may have been left of REST-ARG.

     After binding the variables, the expressions EXPR ... are evaluated in order.

Similarly, let-keywords and let-keywords* extract values from keyword style argument lists, binding local variables to those values or to defaults.

 -- library syntax: let-keywords args allow-other-keys? (binding ...) body ...
 -- library syntax: let-keywords* args allow-other-keys? (binding ...) body ...
     ARGS is evaluated and should give a list of the form (#:keyword1 value1 #:keyword2 value2 ...).  The BINDINGs are variables and default expressions, with the variables to be set (by name) from the keyword values.  The BODY forms are then evaluated and the last is the result.  An example will make the syntax clearest,

          (define args '(#:xyzzy "hello" #:foo "world"))

          (let-keywords args #t
                ((foo  "default for foo")
                 (bar  (string-append "default" "for" "bar")))
            (display foo)
            (display ", ")
            (display bar))
          -| world, defaultforbar

     The binding for foo comes from the #:foo keyword in args.  But the binding for bar is the default in the let-keywords, since there's no #:bar in the args.

     ALLOW-OTHER-KEYS? is evaluated and controls whether unknown keywords are allowed in the ARGS list.  When true other keys are ignored (such as #:xyzzy in the example), when #f an error is thrown for anything unknown.

(ice-9 optargs) also provides some more define* sugar, which is not so useful with modern Guile coding, but still supported: define*-public is the lambda* version of define-public; defmacro* and defmacro*-public exist for defining macros with the improved argument list handling possibilities. The -public versions not only define the procedures/macros, but also export them from the current module.

 -- library syntax: define*-public formals body
     Like a mix of define* and define-public.

 -- library syntax: defmacro* name formals body
 -- library syntax: defmacro*-public name formals body
     These are just like defmacro and defmacro-public except that they take lambda*-style extended parameter lists, where #:optional, #:key, #:allow-other-keys and #:rest are allowed with the usual semantics. Here is an example of a macro with an optional argument:

          (defmacro* transmorgify (a #:optional b)
            (a 1))

Case-lambda
-----------

R5RS's rest arguments are indeed useful and very general, but they often aren't the most appropriate or efficient means to get the job done. For example, lambda* is a much better solution to the optional argument problem than lambda with rest arguments.

Likewise, case-lambda works well for when you want one procedure to do double duty (or triple, or ...), without the penalty of consing a rest list.

For example:

     (define (make-accum n)
       (case-lambda
         (() n)
         ((m) (set! n (+ n m)) n)))

     (define a (make-accum 20))
     (a) => 20
     (a 10) => 30
     (a) => 30

The value returned by a case-lambda form is a procedure which matches the number of actual arguments against the formals in the various clauses, in order. The first matching clause is selected, the corresponding values from the actual parameter list are bound to the variable names in the clauses and the body of the clause is evaluated. If no clause matches, an error is signalled.

The syntax of the case-lambda form is defined in the following EBNF grammar. Formals means a formal argument list just like with lambda (see Lambda).

     <case-lambda>
        --> (case-lambda <case-lambda-clause>)
     <case-lambda-clause>
        --> (<formals> <definition-or-command>*)
     <formals>
        --> (<identifier>*)
          | (<identifier>* . <identifier>)
          | <identifier>

Rest lists can be useful with case-lambda:

     (define plus
       (case-lambda
         (() 0)
         ((a) a)
         ((a b) (+ a b))
         ((a b . rest) (apply plus (+ a b) rest))))
     (plus 1 2 3) => 6

Also, for completeness. Guile defines case-lambda* as well, which is like case-lambda, except with lambda* clauses. A case-lambda* clause matches if the arguments fill the required arguments, but are not too many for the optional and/or rest arguments.

Keyword arguments are possible with case-lambda*, but they do not contribute to the ``matching'' behavior. That is to say, case-lambda* matches only on required, optional, and rest arguments, and on the predicate; keyword arguments may be present but do not contribute to the ``success'' of a match. In fact a bad keyword argument list may cause an error to be raised.

Procedure Properties and Meta-information
-----------------------------------------

In addition to the information that is strictly necessary to run, procedures may have other associated information. For example, the name of a procedure is information not for the procedure, but about the procedure. This meta-information can be accessed via the procedure properties interface.

The first group of procedures in this meta-interface are predicates to test whether a Scheme object is a procedure, or a special procedure, respectively. procedure? is the most general predicates, it returns #t for any kind of procedure. closure? does not return #t for primitive procedures, and thunk? only returns #t for procedures which do not accept any arguments.

 -- Scheme Procedure: procedure? obj
 -- C Function: scm_procedure_p (obj)
     Return #t if OBJ is a procedure.

 -- Scheme Procedure: closure? obj
 -- C Function: scm_closure_p (obj)
     Return #t if OBJ is a closure. This category somewhat misnamed, actually, as it applies only to interpreted procedures, not compiled procedures. But since it has historically been used more to select on implementation details than on essence (closure or not), we keep it here for compatibility. Don't use it in new code, though.

 -- Scheme Procedure: thunk? obj
 -- C Function: scm_thunk_p (obj)
     Return #t if OBJ is a thunk.

Procedure properties are general properties associated with procedures. These can be the name of a procedure or other relevant information, such as debug hints.

 -- Scheme Procedure: procedure-name proc
 -- C Function: scm_procedure_name (proc)
     Return the name of the procedure PROC

 -- Scheme Procedure: procedure-source proc
 -- C Function: scm_procedure_source (proc)
     Return the source of the procedure PROC. Returns #f if the source code is not available.

 -- Scheme Procedure: procedure-environment proc
 -- C Function: scm_procedure_environment (proc)
     Return the environment of the procedure PROC. Very deprecated.

 -- Scheme Procedure: procedure-properties proc
 -- C Function: scm_procedure_properties (proc)
     Return the properties associated with PROC, as an association list.

 -- Scheme Procedure: procedure-property proc key
 -- C Function: scm_procedure_property (proc, key)
     Return the property of PROC with name KEY.

 -- Scheme Procedure: set-procedure-properties! proc alist
 -- C Function: scm_set_procedure_properties_x (proc, alist)
     Set PROC's property list to ALIST.

 -- Scheme Procedure: set-procedure-property! proc key value
 -- C Function: scm_set_procedure_property_x (proc, key, value)
     In PROC's property list, set the property named KEY to VALUE.

Documentation for a procedure can be accessed with the procedure procedure-documentation.

 -- Scheme Procedure: procedure-documentation proc
 -- C Function: scm_procedure_documentation (proc)
     Return the documentation string associated with proc.  By convention, if a procedure contains more than one expression and the first expression is a string constant, that string is assumed to contain documentation for that procedure.

Procedures with Setters
-----------------------

A procedure with setter is a special kind of procedure which normally behaves like any accessor procedure, that is a procedure which accesses a data structure.  The difference is that this kind of procedure has a so-called setter attached, which is a procedure for storing something into a data structure.

Procedures with setters are treated specially when the procedure appears in the special form set! (REFFIXME).  How it works is best shown by example.

Suppose we have a procedure called foo-ref, which accepts two arguments, a value of type foo and an integer.  The procedure returns the value stored at the given index in the foo object. Let f be a variable containing such a foo data
structure. (Working definitions would be:)

     (define foo-ref vector-ref)
     (define foo-set! vector-set!)
     (define f (make-vector 2 #f))

     (foo-ref f 0)       => bar
     (foo-ref f 1)       => braz

Also suppose that a corresponding setter procedure called foo-set! does exist.

     (foo-set! f 0 'bla)
     (foo-ref f 0)       => bla

Now we could create a new procedure called foo, which is a procedure with setter, by calling make-procedure-with-setter with the accessor and setter procedures foo-ref and foo-set!. Let us call this new procedure foo.

     (define foo (make-procedure-with-setter foo-ref foo-set!))

foo can from now an be used to either read from the data structure stored in f, or to write into the structure.

     (set! (foo f 0) 'dum)
     (foo f 0)          => dum

 -- Scheme Procedure: make-procedure-with-setter procedure setter
 -- C Function: scm_make_procedure_with_setter (procedure, setter)
     Create a new procedure which behaves like PROCEDURE, but with the associated setter SETTER.

 -- Scheme Procedure: procedure-with-setter? obj
 -- C Function: scm_procedure_with_setter_p (obj)
     Return #t if OBJ is a procedure with an associated setter procedure.

 -- Scheme Procedure: procedure proc
 -- C Function: scm_procedure (proc)
     Return the procedure of PROC, which must be an applicable struct.

 -- Scheme Procedure: setter proc
     Return the setter of PROC, which must be either a procedure with setter or an operator struct.