cp.tools.md

docs » cp.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
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

numberToWord

Signature	cp.tools.numberToWord(number) -> string
Type	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

optionPressed

Signature	cp.tools.optionPressed() -> boolean
Type	Function
Description	Is the Option Key being pressed?
Parameters	None
Returns	true if the option key is being pressed, otherwise false.

playErrorSound

Signature	cp.tools.playErrorSound() -> none
Type	Function
Description	Plays the "Funk" error sound.
Parameters	None
Returns	None

readFromFile

Signature	cp.tools.readFromFile(path) -> string
Type	Function
Description	Read data from file.
Parameters	path - The path of where you want to load the file.
Returns	None

removeFilenameFromPath

Signature	cp.tools.removeFilenameFromPath(string) -> string
Type	Function
Description	Removes the filename from a path.
Parameters	string - The path
Returns	A string of the path without the filename.

removeFromTable

Signature	cp.tools.removeFromTable(table, element) -> table
Type	Function
Description	Removes a string from a table of strings
Parameters	table - the table you want to check element - the string you want to remove
Returns	A table

replace

Signature	cp.tools.replace(text, old, new) -> string
Type	Function
Description	A find and replace feature that doesn't use patterns.
Parameters	text - The string you want to process old - The string you want to find new - The new string you want to replace the old string with
Returns	A new string

rescale

| Signature | cp.tools.rescale(value, inMin, inMax, outMin, outMax) -> number | nil | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Function | | Description | Takes an input, rescales it, and provides a new output. | | Parameters |

• value - The value you want to process as a number
• inMin - The minimum value of the input as a number
• inMax - The maximum value of the input as a number
• outMin - The minimum value of the output as a number
• outMax - The maximum value of the output as a number

| | Returns |

• The rescaled value as a number or nil.

|

rightClick

Signature	cp.tools.rightClick(point[, delay, clickNumber]) -> none
Type	Function
Description	Performs a Right 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

rmdir

| Signature | cp.tools.rmdir(path[, recursive]) -> true | nil, err | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Function | | Description | Attempts to remove the directory at the specified path, optionally removing | | Parameters |

• path - The absolute path to remove
• recursive - If true, the contents of the directory will be removed first.

| | Returns |

• true if successful, or nil, err if there was a problem.

|

round

Signature	cp.tools.round(num, numDecimalPlaces) -> number
Type	Function
Description	Rounds a number to a set number of decimal places
Parameters	num - The number you want to round numDecimalPlaces - How many numbers of decimal places (defaults to 0)
Returns	A rounded number

safeFilename

Signature	cp.tools.safeFilename(value[, defaultValue]) -> string
Type	Function
Description	Returns a Safe Filename.
Parameters	value - a string you want to make safe defaultValue - the optional default filename to use if the value is not valid
Returns	A string of the safe filename
Notes	Returns "filename" is both value and defaultValue are nil.

shiftPressed

Signature	cp.tools.shiftPressed() -> boolean
Type	Function
Description	Is the Shift Key being pressed?
Parameters	None
Returns	true if the shift key is being pressed, otherwise false.

spairs

Signature	cp.tools.spairs(t, order) -> function
Type	Function
Description	A customised version of pairs, called spairs because it iterates over the table in a sorted order.
Parameters	t - The table to process order - The function of how to sort the table.
Returns	A iterator function.
Notes	Author: Michal Kottman

split

Signature	cp.tools.split(str, pat) -> table
Type	Function
Description	Splits a string with a pattern.
Parameters	str - The string to split pat - The pattern
Returns	Table

splitOnColumn

Signature	cp.tools.splitOnColumn() -> string
Type	Function
Description	Splits a string on a column.
Parameters	Input
Returns	String

startsWith

Signature	cp.tools.startsWith(value, startValue) -> boolean
Type	Function
Description	Checks to see if a string starts with a value.
Parameters	value - The value to check startValue - The value to look for
Returns	true if value starts with the startValue, otherwise false

stringMaxLength

Signature	cp.tools.stringMaxLength(string, maxLength[, optionalEnd]) -> string
Type	Function
Description	Trims a string based on a maximum length.
Parameters	maxLength - The length of the string as a number optionalEnd - A string that is applied to the end of the input string if the input string is larger than the maximum length.
Returns	A string

