Internationalisation
Bundled Plugins API
tools
A collection of handy miscellaneous tools for Lua development.

API Overview

API Documentation

Functions

camelCase

Signature
cp.tools.camelCase(str) -> string
Type
Function
Description
Converts the supplied string to camelcase.
Parameters
  • str - The string you want to manipulate
Returns
  • A string

centre

Signature
cp.tools.centre(frame) -> hs.geometry point
Type
Function
Description
Gets the centre point of a frame.
Parameters
  • frame - an hs.geometry rect
Returns
  • A hs.geometry point
Signature
cp.tools.cleanupButtonText(value) -> string
Type
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) -> string
Type
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

dirFiles

Signature
cp.tools.dirFiles(path) -> table
Type
Function
Description
Gets all the files in a directory
Parameters
  • path - A path as string
Returns
  • A table containing filenames as strings, or nil followed by the error message if an error occurs.
Signature
cp.tools.doesDirectoryExist(path) -> boolean
Type
Function
Description
Returns whether or not a directory exists.
Parameters
  • path - Path to the directory
Returns
  • true if the directory exists otherwise false
Signature
cp.tools.doesFileExist(path) -> boolean
Type
Function
Description
Returns whether or not a file exists.
Parameters
  • path - Path to the file
Returns
  • true if the file exists otherwise false
Signature
cp.tools.doubleLeftClick(point[, delay]) -> none
Type
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

endsWith

Signature
cp.tools.endsWith(str, ending) -> boolean
Type
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 nil if unable to create the directory for some reason.
|
Signature
cp.tools.exactMatch(value, pattern, plain) -> boolean
Type
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
  • true if there's an exact match, otherwise false.
Signature
cp.tools.executeWithAdministratorPrivileges(input[, stopOnError]) -> boolean or string
Type
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
  • true if successful, false if cancelled and a string if there's an error.
Signature
cp.tools.findCommonWordWithinTwoStrings(a, b) -> string
Type
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 nil if something goes wrong.
Signature
cp.tools.firstToUpper(str) -> string
Type
Function
Description
Makes the first letter of a string uppercase.
Parameters
  • str - The string you want to manipulate
Returns
  • A string

getEmail

Signature
cp.tools.getEmail() -> string
Type
Function
Description
Returns the current users Email, otherwise an empty string.
Parameters
  • None
Returns
  • String
Signature
cp.tools.getExternalDevices() -> string
Type
Function
Description
Returns a string of USB & Thunderbolt Devices.
Parameters
  • None
Returns
  • String
Signature
cp.tools.getFileExtensionFromPath(input) -> string
Type
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]) -> string
Type
Function
Description
Gets the filename component of a path.
Parameters
  • input - The path
  • removeExtension - (optional) set to true if the file extension should be removed
Returns
  • A string of the filename.
Signature
cp.tools.getFullname() -> string
Type
Function
Description
Returns the current users Full Name, otherwise an empty string.
Parameters
  • None
Returns
  • String
Signature
cp.tools.getKeysSortedByValue(tbl, sortFunction) -> table
Type
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() -> string
Type
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() -> string
Type
Function
Description
Returns Model Name of Hardware.
Parameters
  • None
Returns
  • String
Signature
cp.tools.getRAMSize() -> string
Type
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() -> table
Type
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() -> string
Type
Function
Description
Returns a string of Thunderbolt Devices.
Parameters
  • None
Returns
  • String
Signature
cp.tools.getUSBDevices() -> string
Type
Function
Description
Returns a string of USB Devices.
Parameters
  • None
Returns
  • String
Signature
cp.tools.getVRAMSize() -> string
Type
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) -> string
Type
Function
Description
Converts a hex string to a string.
Parameters
  • value - The string to convert
Returns
  • A string
Signature
cp.tools.iconFallback(paths) -> string
Type
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) -> string
Type
Function
Description
Increments the filename.
Parameters
  • value - A string
Returns
  • A string
Signature
cp.tools.incrementFilenameInPath(path) -> string
Type
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) -> boolean
Type
Function
Description
Returns whether or not value is a number string.
Parameters
  • value - the string you want to check
Returns
  • true if value is a number string, otherwise false.
Signature
cp.tools.isOffScreen(rect) -> boolean
Type
Function
Description
Determines if the given rect is off screen or not.
Parameters
  • rect - the rect you want to check
Returns
  • true if offscreen otherwise false

leftClick

Signature
cp.tools.leftClick(point[, delay, clickNumber]) -> none
Type
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

lines

| 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 nil if the parameter is not a string.
|

lower

Signature
cp.tools.lower(str) -> string
Type
Function
Description
Converts the supplied string to lowercase.
Parameters
  • str - The string you want to manipulate
Returns
  • A string
Signature
cp.tools.macOSVersion() -> string
Type
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, ...) -> table
Type
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]) -> none
Type