CommandPost Developer Guide
DownloadUser GuideFacebook Group
Search…
⌃K
Links

hs

​
Core Hammerspoon functionality

Submodules

API Overview

API Documentation

Constants

​configdir​

Signature
hs.configdir
Type
Constant
Description
A string containing Hammerspoon's configuration directory. Typically ~/.hammerspoon/
Signature
hs.docstrings_json_file
Type
Constant
Description
A string containing the full path to the docs.json file inside Hammerspoon's app bundle. This contains the full Hammerspoon API documentation and can be accessed in the Console using help("someAPI"). It can also be loaded and processed by the hs.doc extension
Signature
hs.processInfo
Type
Constant
Description
A table containing read-only information about the Hammerspoon application instance currently running.

Variables

Signature
hs.accessibilityStateCallback
Type
Variable
Description
An optional function that will be called when the Accessibility State is changed.
Notes
  • The function will not receive any arguments when called. To check what the accessibility state has been changed to, you should call hs.accessibilityState from within your function.
Signature
hs.completionsForInputString(completionWord) -> table of strings
Type
Variable
Description
Gathers tab completion options for the Console window
Parameters
  • completionWord - A string from the Console window's input field that completions are needed for
Returns
  • A table of strings, each of which will be shown as a possible completion option to the user
Notes
  • Hammerspoon provides a default implementation of this function, which can complete against the global Lua namespace, the 'hs' (i.e. extension) namespace, and object metatables. You can assign a new function to the variable to replace it with your own variant.
