For Gauche 0.9.9

Next: , Previous: , Up: Library modules - Gauche extensions   [Contents][Index]

9.22 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>

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

;; p is a parameter with initial value 2
(define p (make-parameter 2))

;; calling p with no arguments returns the current value
(p) ⇒ 2

;; modify p's value to 3
(p 3)

(p) ⇒ 3

;; you can also use generalized set (srfi-17)
(set! (p) 5)

(p) ⇒ 5

;; using parameterize dynamically changes p's value.

(define (get-p) (p))

(parameterize ([p 7])
  (get-p)) ⇒ 7

(get-p)    ⇒ 5
Function: make-parameter value :optional filter

[SRFI-39] {gauche.parameter} 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] {gauche.parameter} Evaluates 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.

Some examples:

(define a (make-parameter 1))
(a) ⇒ 1
(a 2) ⇒ 1
(a) ⇒ 2
(parameterize ((a 3))
  (a)) ⇒ 3
(a) ⇒ 2
Method: parameter-observer-add! (p <parameter>) proc :optional when where

{gauche.parameter} 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

{gauche.parameter} 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.

Method: parameter-pre-observers (p <parameter>)
Method: parameter-post-observers (p <parameter>)

{gauche.parameter} Returns a hook object (see Hooks) that keeps "before" or "after" observers, respectively.

Note: Although the parameter value itself is thread-local, these hook objects are shared by all threads.

Next: , Previous: , Up: Library modules - Gauche extensions   [Contents][Index]