6.21.8 Parameters

A parameter object is a procedure. Calling it with no arguments returns its value. Calling it with one argument sets the value.

(define my-param (make-parameter 123))
(my-param) ⇒ 123
(my-param 456)
(my-param) ⇒ 456

The parameterize special form establishes new locations for parameters, those new locations having effect within the dynamic scope of the parameterize body. Leaving restores the previous locations. Re-entering (through a saved continuation) will again use the new locations.

(parameterize ((my-param 789))
  (my-param)) ⇒ 789
(my-param) ⇒ 456

Parameters are like dynamically bound variables in other Lisp dialects. They allow an application to establish parameter settings (as the name suggests) just for the execution of a particular bit of code, restoring when done. Examples of such parameters might be case-sensitivity for a search, or a prompt for user input.

Global variables are not as good as parameter objects for this sort of thing. Changes to them are visible to all threads, but in Guile parameter object locations are per-thread, thereby truly limiting the effect of parameterize to just its dynamic execution.

Passing arguments to functions is thread-safe, but that soon becomes tedious when there’s more than a few or when they need to pass down through several layers of calls before reaching the point they should affect. And introducing a new setting to existing code is often easier with a parameter object than adding arguments.

Scheme Procedure: make-parameter init [converter]

Return a new parameter object, with initial value init.

If a converter is given, then a call (converter val) is made for each value set, its return is the value stored. Such a call is made for the init initial value too.

A converter allows values to be validated, or put into a canonical form. For example,

(define my-param (make-parameter 123
                   (lambda (val)
                     (if (not (number? val))
                         (error "must be a number"))
                     (inexact->exact val))))
(my-param 0.75)
(my-param) ⇒ 3/4

library syntax: parameterize ((param value) …) body1 body2 …

Establish a new dynamic scope with the given params bound to new locations and set to the given values. body1 body2 … is evaluated in that environment. The value returned is that of last body form.

Each param is an expression which is evaluated to get the parameter object. Often this will just be the name of a variable holding the object, but it can be anything that evaluates to a parameter.

The param expressions and value expressions are all evaluated before establishing the new dynamic bindings, and they’re evaluated in an unspecified order.

For example,

(define prompt (make-parameter "Type something: "))
(define (get-input)
  (display (prompt))
  ...)

(parameterize ((prompt "Type a number: "))
  (get-input)
  ...)

Parameter objects are implemented using fluids (see section Fluids and Dynamic States), so each dynamic state has its own parameter locations. That includes the separate locations when outside any parameterize form. When a parameter is created it gets a separate initial location in each dynamic state, all initialized to the given init value.

New code should probably just use parameters instead of fluids, because the interface is better. But for migrating old code or otherwise providing interoperability, Guile provides the fluid->parameter procedure:

Scheme Procedure: fluid->parameter fluid [conv]

Make a parameter that wraps a fluid.

The value of the parameter will be the same as the value of the fluid. If the parameter is rebound in some dynamic extent, perhaps via parameterize, the new value will be run through the optional conv procedure, as with any parameter. Note that unlike make-parameter, conv is not applied to the initial value.

As alluded to above, because each thread usually has a separate dynamic state, each thread has its own locations behind parameter objects, and changes in one thread are not visible to any other. When a new dynamic state or thread is created, the values of parameters in the originating context are copied, into new locations.

Guile’s parameters conform to SRFI-39 (see section SRFI-39 - Parameters).

This document was generated on April 20, 2013 using texi2html 5.0.