Signature
hs.dockIconClickCallback
Type
Variable
Description
An optional function that will be called when the Hammerspoon Dock Icon is clicked while the app is running
Notes
  • If set, this callback will be called regardless of whether or not Hammerspoon shows its console window in response to a click (which can be enabled/disabled via hs.openConsoleOnDockClick()
Signature
hs.fileDroppedToDockIconCallback
Type
Variable
Description
An optional function that will be called when a files are dragged to the Hammerspoon Dock Icon or sent via the Services menu
Notes
  • The function should accept a single parameter, which will be a string containing the full path to the file that was dragged to the dock icon
  • If multiple files are sent, this callback will be called once for each file
  • This callback will be triggered when ANY file type is dragged onto the Hammerspoon Dock Icon, however certain filetypes are also processed seperately by Hammerspoon. For example, hs.urlevent will be triggered when the following filetypes are dropped onto the Dock Icon: HTML Documents (.html, .htm, .shtml, .jhtml), Plain text documents (.txt, .text), Web site locations (.url), XHTML documents (.xhtml, .xht, .xhtm, .xht).
Signature
hs.shutdownCallback
Type
Variable
Description
An optional function that will be called when the Lua environment is being destroyed (either because Hammerspoon is exiting or reloading its config)
Notes
  • This function should not perform any asynchronous tasks
  • You do not need to fastidiously destroy objects you have created, this callback exists purely for utility reasons (e.g. serialising state, destroying system resources that will not be released by normal Lua garbage collection processes, etc)
Signature
hs.textDroppedToDockIconCallback
Type
Variable
Description
An optional function that will be called when text is dragged to the Hammerspoon Dock Icon or sent via the Services menu
Notes
  • The function should accept a single parameter, which will be a string containing the text that was dragged to the dock icon

Functions

Signature
hs.accessibilityState(shouldPrompt) -> isEnabled
Type
Function
Description
Checks the Accessibility Permissions for Hammerspoon, and optionally allows you to prompt for permissions.
Parameters
  • shouldPrompt - an optional boolean value indicating if the dialog box asking if the System Preferences application should be opened should be presented when Accessibility is not currently enabled for Hammerspoon. Defaults to false.
Returns
  • True or False indicating whether or not Accessibility is enabled for Hammerspoon.
Notes
  • Since this check is done automatically when Hammerspoon loads, it is probably of limited use except for skipping things that are known to fail when Accessibility is not enabled. Evettaps which try to capture keyUp and keyDown events, for example, will fail until Accessibility is enabled and the Hammerspoon application is relaunched.
Signature
hs.allowAppleScript([state]) -> bool
Type
Function
Description
Set or display whether or not external Hammerspoon AppleScript commands are allowed.
Parameters
  • state - an optional boolean which will set whether or not external Hammerspoon's AppleScript commands are allowed.
Returns
  • A boolean, true if Hammerspoon's AppleScript commands are (or has just been) allowed, otherwise false.
Notes
  • AppleScript access is disallowed by default.
  • However due to the way AppleScript support works, Hammerspoon will always allow AppleScript commands that are part of the "Standard Suite", such as name, quit, version, etc. However, Hammerspoon will only allow commands from the "Hammerspoon Suite" if hs.allowAppleScript() is set to true.
  • For a full list of AppleScript Commands:
    • Open /Applications/Utilities/Script Editor.app
    • Click File > Open Dictionary...
    • Select Hammerspoon from the list of Applications
    • This will now open a Dictionary containing all of the availible Hammerspoon AppleScript commands.
  • Note that strings within the Lua code you pass from AppleScript can be delimited by [[ and ]] rather than normal quotes
  • Example:
Signature
hs.autoLaunch([state]) -> bool
Type
Function
Description
Set or display the "Launch on Login" status for Hammerspoon.
Parameters
  • state - an optional boolean which will set whether or not Hammerspoon should be launched automatically when you log into your computer.
Returns
  • True if Hammerspoon is currently (or has just been) set to launch on login or False if Hammerspoon is not.
Signature
hs.automaticallyCheckForUpdates([setting]) -> bool
Type
Function
Description
Gets and optionally sets the Hammerspoon option to automatically check for updates.
Parameters
  • setting - an optional boolean variable indicating if Hammerspoon should (true) or should not (false) check for updates.
Returns
  • The current (or newly set) value indicating whether or not automatic update checks should occur for Hammerspoon.
Notes
  • If you are running a non-release or locally compiled version of Hammerspoon then the results of this function are unspecified.
Signature
hs.cameraState(shouldPrompt) -> boolean
Type
Function
Description
Checks the Camera Permissions for Hammerspoon, and optionally allows you to prompt for permissions.
Parameters
  • shouldPrompt - an optional boolean value indicating if we should request camear access. Defaults to false.
Returns
  • true or false indicating whether or not Camera access is enabled for Hammerspoon.
Notes
  • Will always return true on macOS 10.13 or earlier.
Signature
hs.canCheckForUpdates() -> boolean
Type
Function
Description
Returns a boolean indicating whether or not the Sparkle framework is available to check for Hammerspoon updates.
Parameters
  • None
Returns
  • a boolean indicating whether or not the Sparkle framework is available to check for Hammerspoon updates
Notes
  • The Sparkle framework is included in all regular releases of Hammerspoon but not included if you are running a non-release or locally compiled version of Hammerspoon, so this function can be used as a simple test to determine whether or not you are running a formal release Hammerspoon or not.
Signature
hs.checkForUpdates([silent]) -> none
Type
Function
Description
Check for an update now, and if one is available, prompt the user to continue the update process.
Parameters
  • silent - An optional boolean. If true, no UI will be displayed if an update is available. Defaults to false.
Returns
  • None
Notes
  • If you are running a non-release or locally compiled version of Hammerspoon then the results of this function are unspecified.
Signature
hs.cleanUTF8forConsole(inString) -> outString
Type
Function
Description
Returns a copy of the incoming string that can be displayed in the Hammerspoon console. Invalid UTF8 sequences are converted to the Unicode Replacement Character and NULL (0x00) is converted to the Unicode Empty Set character.
Parameters
  • inString - the string to be cleaned up
Returns
  • outString - the cleaned up version of the input string.
Notes
  • This function is applied automatically to all output which appears in the Hammerspoon console, but not to the output provided by the hs command line tool.
  • This function does not modify the original string - to actually replace it, assign the result of this function to the original string.
  • This function is a more specifically targeted version of the hs.utf8.fixUTF8(...) function.
Signature
hs.closeConsole()
Type
Function
Description
Closes the Hammerspoon Console window
Parameters
  • None
Returns
  • None
Signature
hs.closePreferences()
Type
Function
Description
Closes the Hammerspoon Preferences window
Parameters
  • None
Returns