docs » hs.spoons

Utility and management functions for Spoons Spoons are Lua plugins for Hammerspoon. See http://www.hammerspoon.org/Spoons/ for more information

API Overview

API Documentation

Methods

bindHotkeysToSpec
Signature hs.spoons.bindHotkeysToSpec(def, map)
Type Method
Description

Map a number of hotkeys according to a definition table

Parameters:

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

Returns:

  • None
isInstalled
Signature hs.spoons.isInstalled(name)
Type Method
Description

Check if a given Spoon is installed.

Parameters:

  • name - Name of the Spoon to check.

Returns:

  • 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.
isLoaded
Signature hs.spoons.isLoaded(name)
Type Method
Description

Check if a given Spoon is loaded.

Parameters:

  • name - Name of the Spoon to check.

Returns:

  • true if the Spoon is loaded, nil otherwise.
list
Signature hs.spoons.list()
Type Method
Description

Return a list of installed/loaded Spoons

Parameters:

  • only_loaded - only return loaded Spoons (skips those that are installed but not loaded). Defaults to false

Returns:

  • 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.
newSpoon
Signature hs.spoons.newSpoon(name, basedir, metadata)
Type Method
Description

Create a skeleton for a new Spoon

Parameters:

  • 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 <your@email.org>",
      homepage = "https://github.com/Hammerspoon/Spoons",
      license = "MIT - https://opensource.org/licenses/MIT",
      download_url = "https://github.com/Hammerspoon/Spoons/raw/master/Spoons/"..name..".spoon.zip"
    }
  • 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.

Returns:

  • The full directory path where the template was created, or nil if there was an error.
resource_path
Signature hs.spoons.resource_path(partial)
Type Method
Description

Return full path of an object within a spoon directory, given its partial path.

Parameters:

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

Returns:

  • Absolute path of the file. Note: no existence or other checks are done on the path.
script_path
Signature hs.spoons.script_path()
Type Method
Description

Return path of the current spoon.

Parameters:

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

Returns:

  • String with the path from where the calling code was loaded.
use
Signature hs.spoons.use(name, arg)
Type Method
Description

Declaratively load and configure a Spoon

Parameters:

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

Returns:

  • true if the spoon was loaded, nil otherwise