#hs.console

Some functions for manipulating the Hammerspoon console.

These functions allow altering the behavior and display of the Hammerspoon console. They should be considered experimental, but have worked well for me.

#API Overview

Deprecateds - API features which will be removed in an future release

asHSDrawing
asHSWindow

Constants - Useful values which cannot be changed

defaultToolbar

Functions - API calls offered directly by the extension

alpha
behaviorAsLabels
clearConsole
consoleCommandColor
consoleFont
consolePrintColor
consoleResultColor
darkMode
getConsole
getHistory
hswindow
inputBackgroundColor
level
maxOutputHistory
outputBackgroundColor
printStyledtext
setConsole
setHistory
smartInsertDeleteEnabled
titleVisibility
windowBackgroundColor

Methods - API calls which can only be made on an object returned by a constructor

behavior
toolbar

#API Documentation

#Deprecateds

#asHSDrawing


Signature	`hs.console.asHSDrawing() -> hs.drawing object`
Type	Deprecated
Description	Because use of this function can easily lead to a crash, useful methods from `hs.drawing` have been added to the `hs.console` module itself. If you believe that a useful method has been overlooked, please submit an issue.
Parameters	None
Returns	a placeholder object
Notes	None
Source	extensions/console/console.lua line 43

#asHSWindow


Signature	`hs.console.asHSWindow() -> hs.window object`
Type	Deprecated
Description	Returns an hs.window object for the console so that you can use hs.window methods on it.
Notes	None
Source	extensions/console/console.lua line 78

#Constants

#defaultToolbar


Signature	`hs.console.defaultToolbar`
Type	Constant
Description	Default toolbar for the Console window
Notes	This is an `hs.toolbar` object that is shown by default in the Hammerspoon Console You can remove this toolbar by adding `hs.console.toolbar(nil)` to your config, or you can replace it with your own `hs.webview.toolbar` object
Source	extensions/_coresetup/_coresetup.lua line 700

#Functions

#alpha


Signature	`hs.console.alpha([alpha]) -> currentValue`
Type	Function
Description	Get or set the alpha level of the console window.
Parameters	`alpha` - an optional number between 0.0 and 1.0 specifying the new alpha level for the Hammerspoon console.
Returns	the current, possibly new, value.
Notes	None
Examples	None
Source	extensions/console/libconsole.m line 506

#behaviorAsLabels


Signature	`hs.console.behaviorAsLabels(behaviorTable) -> currentValue`
Type	Function
Description	Get or set the window behavior settings for the console using labels defined in `hs.drawing.windowBehaviors`.
Parameters	behaviorTable - an optional table of strings and/or numbers specifying the desired window behavior for the Hammerspoon console.
Returns	the current (possibly new) value.
Notes	Window behaviors determine how the console is handled by Spaces and Exposé. See `hs.drawing.windowBehaviors` for more information.
Examples	None
Source	extensions/console/console.lua line 88

#clearConsole


Signature	`hs.console.clearConsole() -> nil`
Type	Function
Description	Clear the Hammerspoon console output window.
Parameters	None
Returns	None
Notes	This is equivalent to `hs.console.setConsole()`
Examples	None
Source	extensions/console/console.lua line 27

#consoleCommandColor


Signature	`hs.console.consoleCommandColor([color]) -> color`
Type	Function
Description	Get or set the color that commands displayed in the Hammerspoon console are displayed with.
Parameters	color - an optional table containing color keys as described in `hs.drawing.color`
Returns	the current color setting as a table
Notes	See the `hs.drawing.color` entry in the Dash documentation, or type `help.hs.drawing.color` in the Hammerspoon console to get more information on how to specify a color. Note this only affects future output -- anything already in the console will remain its current color.
Examples	None
Source	extensions/console/libconsole.m line 143

#consoleFont


Signature	`hs.console.consoleFont([font]) -> fontTable`
Type	Function
Description	Get or set the font used in the Hammerspoon console.
Parameters	font - an optional string or table describing the font to use in the console. If a string is specified, then the default system font size will be used. If a table is specified, it should contain a `name` key-value pair and a `size` key-value pair describing the font to be used.
Returns	the current font setting as a table containing a `name` key and a `size` key.
Notes	See the `hs.drawing.color` entry in the Dash documentation, or type `help.hs.drawing.color` in the Hammerspoon console to get more information on how to specify a color. Note this only affects future output -- anything already in the console will remain its current font.
Examples	None
Source	extensions/console/libconsole.m line 117

#consolePrintColor


Signature	`hs.console.consolePrintColor([color]) -> color`
Type	Function
Description	Get or set the color that regular output displayed in the Hammerspoon console is displayed with.
Parameters	color - an optional table containing color keys as described in `hs.drawing.color`
Returns	the current color setting as a table
Notes	See the `hs.drawing.color` entry in the Dash documentation, or type `help.hs.drawing.color` in the Hammerspoon console to get more information on how to specify a color. Note this only affects future output -- anything already in the console will remain its current color.
Examples	None
Source	extensions/console/libconsole.m line 65

