docs » cp.tools


A collection of handy miscellaneous tools for Lua development.

API Overview

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

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.

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` </span>
Type Function
Description Ensures all steps on a provided path exist. If not, attempts to create them.
Parameters
  • rootPath - The root path (should already exist).
  • ... - 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.

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.

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

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

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

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` </span>
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.

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

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

playErrorSound

Signature cp.tools.playErrorSound() -> none
Type Function
Description Plays the "Funk" error sound.
Parameters
  • None
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

rmdir

Signature `cp.tools.rmdir(path[, recursive]) -> true nil, err` </span>
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.

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

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.

results matching ""

    No results matching ""