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