settings

The settings API allows to store values and save them to a file for persistent configurations for CraftOS and your programs.

By default, the settings API will load its configuration from the /.settings file. One can then use settings.save to update the file.

define(name[, options])Define a new setting, optional specifying various properties about it.
undefine(name)Remove a definition of a setting.
set(name, value)Set the value of a setting.
get(name[, default])Get the value of a setting.
getDetails(name)Get details about a specific setting.
unset(name)Remove the value of a setting, setting it to the default.
clear()Resets the value of all settings.
getNames()Get the names of all currently defined settings.
load([sPath])Load settings from the given file.
save([sPath])Save settings to the given file.
define(name[, options])Source

Define a new setting, optional specifying various properties about it.

While settings do not have to be added before being used, doing so allows you to provide defaults and additional metadata.

Parameters

  1. name string The name of this option
  2. options? { description? = string, default? = any, type? = string }

    Options for this setting. This table accepts the following fields:

    • description: A description which may be printed when running the set program.
    • default: A default value, which is returned by settings.get if the setting has not been changed.
    • type: Require values to be of this type. Setting the value to another type will error.
undefine(name)Source

Remove a definition of a setting.

If a setting has been changed, this does not remove its value. Use settings.unset for that.

Parameters

  1. name string The name of this option
set(name, value)Source

Set the value of a setting.

Parameters

  1. name string The name of the setting to set
  2. value The setting's value. This cannot be nil, and must be serialisable by textutils.serialize.

Throws

  • If this value cannot be serialised

See also

get(name[, default])Source

Get the value of a setting.

Parameters

  1. name string The name of the setting to get.
  2. default? The value to use should there be pre-existing value for this setting. If not given, it will use the setting's default value if given, or nil otherwise.

Returns

  1. The setting's, or the default if the setting has not been changed.
getDetails(name)Source

Get details about a specific setting.

Parameters

  1. name string The name of the setting to get.

Returns

  1. { description? = string, default? = any, type? = string, value? = any } Information about this setting. This includes all information from settings.define, as well as this setting's value.
unset(name)Source

Remove the value of a setting, setting it to the default.

settings.get will return the default value until the setting's value is set, or the computer is rebooted.

Parameters

  1. name string The name of the setting to unset.

See also

clear()Source

Resets the value of all settings. Equivalent to calling settings.unset

  • on every setting.

@see settings.unset

getNames()Source

Get the names of all currently defined settings.

Returns

  1. { string } An alphabetically sorted list of all currently-defined settings.
load([sPath])Source

Load settings from the given file.

Existing settings will be merged with any pre-existing ones. Conflicting entries will be overwritten, but any others will be preserved.

Parameters

  1. sPath? string The file to load from, defaulting to .settings.

Returns

  1. boolean Whether settings were successfully read from this file. Reasons for failure may include the file not existing or being corrupted.

See also

save([sPath])Source

Save settings to the given file.

This will entirely overwrite the pre-existing file. Settings defined in the file, but not currently loaded will be removed.

Parameters

  1. sPath? string The path to save settings to, defaulting to .settings.

Returns

  1. boolean If the settings were successfully saved.

See also