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
• cleanupButtonText
• doesDirectoryExist
• doesFileExist
• doubleLeftClick
• executeWithAdministratorPrivileges
• getEmail
• getExternalDevices
• getFilenameFromPath
• getFullname
• getmacOSVersion
• getModelName
• getRAMSize
• getScreenshotsAsBase64
• getThunderboltDevices
• getUSBDevices
• getVRAMSize
• iconFallback
• incrementFilename
• isOffScreen
• leftClick
• lines
• macOSVersion
• mergeTable
• modifierMaskToModifiers
• modifierMatch
• ninjaDoubleClick
• ninjaMouseAction
• ninjaMouseClick
• numberToWord
• removeFilenameFromPath
• removeFromTable
• rmdir
• round
• safeFilename
• split
• splitOnColumn
• stringMaxLength
• tableContains
• tableCount
• trim
• unescape
• urlQueryStringDecode
• volumeFormat

API Documentation

Functions

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

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

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.

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

getFilenameFromPath

Signature	cp.tools.getFilenameFromPath(input) -> string
Type	Function
Description	Gets the filename component of a path.
Parameters	input - The path
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

getmacOSVersion

Signature	cp.tools.getmacOSVersion() -> string
Type	Function
Description	Returns macOS Version.
Parameters	None
Returns	String

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.
Parameters	None
Returns	String

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

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	Returns a table of file names for the given path.
Parameters	path - A path as string
Returns	A table containing filenames as strings.

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
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

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	Gives you the file system volume format of a path.
Parameters	target - The target table ... - Any other tables you want to merge into target
Returns	Table

modifierMaskToModifiers

Signature	cp.tools.modifierMaskToModifiers() -> table
Type	Function
Description	Translate Keyboard Modifiers from Apple's Plist Format into Hammerspoon Format
Parameters	value - Modifiers String
Returns	table

modifierMatch

Signature	cp.tools.modifierMatch(inputA, inputB) -> boolean
Type	Function
Description	Compares two modifier tables.
Parameters	inputA - table of modifiers inputB - table of modifiers
Returns	true if there's a match otherwise false
Notes	This function only takes into account 'ctrl', 'alt', 'cmd', 'shift'.

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

numberToWord

Signature	cp.tools.numberToWord(str) -> string
Type	Function
Description	Makes the first letter of a string uppercase.
Parameters	str - The string you want to manipulate
Returns	A string

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

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.

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

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

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.

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.

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.