27 Preferences, Textual
preferences:get returns the value for the preference
symbol. It raises
exn:unknown-preference
if the preference’s default has not been set.
preferences:set-preference sets the preference
symbol to value. This should be called when the
users requests a change to a preference.
This function immediately writes the preference value to disk.
It raises
exn:unknown-preference
if the preference’s default has not been set.
This function adds a callback which is called with a symbol naming a
preference and its value, when the preference changes.
preferences:add-callback returns a thunk, which when
invoked, removes the callback from this preference.
If weak? is true, the preferences system will only hold on to
the callback weakly.
The callbacks will be called in the order in which they were added.
If you are adding a callback for a preference that requires
marshalling and unmarshalling, you must set the marshalling and
unmarshalling functions by calling
preferences:set-un/marshall before adding a callback.
This function raises
exn:unknown-preference
exn:unknown-preference
if the preference has not been set.
If you use preferences:set-un/marshall,
you must call this function before calling it.
This sets the default value of the preference symbol to
value. If the user has chosen a different setting,
the user’s setting will take precedence over the default value.
The test argument is used as a safeguard. That function is
called to determine if a preference read in from a file is a valid
preference. If test returns #t, then the preference is
treated as valid. If test returns #f then the default is
used.
The aliases and rewrite-aliases arguments aids
in renaming preferences. If aliases is present, it is
expected to be a list of symbols that correspond to old versions
of the preferences. It defaults to '(). If rewrite-aliases
is present, it is used to adjust the old values of the preferences
when they are present in the saved file.
preferences:set-un/marshall is used to specify marshalling and
unmarshalling functions for the preference
symbol.
marshall will be called when the users saves their
preferences to turn the preference value for
symbol into a
printable value.
unmarshall will be called when the user’s
preferences are read from the file to transform the printable value
into its internal representation. If
preferences:set-un/marshall
is never called for a particular preference, the values of that
preference are assumed to be printable.
If the unmarshalling function returns a value that does not meet the
guard passed to preferences:set-default
for this preference, the default value is used.
The marshall function might be called with any value returned
from read and it must not raise an error
(although it can return arbitrary results if it gets bad input). This might
happen when the preferences file becomes corrupted, or is edited
by hand.
preferences:set-un/marshall must be called before calling
preferences:get,preferences:set.
The callback occurs on whichever thread happened to call preferences:set.
Pre- and post-write notifications are not necessarily paired; unregistration
may cancel the post-write notification before it occurs.
Unregisters the save callback associated with key.
Creates an unknown preference exception.
Determines if a value is an unknown preference exn.
The struct type for the unknown preference exn.
This parameter’s value is called to save preference the preferences file.
Its interface should be just like mzlib’s put-preferences.
The default value calls put-preferences and, if there is an error,
then starts using a hash-table to save the preferences instead.
See also
This parameter’s value is called to get a preference from the preferences
file. Its interface should be just like get-preference.
The default value calls get-preferences and, if there is an error,
then starts using a hash-table to save the preferences instead.
Determines if its argument is a preferences snapshot.
Restores the preferences saved in snapshot.
Caches all of the current values of the preferences and returns them.
For any preference that has marshalling and unmarshalling set
(see
preferences:set-un/marshall), the preference value is
copied by passing it through the marshalling and unmarshalling process.
Other values are not copied, but references to them are instead saved.
See also preferences:restore-prefs-snapshot.