tools

​
A collection of handy miscellaneous tools for Lua development.
API Overview
Functions - API calls offered directly by the extension
​camelCase​
​centre​
​cleanupButtonText​
​contentsInsideBrackets​
​convertSingleHexStringToDecimalString​
​dirFiles​
​doesDirectoryExist​
​doesFileExist​
​doubleLeftClick​
​endsWith​
​ensureDirectoryExists​
​exactMatch​
​executeWithAdministratorPrivileges​
​findCommonWordWithinTwoStrings​
​firstToUpper​
​getEmail​
​getExternalDevices​
​getFileExtensionFromPath​
​getFilenameFromPath​
​getFullname​
​getKeysSortedByValue​
​getmacOSVersion​
​getModelName​
​getRAMSize​
​getScreenshotsAsBase64​
​getThunderboltDevices​
​getUSBDevices​
​getVRAMSize​
​hexStringToString​
​iconFallback​
​incrementFilename​
​incrementFilenameInPath​
​isNumberString​
​isOffScreen​
​leftClick​
​lines​
​lower​
​macOSVersion​
​mergeTable​
​ninjaDoubleClick​
​ninjaMouseAction​
​ninjaMouseClick​
​ninjaRightMouseClick​
​numberToWord​
​optionPressed​
​playErrorSound​
​readFromFile​
​removeFilenameFromPath​
​removeFromTable​
​replace​
​rescale​
​rightClick​
​rmdir​
​round​
​safeFilename​
​shiftPressed​
​spairs​
​split​
​splitOnColumn​
​startsWith​
​stringMaxLength​
​stringToHexString​
​tableContains​
​tableCount​
​tableFilter​
​tableMatch​
​toRegionalNumber​
​toRegionalNumberString​
​trim​
​unescape​
​upper​
​urlQueryStringDecode​
​volumeFormat​
​writeToFile​
Methods - API calls which can only be made on an object returned by a constructor
​escapeTilda​
​keyStroke​
​pressSystemKey​
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
​cleanupButtonText​
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
​contentsInsideBrackets​
| 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
|
​convertSingleHexStringToDecimalString​
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.
​doesDirectoryExist​
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
​doesFileExist​
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
​doubleLeftClick​
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
​ensureDirectoryExists​
| 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.
|
​exactMatch​
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.
​executeWithAdministratorPrivileges​
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.
​findCommonWordWithinTwoStrings​
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.
​firstToUpper​
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
​getExternalDevices​
Signature
cp.tools.getExternalDevices() -> string
Type
Function
Description
Returns a string of USB & Thunderbolt Devices.
Parameters
None
Returns
String
​getFileExtensionFromPath​
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.
​getFilenameFromPath​
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.
​getFullname​
Signature
cp.tools.getFullname() -> string
Type
Function
Description
Returns the current users Full Name, otherwise an empty string.
Parameters
None
Returns
String
​getKeysSortedByValue​
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
​getmacOSVersion​
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.
​getModelName​
Signature
cp.tools.getModelName() -> string
Type
Function
Description
Returns Model Name of Hardware.
Parameters
None
Returns
String
​getRAMSize​
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.
​getScreenshotsAsBase64​
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.
​getThunderboltDevices​
Signature
cp.tools.getThunderboltDevices() -> string
Type
Function
Description
Returns a string of Thunderbolt Devices.
Parameters
None
Returns
String
​getUSBDevices​
Signature
cp.tools.getUSBDevices() -> string
Type
Function
Description
Returns a string of USB Devices.
Parameters
None
Returns
String
​getVRAMSize​
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
​hexStringToString​
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
​iconFallback​
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
​incrementFilename​
Signature
cp.tools.incrementFilename(value) -> string
Type
Function
Description
Increments the filename.
Parameters
value - A string
Returns
A string
​incrementFilenameInPath​
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
​isNumberString​
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.
​isOffScreen​
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
​macOSVersion​
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
​mergeTable​
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
​ninjaDoubleClick​
Signature
cp.tools.ninjaDoubleClick(point[, delay]) -> none
Type
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
​ninjaMouseAction​
Signature
cp.tools.ninjaMouseAction(point, fn) -> none
Type
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
​ninjaMouseClick​
Signature
cp.tools.ninjaMouseClick(point[, delay]) -> none
Type
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
​ninjaRightMouseClick​
Signature
cp.tools.ninjaRightMouseClick(point[, delay]) -> none
Type
Function

API Overview

API Documentation

Functions

​camelCase​

​centre​

​cleanupButtonText​

​contentsInsideBrackets​

​convertSingleHexStringToDecimalString​

​dirFiles​

​doesDirectoryExist​

​doesFileExist​

​doubleLeftClick​

​endsWith​

​ensureDirectoryExists​

​exactMatch​

​executeWithAdministratorPrivileges​

​findCommonWordWithinTwoStrings​

​firstToUpper​

​getEmail​

​getExternalDevices​

​getFileExtensionFromPath​

​getFilenameFromPath​

​getFullname​

​getKeysSortedByValue​

​getmacOSVersion​

​getModelName​

​getRAMSize​

​getScreenshotsAsBase64​

​getThunderboltDevices​

​getUSBDevices​

​getVRAMSize​

​hexStringToString​

​iconFallback​

​incrementFilename​

​incrementFilenameInPath​

​isNumberString​

​isOffScreen​

​leftClick​

​lines​

​lower​

​macOSVersion​

​mergeTable​

​ninjaDoubleClick​

​ninjaMouseAction​

​ninjaMouseClick​

​ninjaRightMouseClick​

camelCase

centre

cleanupButtonText

contentsInsideBrackets

convertSingleHexStringToDecimalString

dirFiles

doesDirectoryExist

doesFileExist

doubleLeftClick

endsWith

ensureDirectoryExists

exactMatch

executeWithAdministratorPrivileges

findCommonWordWithinTwoStrings

firstToUpper

getEmail

getExternalDevices

getFileExtensionFromPath

getFilenameFromPath

getFullname

getKeysSortedByValue

getmacOSVersion

getModelName

getRAMSize

getScreenshotsAsBase64

getThunderboltDevices

getUSBDevices

getVRAMSize

hexStringToString

iconFallback

incrementFilename

incrementFilenameInPath

isNumberString

isOffScreen

leftClick

lines

lower

macOSVersion

mergeTable

ninjaDoubleClick

ninjaMouseAction

ninjaMouseClick

ninjaRightMouseClick