Skip to content
This repository has been archived by the owner on Jun 9, 2023. It is now read-only.

Latest commit

 

History

History
101 lines (84 loc) · 9.49 KB

hs.settings.md

File metadata and controls

101 lines (84 loc) · 9.49 KB
Raw

docs » 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

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

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)

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

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

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 existance of a particular key

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

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

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