Documentation
¶
Overview ¶
Package prefs facilitates the storage of preferential values in the Gopher2600 system. It is a key/value system and is quite flexible. The most significant feature is the ability to only specify the preferences you are interested in for a given task. Loading and saving a preference will ignore and preserve values that haven't been added to the "Disk" type.
The Disk type is the key resource in the package. First, create new Disk instance with NewDisk(), specifying the location of the preferences file (using paths.ResourcePath() as necessary).
fn, _ := paths.ResourcePath(prefs.DefaultPrefsFile) prf := prefs.NewDisk(fn)
Preference value can then be added with the Add() function, specifying the "key" value. For clarity, the key value should be similar to the name of the variable as used in the calling code, although this isn't required (note the restrictions on the key value in the documtation for the Add() function).
prf.Add("auto", &auto)
Values that are added to the Disk type must use one of the preference types defined in this package. Currently, there are Bool, String and Int types. There is also a Generic type, that allows the Set() and Get() functions to be defined as appropriate
Once added to the disk object, preference values can be changed in the program in the normal way. Changes can be committed to disk wit the Disk.Save() function and restoried with Disk.Load().
Note ¶
While saved preference files are stored in UTF-8 it is not a good idea for the files to be edited by hand. As such, manual editing is discorouaged with the warning at the top of the file:
*** do not edit this file by hand ***
This also serves as the means of identification for the Load() function. ie. if this warning is not present then the Load() operation will fail.
Index ¶
Constants ¶
const DefaultPrefsFile = "preferences"
DefaultPrefsFile is the default filename of the global preferences file.
const WarningBoilerPlate = "*** do not edit this file by hand ***"
WarningBoilerPlate is inserted at the beginning of a preferences file.
Variables ¶
var DisableSaving = false
DisableSaving is useful for testing when a blanket prohibition on saving to disk is required.
Functions ¶
This section is empty.
Types ¶
type Bool ¶
type Bool struct {
// contains filtered or unexported fields
}
Bool implements a boolean type in the prefs system.
func (*Bool) RegisterCallback ¶ added in v0.3.1
RegisterCallback sets the callback function to be called when the value is updated. Note that even if the value hasn't changed, the callback will be executed.
Not required but is useful in some contexts.
type Disk ¶
type Disk struct {
// contains filtered or unexported fields
}
Disk represents preference values as stored on disk.
func (*Disk) Add ¶
Add preference value to list of values to store/load from Disk. The id is used to identify the preference value on disk and should only consist of alphabetic characters or the period character. The program will panic if these constraints are not met.
func (*Disk) HasEntry ¶ added in v0.7.1
HasEntry returns false if there is no matching entry on disk and true if there is.
func (*Disk) Load ¶
Load preference values from disk. The saveonFirstUse argument is useful when loading preferences on initialisation. It makes sure default preferences are saved to disk if they are not present in the preferences file.
type Float ¶ added in v0.7.1
type Float struct {
// contains filtered or unexported fields
}
Int implements a string type in the prefs system.
func (*Float) RegisterCallback ¶ added in v0.7.1
RegisterCallback sets the callback function to be called when the value is updated. Note that even if the value hasn't changed, the callback will be executed.
Not required but is useful in some contexts.
type Generic ¶
type Generic struct {
// contains filtered or unexported fields
}
Generic is a general purpose prefererences type, useful for values that cannot be represented by a single live value. You must use the NewGeneric() function to initialise a new instance of Generic.
The Generic prefs type does not have a way of registering a callback function. It is also slower than other prefs types because it must protect potential critical sections with a mutex (other types can use an atomic value).
func NewGeneric ¶
NewGeneric is the preferred method of initialisation for the Generic type.
type Int ¶
type Int struct {
// contains filtered or unexported fields
}
Int implements a string type in the prefs system.
func (*Int) RegisterCallback ¶ added in v0.3.1
RegisterCallback sets the callback function to be called when the value is updated. Note that even if the value hasn't changed, the callback will be executed.
Not required but is useful in some contexts.
type String ¶
type String struct {
// contains filtered or unexported fields
}
String implements a string type in the prefs system.
func (*String) RegisterCallback ¶ added in v0.3.1
RegisterCallback sets the callback function to be called when the value is updated. Note that even if the value hasn't changed, the callback will be executed.
Not required but is useful in some contexts.
Source Files