docs » hs.settings

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

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)

Deletes a setting

• key - A string containing the name of a setting

• A boolean, true if the setting was deleted, otherwise false

Loads a setting

• key - A string containing the name of the setting

• The value of the setting

• This function can load all of the datatypes supported by hs.settings.set(), hs.settings.setData() and hs.settings.setDate()

Gets all of the previously stored setting names

• None

• A table containing all of the settings keys in Hammerspoon's settings

• 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

Saves a setting with common datatypes

• 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)

• None

• 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

Saves a setting with raw binary data

• key - A string containing the name of the setting
• val - Some raw binary data

• None

Saves a setting with a date

• 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])

• None

• See hs.settings.dateFormat for a convenient representation of the RFC3339 format, to use with other time/date related functions

Get or set a watcher to invoke a callback when the specified settings key changes

• 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.

• 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.

• 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!