# hs.spoons

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


# API Overview

Functions - API calls offered directly by the extension

  • bindHotkeysToSpec
  • isInstalled
  • isLoaded
  • list
  • newSpoon
  • resourcePath
  • scriptPath
  • use

# API Documentation

# Functions

# bindHotkeysToSpec

Signature hs.spoons.bindHotkeysToSpec(def, map) -> none
Type Function
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 and an optional message to be displayed via hs.alert() when the hotkey has been triggered, 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
Notes None
Examples None
Source extensions/spoons/spoons.lua line 123

# isInstalled

Signature hs.spoons.isInstalled(name) -> table | nil
Type Function
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.
Notes None
Examples None
Source extensions/spoons/spoons.lua line 182

# isLoaded

Signature hs.spoons.isLoaded(name) -> boolean | nil
Type Function
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.
Notes None
Examples None
Source extensions/spoons/spoons.lua line 201

# list

Signature hs.spoons.list() -> table
Type Function
Description Return a list of installed/loaded Spoons
Parameters
  • onlyLoaded - 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 onlyLoaded). 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.
Notes None
Examples None
Source extensions/spoons/spoons.lua line 148

# newSpoon

Signature hs.spoons.newSpoon(name, basedir, metadata, [template]) -> string | nil
Type Function
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 <[email protected]>", 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.
Notes None
Examples None
Source extensions/spoons/spoons.lua line 40

# resourcePath

Signature hs.spoons.resourcePath(partial) -> string
Type Function
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.
Notes None
Examples None
Source extensions/spoons/spoons.lua line 110

# scriptPath

Signature hs.spoons.scriptPath([n]) -> string
Type Function
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 scriptPath()
Returns
  • String with the path from where the calling code was loaded.
Notes None
Examples None
Source extensions/spoons/spoons.lua line 95

# use

| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | hs.spoons.use(name, arg, [noerror]) -> boolean | nil | | Type | Function | | 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
| | Notes | None | | Examples | None | | Source | extensions/spoons/spoons.lua line 220 |