28 Preferences, Textual

preferences:set immediately writes the preference value to disk. It raises an exception matching exn:unknown-preference? if the preference’s default has not been set

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.

The result thunk removes the callback from the same preferences layer that p was in when preferences:add-callback was originally called.

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, (reflected via a call to preferences:set, possibly in a different run of your program), 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.

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.

A preferences layer gives a form of scoping to preferences. When a new preference is first registered with this library (via a call to preferences:set-default or preferences:add-callback) it is put into the layer in preferences:current-layer (and not into any of that layer’s previous layers). When preferences:get, preferences:set, preferences:set-un/marshall are called, they consult and manipulate only the layer where the preference was first installed. Accordingly, preference layers give a way to discard some set of calls to preference:set-default and other preference configuration and to start over with a new set. Note that this affects only the configuration of the preferences for the library; the values are all stored centrally (see preferences:low-level-put-preferences) and are unaffected by the layers.