Parameters are Guile’s facility for dynamically bound variables.
On the most basic level, 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 extent
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. Introducing a new setting to existing code is often easier with a parameter object than adding arguments.
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
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 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:
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 SRFI-39 - Parameters).