stringToHexString

Signature	cp.tools.stringToHexString(value) -> string
Type	Function
Description	Converts a string to a hex string.
Parameters	value - The string to convert
Returns	A hex string

tableContains

Signature	cp.tools.tableContains(table, element) -> boolean
Type	Function
Description	Does a element exist in a table?
Parameters	table - the table you want to check element - the element you want to check for
Returns	Boolean

tableCount

Signature	cp.tools.tableCount(table) -> number
Type	Function
Description	Returns how many items are in a table.
Parameters	table - The table you want to count.
Returns	The number of items in the table.
Notes	If something other than a table is supplied, this function will return 0.

tableFilter

Signature	cp.tools.tableFilter(t, matchFn) -> table
Type	Function
Description	Efficiently filters out all elements from the table t which to not match the matchFn.
Parameters	t - The table to filter. matchFn - A function which will receive the table, the current index, and the target index.
Returns	The same table, updated.

tableMatch

Signature	cp.tools.tableMatch(t1, t2[, ignoreMetatable]) -> boolean
Type	Function
Description	Compares two tables.
Parameters	t1 - The first table. t2 - The second table. ignoreMetatable - A boolean that determines whether or not we should ignore the metatable.
Returns	true if t1 and t2 are identical, otherwise false.

toRegionalNumber

| Signature | cp.tools.toRegionalNumber(value) -> number | nil | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Function | | Description | Takes a string and converts it into a number, with the correct | | Parameters |

• value - The value you want to process as a string.

| | Returns |

• The value as a number or nil.

|

toRegionalNumberString

| Signature | cp.tools.toRegionalNumberString(value) -> string | nil | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Function | | Description | Takes a number and converts it into a string, with the correct | | Parameters |

• value - The value you want to process as a number.

| | Returns |

• The value as a number or nil.

|

trim

Signature	cp.tools.trim(string) -> string
Type	Function
Description	Trims the whitespaces from a string
Parameters	string - the string you want to trim
Returns	A trimmed string

unescape

Signature	cp.tools.unescape(str) -> string
Type	Function
Description	Removes any URL encoding in the provided string.
Parameters	str - the string to decode
Returns	A string with all "+" characters converted to spaces and all percent encoded sequences converted to their ASCII equivalents.

upper

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

urlQueryStringDecode

Signature	cp.tools.urlQueryStringDecode() -> string
Type	Function
Description	Decodes a URL Query String
Parameters	None
Returns	Decoded URL Query String as string

volumeFormat

Signature	cp.tools.volumeFormat(path) -> string
Type	Function
Description	Gives you the file system volume format of a path.
Parameters	path - the path you want to check as a string
Returns	The NSURLVolumeLocalizedFormatDescriptionKey as a string, otherwise nil.

writeToFile

Signature	cp.tools.writeToFile(path, data) -> none
Type	Function
Description	Write data to a file at a given path.
Parameters	path - The path to the file you want to write to. data - The data to write to the file.
Returns	None

Methods

escapeTilda

Signature	cp.tools.escapeTilda(input) -> none
Type	Method
Description	Escapes a tilda.
Parameters	input - The string you want to escape.
Returns	A new string

keyStroke

Signature	cp.tools.keyStroke(modifiers, character, app) -> none
Type	Method
Description	Generates and emits a single keystroke event pair for the supplied keyboard
Parameters	modifiers - A table containing the keyboard modifiers to apply ("fn", "ctrl", "alt", "cmd" or "shift") character - A string containing a character to be emitted app - The optional hs.application you want to target
Returns	None

pressSystemKey

Signature	cp.tools.pressSystemKey(key) -> none
Type	Method
Description	Virtually presses a system key.
Parameters	key - The key to use.
Returns	Supported key values are: SOUND_UP SOUND_DOWN MUTE BRIGHTNESS_UP BRIGHTNESS_DOWN CONTRAST_UP CONTRAST_DOWN POWER LAUNCH_PANEL VIDMIRROR PLAY EJECT NEXT PREVIOUS FAST REWIND ILLUMINATION_UP ILLUMINATION_DOWN ILLUMINATION_TOGGLE CAPS_LOCK HELP NUM_LOCK