# hs.settings

Serialize simple Lua variables across Hammerspoon launches Settings must have a string key and must be made up of serializable Lua objects (string, number, boolean, nil, tables of such, etc.)

This module is based partially on code from the previous incarnation of Mjolnir by Steven Degutis.

# API Overview

Constants - Useful values which cannot be changed

bundleID
dateFormat

Functions - API calls offered directly by the extension

clear
get
getKeys
set
setData
setDate
watchKey

# API Documentation

# Constants

# bundleID


Signature	`hs.settings.bundleID`
Type	Constant
Description	A string representing the ID of the bundle Hammerspoon's settings are stored in . You can use this with the command line tool `defaults` or other tools which allow access to the `User Defaults` of applications, to access these outside of Hammerspoon
Notes	None
Source	extensions/settings/libsettings.m line 326

# dateFormat


Signature	`hs.settings.dateFormat`
Type	Constant
Description	A string representing the expected format of date and time when presenting the date and time as a string to `hs.setDate()`. e.g. `os.date(hs.settings.dateFormat)`
Notes	None
Source	extensions/settings/libsettings.m line 320

# Functions

# clear


Signature	`hs.settings.clear(key) -> bool`
Type	Function
Description	Deletes a setting
Parameters	key - A string containing the name of a setting
Returns	A boolean, true if the setting was deleted, otherwise false
Notes	None
Examples	None
Source	extensions/settings/libsettings.m line 179

# get


Signature	`hs.settings.get(key) -> string or boolean or number or nil or table or binary data`
Type	Function
Description	Loads a setting
Parameters	key - A string containing the name of the setting
Returns	The value of the setting
Notes	This function can load all of the datatypes supported by `hs.settings.set()`, `hs.settings.setData()` and `hs.settings.setDate()`
Examples	None
Source	extensions/settings/libsettings.m line 157

# getKeys


Signature	`hs.settings.getKeys() -> table`
Type	Function
Description	Gets all of the previously stored setting names
Parameters	None
Returns	A table containing all of the settings keys in Hammerspoon's settings
Notes	Use `ipairs(hs.settings.getKeys())` to iterate over all available settings Use `hs.settings.getKeys()["someKey"]` to test for the existence of a particular key
Examples	None
Source	extensions/settings/libsettings.m line 200

# set

| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | hs.settings.set(key[, val]) | | Type | Function | | Description | Saves a setting with common datatypes | | Parameters |

key - A string containing the name of the setting
val - An optional value for the setting. Valid datatypes are: string number boolean nil table (which may contain any of the same valid datatypes)

| | Returns |

None

| | Notes |

If no val parameter is provided, it is assumed to be nil
This function cannot set dates or raw data types, see hs.settings.setDate() and hs.settings.setData()
Assigning a nil value is equivalent to clearing the value with hs.settings.clear

# setData


Signature	`hs.settings.setData(key, val)`
Type	Function
Description	Saves a setting with raw binary data
Parameters	key - A string containing the name of the setting val - Some raw binary data
Returns	None
Notes	None
Examples	None
Source	extensions/settings/libsettings.m line 91

# setDate


Signature	`hs.settings.setDate(key, val)`
Type	Function
Description	Saves a setting with a date
Parameters	key - A string containing the name of the setting val - A number representing seconds since `1970-01-01 00:00:00 +0000` (e.g. `os.time()`), or a string containing a date in RFC3339 format (`YYYY-MM-DD[T]HH:MM:SS[Z]`)
Returns	None
Notes	See `hs.settings.dateFormat` for a convenient representation of the RFC3339 format, to use with other time/date related functions
Examples	None
Source	extensions/settings/libsettings.m line 129

# watchKey


Signature	`hs.settings.watchKey(identifier, key, [fn]) -> identifier \| current value`
Type	Function
Description	Get or set a watcher to invoke a callback when the specified settings key changes
Parameters	identifier - a required string used as an identifier for this callback key - the settings key to watch for changes to fn - the callback function to be invoked when the specified key changes. If this is an explicit nil, removes the existing callback.
Returns	if a callback is set or removed, returns the identifier; otherwise returns the current callback function or nil if no callback function is currently defined.
Notes	the identifier is required so that multiple callbacks for the same key can be registered by separate modules; it's value doesn't affect what is being watched but does need to be unique between multiple watchers of the same key. Does not work with keys that include a period (.) in the key name because KVO uses dot notation to specify a sequence of properties. If you know of a way to escape periods so that they are watchable as NSUSerDefault key names, please file an issue and share!
Examples	None
Source	extensions/settings/libsettings.m line 230