#consoleResultColor


Signature	`hs.console.consoleResultColor([color]) -> color`
Type	Function
Description	Get or set the color that function results displayed in the Hammerspoon console are displayed with.
Parameters	color - an optional table containing color keys as described in `hs.drawing.color`
Returns	the current color setting as a table
Notes	See the `hs.drawing.color` entry in the Dash documentation, or type `help.hs.drawing.color` in the Hammerspoon console to get more information on how to specify a color. Note this only affects future output -- anything already in the console will remain its current color.
Examples	None
Source	extensions/console/libconsole.m line 169

#darkMode


Signature	`hs.console.darkMode([state]) -> bool`
Type	Function
Description	Set or display whether or not the Console window should display in dark mode.
Parameters	state - an optional boolean which will set whether or not the Console window should display in dark mode.
Returns	A boolean, true if dark mode is enabled otherwise false.
Notes	Enabling Dark Mode for the Console only affects the window background, and doesn't automatically change the Console's Background Color, so you will need to add something similar to: `lua</li><li> if hs.console.darkMode() then</li><li> hs.console.outputBackgroundColor{ white = 0 }</li><li> hs.console.consoleCommandColor{ white = 1 }</li><li> hs.console.alpha(.8)</li><li> end</li><li>.`
Examples	None
Source	extensions/console/libconsole.m line 33

#getConsole


Signature	`hs.console.getConsole([styled]) -> text \| styledText`
Type	Function
Description	Get the text of the Hammerspoon console output window.
Parameters	styled - an optional boolean indicating whether the console text is returned as a string or a styledText object. Defaults to false.
Returns	The text currently in the Hammerspoon console output window as either a string or an `hs.styledtext` object.
Notes	If the text of the console is retrieved as a string, no color or style information in the console output is retrieved - only the raw text.
Examples	None
Source	extensions/console/libconsole.m line 373

#getHistory


Signature	`hs.console.getHistory() -> array`
Type	Function
Description	Get the Hammerspoon console command history as an array.
Parameters	None
Returns	an array containing the history of commands entered into the Hammerspoon console.
Notes	None
Examples	None
Source	extensions/console/libconsole.m line 314

#hswindow


Signature	`hs.console.hswindow() -> hs.window object`
Type	Function
Description	Get an hs.window object which represents the Hammerspoon console window
Parameters	None
Returns	an hs.window object
Notes	None
Examples	None
Source	extensions/console/libconsole.m line 195

#inputBackgroundColor


Signature	`hs.console.inputBackgroundColor([color]) -> color`
Type	Function
Description	Get or set the color for the background of the Hammerspoon Console's input field.
Parameters	color - an optional table containing color keys as described in `hs.drawing.color`
Returns	the current color setting as a table
Notes	See the `hs.drawing.color` entry in the Dash documentation, or type `help.hs.drawing.color` in the Hammerspoon console to get more information on how to specify a color.
Examples	None
Source	extensions/console/libconsole.m line 266

#level


Signature	`hs.console.level([theLevel]) -> currentValue`
Type	Function
Description	Get or set the console window level
Parameters	`theLevel` - an optional parameter specifying the desired level as an integer, which can be obtained from `hs.drawing.windowLevels`.
Returns	the current, possibly new, value
Notes	see the notes for `hs.drawing.windowLevels`
Examples	None
Source	extensions/console/libconsole.m line 474

#maxOutputHistory


Signature	`hs.console.maxOutputHistory([length]) -> number`
Type	Function
Description	Get or set the max length of the Hammerspoon console's scrollback history.
Parameters	length - an optional number containing the maximum size in bytes of the Hammerspoon console history.
Returns	the current maximum size of the console history
Notes	A length value of zero will allow the history to grow infinitely The default console history is 100,000 characters
Examples	None
Source	extensions/console/libconsole.m line 91

#outputBackgroundColor


Signature	`hs.console.outputBackgroundColor([color]) -> color`
Type	Function
Description	Get or set the color for the background of the Hammerspoon Console's output view.
Parameters	color - an optional table containing color keys as described in `hs.drawing.color`
Returns	the current color setting as a table
Notes	See the `hs.drawing.color` entry in the Dash documentation, or type `help.hs.drawing.color` in the Hammerspoon console to get more information on how to specify a color.
Examples	None
Source	extensions/console/libconsole.m line 241

#printStyledtext


