9.21 gauche.parameter - Parameters

Module: gauche.parameter

A parameter is something like a stateful procedure that takes zero or
one argument.
If no argument is given, the parameter returns the current value it is keeping.
If single argument is given, it will be the current value of the parameter.
A parameter has several advantages over global variables to store
states.

Value of parameters are kept for each thread, so you can use
a parameter as a thread-local storage. When a new thread is
created, it inherits a copy of parameters from its creator thread.

You can give a "filter procedure" that checks the new
value before setting it as the parameter value,
so that you can guarantee the value of the parameter is always sane.

With the macro parameterize, you can change the parameter’s
value within certain dynamic scope. It can effectively
replace dynamically scoped variables.

You can also register callback procedures to be called whenever
the value of the parameter is changed. It can effectively
replace so-called "traced variables"

The basic parameter object feature is defined in SRFI-39.
It also can be found in other Scheme implementations,
including ChezScheme, Chicken and MzScheme.
Gauche’s one is upper compatible to SRFI-39.

Class: <parameter>

A parameter class. A object-apply method is defined
so that a parameter can be used as if it were a procedure.

[SRFI-39]
Creates a parameter whose initial value is value.
If an optional argument filter is given, it must be
a procedure that takes one argument and returns one value;
whenever the parameter’s value is about to change, the procedure
is called with the given value, and the value the procedure
returns will be the parameter’s value. The filter procedure
can raise an error or reject to change the parameter’s value.

Macro: parameterize((param value) …) body …

[SRFI-39]
Evaluages body …, with
change parameter param’s value to the given value within
the dynamic scope of body ….
Returns the value(s) of the result of the last body.

Adds proc to "observer" procedures of a parameter p.
Observer procedures are called either (1) just before
a new value is set to the parameter, or (2) just after the new value
is set to the parameter. In case of (1), a filter procedure is
already applied before a callback is called.
In either case, observer procedures are called with two arguments,
the old value and the new value. The return value(s) of observer
procedures are discarded.

The optional when argument must be either a symbol before
or after, to specify whether proc should be called
before or after the value is changed. If omitted, after is
assumed.

The optional where argument must be either a symbol
append or prepend, to specify whether proc should
be prepended or appended to the existing observer procedure list.
If omitted, append is assumed.

Note: Although the parameter value itself is thread-local,
the observer list is shared by all threads.

Method: parameter-observer-delete!(p <parameter>) proc :optional when

Deletes proc from observer procedure list of a parameter p.
If proc is not in the list, nothing happens.
You can give either a symbol before or after to
when argument to specify from which list proc should be
deleted. If when argument is omitted, proc is deleted
from both lists.