Getting Started
Contributing
Control CommandPost
Plugins
Internationalisation
CommandPost API
Bundled Plugins API
Hammerspoon API
tools
A collection of handy miscellaneous tools for Lua development.
API Overview
- Functions - API calls offered directly by the extension
- Methods - API calls which can only be made on an object returned by a constructor
API Documentation
Functions
Signature
cp.tools.camelCase(str) -> stringType
Function
Description
Converts the supplied string to camelcase.
Parameters
- str - The string you want to manipulate
Returns
- A string
Signature
cp.tools.centre(frame) -> hs.geometry pointType
Function
Description
Gets the centre point of a frame.
Parameters
- frame - an
hs.geometryrect
Returns
- A hs.geometry point
Signature
cp.tools.cleanupButtonText(value) -> stringType
Function
Description
Removes the … symbol and multiple >'s from a string.
Parameters
- value - A string
Returns
- A cleaned string
| Signature |
cp.tools.contentsInsideBrackets(value) -> string | nil | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Function | | Description | Gets the contents of any text inside the first bracket set. | | Parameters |- value - The string to process
| | Returns |
- The contents as a string or
nil
|
Signature
cp.tools.convertSingleHexStringToDecimalString(hex) -> stringType
Function
Description
Converts a single hex string (i.e. "3") to a binary string (i.e. "0011")
Parameters
- hex - A single string character
Returns
- A four character string
Signature
cp.tools.dirFiles(path) -> tableType
Function
Description
Gets all the files in a directory
Parameters
- path - A path as string
Returns
- A table containing filenames as strings, or
nilfollowed by the error message if an error occurs.
Signature
cp.tools.doesDirectoryExist(path) -> booleanType
Function
Description
Returns whether or not a directory exists.
Parameters
- path - Path to the directory
Returns
trueif the directory exists otherwisefalse
Signature
cp.tools.doesFileExist(path) -> booleanType
Function
Description
Returns whether or not a file exists.
Parameters
- path - Path to the file
Returns
trueif the file exists otherwisefalse
Signature
cp.tools.doubleLeftClick(point[, delay]) -> noneType
Function
Description
Performs a Left Mouse Double Click.
Parameters
- point - A point-table containing the absolute x and y co-ordinates to move the mouse pointer to
- delay - The optional delay between multiple mouse clicks
Returns
- None
Signature
cp.tools.endsWith(str, ending) -> booleanType
Function
Description
Checks to see if
str has the same ending as ending.Parameters
- str - String to analysis
- ending - End of string to compare against
Returns
- table
| Signature |
cp.tools.ensureDirectoryExists(rootPath, ...) -> string | nil | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Function | | Description | Ensures all steps on a provided path exist. If not, attempts to create them. | | Parameters |rootPath- The root path...- The list of path steps to create
| | Returns |
- The full path, if it exists, or
nilif unable to create the directory for some reason.
|
Signature
cp.tools.exactMatch(value, pattern, plain) -> booleanType
Function
Description
Compares two strings to see if they're an exact match.
Parameters
- value - The first string
- pattern - The second string, including any patterns
- plain - Whether or not to ignore patterns. Defaults to
false. - ignoreCase - Ignore the case of the value & pattern.
Returns
trueif there's an exact match, otherwisefalse.
Signature
cp.tools.executeWithAdministratorPrivileges(input[, stopOnError]) -> boolean or stringType
Function
Description
Executes a single or multiple shell commands with Administrator Privileges.
Parameters
- input - either a string or a table of strings of commands you want to execute
- stopOnError - an optional variable that stops processing multiple commands when an individual commands returns an error
Returns
trueif successful,falseif cancelled and a string if there's an error.
Signature
cp.tools.findCommonWordWithinTwoStrings(a, b) -> stringType
Function
Description
Finds a common word within two strings.
Parameters
- a - The first string
- b - The second string
Returns
- The first common word that's found or
nilif something goes wrong.
Signature
cp.tools.firstToUpper(str) -> stringType
Function
Description
Makes the first letter of a string uppercase.
Parameters
- str - The string you want to manipulate
Returns
- A string
Signature
cp.tools.getEmail() -> stringType
Function
Description
Returns the current users Email, otherwise an empty string.
Parameters
- None
Returns
- String
Signature
cp.tools.getExternalDevices() -> stringType
Function
Description
Returns a string of USB & Thunderbolt Devices.
Parameters
- None
Returns
- String
Signature
cp.tools.getFileExtensionFromPath(input) -> stringType
Function
Description
Gets the file extension from a path.
Parameters
- input - The path
Returns
- A string of the file extension.
Signature
cp.tools.getFilenameFromPath(input[, removeExtension]) -> stringType
Function
Description
Gets the filename component of a path.
Parameters
- input - The path
- removeExtension - (optional) set to
trueif the file extension should be removed
Returns
- A string of the filename.
Signature
cp.tools.getFullname() -> stringType
Function
Description
Returns the current users Full Name, otherwise an empty string.
Parameters
- None
Returns
- String
Signature
cp.tools.getKeysSortedByValue(tbl, sortFunction) -> tableType
Function
Description
Sorts table keys by a value
Parameters
- tbl - the table you want to sort
- sortFunction - the function you want to use to sort the table
Returns
- A sorted table
Signature
cp.tools.getmacOSVersion() -> stringType
Function
Description
Returns the macOS Version in the format that Apple's Feedback Form expects.
Parameters
- None
Returns
- The macOS version as a string or "" if unknown.
Signature
cp.tools.getModelName() -> stringType
Function
Description
Returns Model Name of Hardware.
Parameters
- None
Returns
- String
Signature
cp.tools.getRAMSize() -> stringType
Function
Description
Returns RAM Size in a format Apple's Feedback form expects.
Parameters
- None
Returns
- The RAM size as a string, or "" if unknown.
Signature
cp.tools.getScreenshotsAsBase64() -> tableType
Function
Description
Captures all available screens and saves them as base64 encodes in a table.
Parameters
- None
Returns
- A table containing base64 images of all available screens.
Signature
cp.tools.getThunderboltDevices() -> stringType
Function
Description
Returns a string of Thunderbolt Devices.
Parameters
- None
Returns
- String
Signature
cp.tools.getUSBDevices() -> stringType
Function
Description
Returns a string of USB Devices.
Parameters
- None
Returns
- String
Signature
cp.tools.getVRAMSize() -> stringType
Function
Description
Returns the VRAM size in format suitable for Apple's Final Cut Pro feedback form or "" if unknown.
Parameters
- None
Returns
- String
Signature
cp.tools.hexStringToString(value) -> stringType
Function
Description
Converts a hex string to a string.
Parameters
- value - The string to convert
Returns
- A string
Signature
cp.tools.iconFallback(paths) -> stringType
Function
Description
Excepts one or more paths to an icon, checks to see if they exist (in the order that they're given), and if none exist, returns the CommandPost icon path.
Parameters
- paths - One or more paths to an icon
Returns
- A string
Signature
cp.tools.incrementFilename(value) -> stringType
Function
Description
Increments the filename.
Parameters
- value - A string
Returns
- A string
Signature
cp.tools.incrementFilenameInPath(path) -> stringType
Function
Description
Increments the filename as it appears in a path.
Parameters
- path - A path to a file.
Returns
- A string
Signature
cp.tools.isNumberString(value) -> booleanType
Function
Description
Returns whether or not value is a number string.
Parameters
- value - the string you want to check
Returns
trueif value is a number string, otherwisefalse.
Signature
cp.tools.isOffScreen(rect) -> booleanType
Function
Description
Determines if the given rect is off screen or not.
Parameters
- rect - the rect you want to check
Returns
trueif offscreen otherwisefalse
Signature
cp.tools.leftClick(point[, delay, clickNumber]) -> noneType
Function
Description
Performs a Left Mouse Click.
Parameters
- point - A point-table containing the absolute x and y co-ordinates to move the mouse pointer to
- delay - The optional delay between multiple mouse clicks
- clickNumber - The optional number of times you want to perform the click.
Returns
- None
| Signature |
cp.tools.lines(string) -> table | nil | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Function | | Description | Splits a string containing multiple lines of text into a table. | | Parameters |- string - the string you want to process
| | Returns |
- A table or
nilif the parameter is not a string.
|
Signature
cp.tools.lower(str) -> stringType
Function
Description
Converts the supplied string to lowercase.
Parameters
- str - The string you want to manipulate
Returns
- A string
Signature
cp.tools.macOSVersion() -> stringType
Function
Description
Returns a the macOS Version as a single string.
Parameters
- None
Returns
- A string containing the macOS version
Signature
cp.tools.mergeTable(target, ...) -> tableType
Function
Description
Merges multiple tables into a target table.
Parameters
- target - The target table
- ... - Any other tables you want to merge into target
Returns
- Table
Signature
cp.tools.ninjaDoubleClick(point[, delay]) -> noneType
Function
Description
Performs a mouse double click, but returns the mouse to the original position without the users knowledge.
Parameters
- point - A point-table containing the absolute x and y co-ordinates to move the mouse pointer to
- delay - The optional delay between multiple mouse clicks
Returns
- None
Signature
cp.tools.ninjaMouseAction(point, fn) -> noneType
Function
Description
Moves the mouse to a point, performs a function, then returns the mouse to the original point.
Parameters
- point - A point-table containing the absolute x and y co-ordinates to move the mouse pointer to
- fn - A function you want to perform
Returns
- None
Signature
cp.tools.ninjaMouseClick(point[, delay]) -> noneType
Function
Description
Performs a mouse click, but returns the mouse to the original position without the users knowledge.
Parameters
- point - A point-table containing the absolute x and y co-ordinates to move the mouse pointer to
- delay - The optional delay between multiple mouse clicks
Returns
- None
Signature
cp.tools.ninjaRightMouseClick(point[, delay]) -> noneType
Function
Description
Performs a right mouse click, but returns the mouse to the original position without the users knowledge.
Parameters
- point - A point-table containing the absolute x and y co-ordinates to move the mouse pointer to
- delay - The optional delay between multiple mouse clicks
Returns
- None
Signature
cp.tools.numberToWord(number) -> stringType
Function
Description
Converts a number to a string (i.e. 1 becomes "One").
Parameters
- number - A whole number between 0 and 10
Returns
- A string
Signature
cp.tools.optionPressed() -> booleanType
Function
Description
Is the Option Key being pressed?
Parameters
- None