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.

Function: 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

Scheme Syntax: parameterize ((param value) …) body …

Establish a new dynamic scope with the given params bound to new locations and set to the given values. body is evaluated in that environment, the result is the return from the last form in body.

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.

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 February 3, 2012 using texi2html 5.0.