docs » hs.spoons

Utility and management functions for Spoons Spoons are Lua plugins for Hammerspoon. See for more information

API Overview

API Documentation



Signature hs.spoons.bindHotkeysToSpec(def, map)
Type Method
Description Map a number of hotkeys according to a definition table
  • def - table containing name-to-function definitions for the hotkeys supported by the Spoon. Each key is a hotkey name, and its value must be a function that will be called when the hotkey is invoked.
  • map - table containing name-to-hotkey definitions, as supported by [bindHotkeys in the Spoon API]( Not all the entries in `def` must be bound, but if any keys in `map` don't have a definition, an error will be produced.
  • None


Signature hs.spoons.isInstalled(name)
Type Method
Description Check if a given Spoon is installed.
  • name - Name of the Spoon to check.
  • If the Spoon is installed, it returns a table with the Spoon information as returned by `list()`. Returns `nil` if the Spoon is not installed.


Signature hs.spoons.isLoaded(name)
Type Method
Description Check if a given Spoon is loaded.
  • name - Name of the Spoon to check.
  • `true` if the Spoon is loaded, `nil` otherwise.


Signature hs.spoons.list()
Type Method
Description Return a list of installed/loaded Spoons
  • only_loaded - only return loaded Spoons (skips those that are installed but not loaded). Defaults to `false`
  • Table with a list of installed/loaded spoons (depending on the value of `only_loaded`). Each entry is a table with the following entries:
  • `name` - Spoon name
  • `loaded` - boolean indication of whether the Spoon is loaded (`true`) or only installed (`false`)
  • `version` - Spoon version number. Available only for loaded Spoons.


Signature hs.spoons.newSpoon(name, basedir, metadata)
Type Method
Description Create a skeleton for a new Spoon
  • name: name of the new spoon, without the `.spoon` extension
  • basedir: (optional) directory where to create the template. Defaults to `~/.hammerspoon/Spoons`
  • metadata: (optional) table containing metadata values to be inserted in the template. Provided values are merged with the defaults. Defaults to:
  • ```
  • {
  • version = "0.1",
  • author = "Your Name ",
  • homepage = "",
  • license = "MIT -",
  • download_url = """"
  • }
  • ```
  • template: (optional) absolute path of the template to use for the `init.lua` file of the new Spoon. Defaults to the `templates/init.tpl` file included with Hammerspoon.
  • The full directory path where the template was created, or `nil` if there was an error.


Signature hs.spoons.resource_path(partial)
Type Method
Description Return full path of an object within a spoon directory, given its partial path.
  • partial - path of a file relative to the Spoon directory. For example `images/img1.png` will refer to a file within the `images` directory of the Spoon.
  • Absolute path of the file. Note: no existence or other checks are done on the path.


Signature hs.spoons.script_path()
Type Method
Description Return path of the current spoon.
  • n - (optional) stack level for which to get the path. Defaults to 2, which will return the path of the spoon which called `script_path()`
  • String with the path from where the calling code was loaded.


Signature hs.spoons.use(name, arg)
Type Method
Description Declaratively load and configure a Spoon
  • name - the name of the Spoon to load (without the `.spoon` extension).
  • arg - if provided, can be used to specify the configuration of the Spoon. The following keys are recognized (all are optional):
  • config - a table containing variables to be stored in the Spoon object to configure it. For example, `config = { answer = 42 }` will result in `spoon..answer` being set to 42.
  • hotkeys - a table containing hotkey bindings. If provided, will be passed as-is to the Spoon's `bindHotkeys()` method. The special string `"default"` can be given to use the Spoons `defaultHotkeys` variable, if it exists.
  • fn - a function which will be called with the freshly-loaded Spoon object as its first argument.
  • loglevel - if the Spoon has a variable called `logger`, its `setLogLevel()` method will be called with this value.
  • start - if `true`, call the Spoon's `start()` method after configuring everything else.
  • noerror - if `true`, don't log an error if the Spoon is not installed, simply return `nil`.
  • `true` if the spoon was loaded, `nil` otherwise

results matching ""

    No results matching ""