Difference between revisions of "Settings (API)"

Latest revision as of 03:40, 11 June 2016

The settings API allows to store values and save them to a file for persistent configurations for your and CraftOS programs. The default file for saving settings is .settings sitting in the root of the computer. Settings can also be changed and added to all computers through ComputerCraft.cfg's S:default_computer_settings value. It became available as of ComputerCraft 1.77, the first build for Minecraft 1.8.9.

See also: the set script.

settings (API)
Function	Return values	Description
settings.set(string name, any value)	nil	Sets the setting name to value.
settings.get(string name [, any default])	any value	Returns the setting's name value, or default if the setting does not exist.
settings.unset(string name)	nil	Removes the setting name.
settings.clear()	nil	Removes all settings.
settings.getNames()	table settingNames	Returns a numerically-indexed table of all the setting's names.
settings.load(string path)	boolean loaded	Loads settings from a file.
settings.save(string path)	boolean saved	Saves current settings to a file.

Notes

• Settings changed via this API are not automatically saved to a file, you have to do this manually.
• Setting's names can only be of type string.
• Setting's values can only be serializable types: string, number, boolean or table.

Default Settings

These are the default settings of a computer (as seen in CC 1.77 and later):

{
  [ "bios.use_multishell" ] = true,
  [ "shell.autocomplete" ] = true,
  [ "shell.allow_disk_startup" ] = true  --# (for all Computer types except Command Computers),
  [ "shell.allow_startup" ] = true,
  [ "lua.autocomplete" ] = true,
  [ "list.show_hidden" ] = false,
  [ "edit.autocomplete" ] = true,
}

• shell.autocomplete - enables auto-completion in the Shell.
• lua.autocomplete - enables auto-completion in the Lua program.
• edit.autocomplete - enables auto-completion in the Edit program.
• bios.use_multishell - enables Multishell on Advanced Computers, Turtles, Pocket Computers and Command Computers.
• shell.allow_disk_startup - if a Disk Drive with a Disk inside that has a 'startup' script is attached to a computer, this setting allows to automatically run that script when the computer starts.
• shell.allow_startup - if there is a 'startup' script in a computer's root, this setting allow to automatically run that script when the computer runs.
• list.show_hidden - determines, whether the List program will list hidden files or not.

.settings

If a file titled ".settings" is saved to the root of a given computer's drive, it will be automatically loaded after the default settings on boot (note "after", as opposed to "instead of").

For example, if the file simply contains:

{
  [ "bios.use_multishell" ] = false
}

... then all regular defaults will apply except for the use of multishell, which will be disabled.

ComputerCraft.cfg

You can change or add default settings for all computers through ComputerCraft.cfg. The format is as follows:

• each setting is separated by a comma (,)
• setting's name and value is separated by an equals sign (=)

This example will disable auto-completion features in the default programs.

S:default_computer_settings=shell.autocomplete=false,lua.autocomplete=false,edit.autocomplete=false