View Source

The settings module is used to read and write system settings.

Settings are stored on the Filesystem as string based key/value pairs. Parameters of a settings are:

Parameter	Description
ID	"dot-separated" name (e.g. "network.ip.netmask")
Label	Displayed name of the settings (e.g. "Subnetmask")
Type	Arbitrary string defining the type (e.g. "ip_address" )
Value	String with the value of the setting (e.g. "255.255.255.0" )
Editable	Boolean value indicating if the settings can be changed or not

Settings are organized in a tree structure. Each node has a name of at most 8 characters (case insensitive, numbers and letters only, no spaces or special characters allowed). The ID of a settings is a concatenation of the IDs of the nodes in its "path" down the tree.

E.g.

network
network.ip
network.ip.netmask
network.ip.gateway

Learn more, go to page The Settings Framework

Functions

Function	Description
.create( id, label, type, value, editable)	Creates a setting.
.read( id )	Reads the value of a setting.
.write( id, value )	Writes the value of a setting.
.delete( id )	Deletes a setting.

.create( id, label, type, value, editable)

Creates a setting. If the setting already exists the string "Exists" is returned and the setting is not updated with the provided value.

Parameter	Type	Description
id	String	The ID of the settings. Must be a valid "dot-separated" ID.
label	String	The label of the settings used for displaying.
type	String	The type of settings. This is an arbitrary string.
value	String	The content of the setting. This is always a string.
editable	Boolean	Make the setting editable or not.

Return Value	Type	Description
error	String	Error string describing the issue (e.g. "Exists" or nil when the operation was successful.

-- Create a clean looking title "Network Settings".
err = settings.create("network", "Network Settings", nil, "", true)


-- Create a Subnetmask under the "network" title. 
err = settings.create( 
		"network.ip.netmask",
		"Subnetmask",
		"ip_address",
		"255.255.255.0",
		true
		)

On the Lua Development Environment webpage you can view and edit these settings by clicking on the "settings"-icon.

A hidden setting can be created by starting the id with an underscore.

.read( id )

Reads the value of a setting. Returns the string value of a setting. In case an error occures during reading (e.g. setting does not exist) nil is returned together with a second string with error information.

Parameter	Type	Description
id	String	The ID of the settings. Must be a valid "dot-separated" ID.

Return Value	Type	Description
value	String	Value of the setting or nil if the settings could not be read.
error	String	Error string describing the issue or nil when the operation was successful.

value, err = settings.read( "network.ip.netmask" )

.write( id, value )

Writes the value of a setting. Updates the setting to the value that is provided. In case an error occurs during writing (e.g. setting does not exist) an error string is returned.

Parameter	Type	Description
id	String	The ID of the settings. Must be a valid "dot-separated" ID.
value	String	The new content of the setting. This is always a string.

Return Value	Type	Description
error	String	Error string describing the issue or nil when the operation was successful.

err = settings.write( "network.ip.netmask", "255.255.0.0" )

.delete( id )

Deletes a setting. If the setting has children these are also deleted. In case an error occurs during writing (e.g. setting does not exist) an error string is returned.

Parameter	Type	Description
id	String	The ID of the settings. Must be a valid "dot-separated" ID.

Return Value	Type	Description
error	String	Error string describing the issue or nil when the operation was successful.

-- Given the settings from the example above, below command will delete the following settings:
--   network
--   network.ip
--   network.ip.netmask
--   network.ip.gateway

err = settings.delete( "network" )