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 a Disk instance with NewDisk(), specifying the location of the preferences file (using resources.ResourcePath() as necessary).
fn, _ := resources.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 and also a Generic type (unreleated to Go "generics").
Once added to the disk object, preference values can be changed in the program in the normal way. Changes can be committed to disk with the Disk.Save() function and restored with Disk.Load().
Prefs valus and Multiple Disk Instances ¶
A prefs values can be added to more than one disk intance at once. Moreover, more than disk instance can point to the same file on disk.
This is useful when only wanting to save a subset of prefs values. The values that are to be saved can be allocated to a limited disk object and be saved. Values that exist on the physical disk but which are missing from the limited disk object will be preserved.
Concurrency ¶
Generally, it is safe to access a prefs value from any goroutine. However, Set() should be used with care *if* SetHookPost() or SetHookPre() has been set for that value.
Command Line Support ¶
The *CommandLine*() functions are designed to help with the overriding of disk values with a value given on the command line. These values are added as a group with AddCommandLineGroup(). For example
AddCommandLineGroup("foo::bar; baz::qux")
(see below for more detail about the format of the prefs string)
These values are then looked up when preferences are first loaded by an instance of the Disk type. The command line value will be used instead of the saved value for the first load only. If Load() is never called then the command line value will not be used -- this shouldn't be an issue because it is good practice for Load() to always be called after the a set of prefs values have been added with the Add() function
Commandline groups can be nested. Subsequent calls to AddCommandLineGroup() will hide the previous group until EndCommandLineGroup() is called.
The prefs string used with AddCommandLineGroup() mirror the format of the preferences file except that entries are separated by semi-colons instead of newlines.
For example, if the preferences file has the following entries:
a.b.c :: 100 d.e.f.g :: false h.i :: wibble
A valid string to use with AddCommandLineGroup() might be:
a.b.c::100; h.i::wibble
Leading and trailing spaces around the key and value are stripped.
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 GenericGetValueUndefined = "GenericGetValueUndefined"
GenericGetValueUndefined is a special return value for the get() function (see NewGeneric()). It indicates that the value is currently unavailable and the most recent previous value should be used.
const KeySep = " :: "
the string the separators the pref key from the value.
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 ¶
func PopCommandLineStack ¶ added in v0.16.0
func PopCommandLineStack() string
PopCommandLineStack forgets the most recent group added by AddCommandLineGroup().
Returns the "unused" preferences of the stack entry.
func PushCommandLineStack ¶ added in v0.16.0
func PushCommandLineStack(prefs string)
PushCommandLineStack parses a command line and adds it as a new group.
func SizeCommandLineStack ¶ added in v0.16.0
func SizeCommandLineStack() int
SizeCommandLineStack returns the number of groups that have been added with AddCommanLineGroup().
Types ¶
type Bool ¶
type Bool struct {
// contains filtered or unexported fields
}
Bool implements a boolean type in the prefs system.
func (*Bool) Set ¶
Set new value to Bool type. New value must be of type bool or string. A string value of anything other than "true" (case insensitive) will set the value to false.
func (*Bool) SetHookPost ¶ added in v0.15.0
SetHookPost sets the callback function to be called just after the prefs 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.
func (*Bool) SetHookPre ¶ added in v0.15.0
SetHookPre sets the callback function to be called just before the prefs 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 key value 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) DoesNotHaveEntry ¶ added in v0.17.0
DoesNotHaveEntry returns true if entry is missing from the written disk.
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) SetHookPost ¶ added in v0.15.0
SetHookPost sets the callback function to be called just after the prefs 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.
func (*Float) SetHookPre ¶ added in v0.15.0
SetHookPre sets the callback function to be called just before the prefs 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) SetHookPost ¶ added in v0.15.0
SetHookPost sets the callback function to be called just after the prefs 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.
func (*Int) SetHookPre ¶ added in v0.15.0
SetHookPre sets the callback function to be called just before the prefs 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) SetHookPost ¶ added in v0.15.0
SetHookPost sets the callback function to be called just after the prefs 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.
func (*String) SetHookPre ¶ added in v0.15.0
SetHookPre sets the callback function to be called just before the prefs 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