Signature	`hs.console.printStyledtext(...) -> none`
Type	Function
Description	A print function which recognizes `hs.styledtext` objects and renders them as such in the Hammerspoon console.
Parameters	Any number of arguments can be specified, just like the builtin Lua `print` command. If an argument matches the userdata type of `hs.styledtext`, the text is rendered as defined by its style attributes in the Hammerspoon console; otherwise it is rendered as it would be via the traditional `print` command within Hammerspoon.
Returns	None
Notes	This has been made as close to the Lua `print` command as possible. You can replace the existing print command with this by adding the following to your `init.lua` file: print = function(...) hs.rawprint(...) hs.console.printStyledtext(...) end
Examples	None
Source	extensions/console/libconsole.m line 423

#setConsole


Signature	`hs.console.setConsole([styledText]) -> none`
Type	Function
Description	Clear the Hammerspoon console output window.
Parameters	styledText - an optional `hs.styledtext` object containing the text you wish to replace the Hammerspoon console output with. If you do not provide an argument, the console is cleared of all content.
Returns	None
Notes	You can specify the console content as a string or as an `hs.styledtext` object in either userdata or table format.
Examples	None
Source	extensions/console/libconsole.m line 332

#setHistory


Signature	`hs.console.setHistory(array) -> nil`
Type	Function
Description	Set the Hammerspoon console command history to the items specified in the given array.
Parameters	array - the list of commands to set the Hammerspoon console history to.
Returns	None
Notes	You can clear the console history by using an empty array (e.g. `hs.console.setHistory({})`
Examples	None
Source	extensions/console/libconsole.m line 400

#smartInsertDeleteEnabled


Signature	`hs.console.smartInsertDeleteEnabled([flag]) -> bool`
Type	Function
Description	Determine whether or not objects copied from the console window insert or delete space around selected words to preserve proper spacing and punctuation.
Parameters	flag - an optional boolean value indicating whether or not "smart" space behavior is enabled when copying from the Hammerspoon console.
Returns	the current value
Notes	this only applies to future copy operations from the Hammerspoon console -- anything already in the clipboard is not affected.
Examples	None
Source	extensions/console/libconsole.m line 291

#titleVisibility


Signature	`hs.console.titleVisibility([state]) -> current value`
Type	Function
Description	Get or set whether or not the "Hammerspoon Console" text appears in the Hammerspoon console titlebar.
Parameters	state - an optional string containing the text "visible" or "hidden", specifying whether or not the console window's title text appears.
Returns	a string of "visible" or "hidden" specifying the current (possibly changed) state of the window title's visibility.
Notes	When a toolbar is attached to the Hammerspoon console (see the `hs.webview.toolbar` module documentation), this function can be used to specify whether the Toolbar appears underneath the console window's title ("visible") or in the window's title bar itself, as seen in applications like Safari ("hidden"). When the title is hidden, the toolbar will only display the toolbar items as icons without labels, and ignores changes made with `hs.webview.toolbar:displayMode`. If a toolbar is attached to the console, you can achieve the same effect as this function with `hs.console.toolbar():inTitleBar(boolean)`
Examples	None
Source	extensions/console/libconsole.m line 563

#windowBackgroundColor


Signature	`hs.console.windowBackgroundColor([color]) -> color`
Type	Function
Description	Get or set the color for the background of the Hammerspoon Console's window.
Parameters	color - an optional table containing color keys as described in `hs.drawing.color`
Returns	the current color setting as a table
Notes	See the `hs.drawing.color` entry in the Dash documentation, or type `help.hs.drawing.color` in the Hammerspoon console to get more information on how to specify a color.
Examples	None
Source	extensions/console/libconsole.m line 216

#Methods

#behavior


Signature	`hs.console.behavior([behavior]) -> currentValue`
Type	Method
Description	Get or set the window behavior settings for the console.
Parameters	`behavior` - an optional number representing the desired window behaviors for the Hammerspoon console.
Returns	the current, possibly new, value.
Notes	Window behaviors determine how the webview object is handled by Spaces and Exposé. See `hs.drawing.windowBehaviors` for more information.
Examples	None
Source	extensions/console/libconsole.m line 528


Signature	`hs.console.toolbar([toolbar]) -> toolbarObject \| currentValue`
Type	Method
Description	Get or attach/detach a toolbar to/from the Hammerspoon console.
Parameters	`toolbar` - if an `hs.webview.toolbar` object is specified, it will be attached to the Hammerspoon console. If an explicit nil is specified, the current toolbar will be removed from the console.
Returns	if a toolbarObject or explicit nil is specified, returns the toolbarObject; otherwise returns the current toolbarObject or nil, if no toolbar is attached to the console.
Notes	this method is a convenience wrapper for the `hs.webview.toolbar.attachToolbar` function. If the toolbar is currently attached to another window when this function is called, it will be detached from the original window and attached to the console.
Examples	None
Source	extensions/console/console.lua line 136