# cp.tools
A collection of handy miscellaneous tools for Lua development.
---
## API Overview
**Functions** - _API calls offered directly by the extension_
* [appleScriptViaTask](#applescriptviatask)
* [between](#between)
* [camelCase](#camelcase)
* [centre](#centre)
* [characterToPercentEncodedString](#charactertopercentencodedstring)
* [cleanupButtonText](#cleanupbuttontext)
* [contentsInsideBrackets](#contentsinsidebrackets)
* [convertSingleHexStringToDecimalString](#convertsinglehexstringtodecimalstring)
* [desktopPath](#desktoppath)
* [dirFiles](#dirfiles)
* [doesDirectoryExist](#doesdirectoryexist)
* [doesFileExist](#doesfileexist)
* [doubleLeftClick](#doubleleftclick)
* [encodeURI](#encodeuri)
* [encodeURIComponent](#encodeuricomponent)
* [endsWith](#endswith)
* [ensureDirectoryExists](#ensuredirectoryexists)
* [escapeTilda](#escapetilda)
* [exactMatch](#exactmatch)
* [executeWithAdministratorPrivileges](#executewithadministratorprivileges)
* [fileLinesBackward](#filelinesbackward)
* [findCommonWordWithinTwoStrings](#findcommonwordwithintwostrings)
* [firstToUpper](#firsttoupper)
* [getEmail](#getemail)
* [getExternalDevices](#getexternaldevices)
* [getFileExtensionFromPath](#getfileextensionfrompath)
* [getFilenameFromPath](#getfilenamefrompath)
* [getFullname](#getfullname)
* [getKeysSortedByValue](#getkeyssortedbyvalue)
* [getmacOSVersion](#getmacosversion)
* [getModelName](#getmodelname)
* [getRAMSize](#getramsize)
* [getScreenshotsAsBase64](#getscreenshotsasbase64)
* [getThunderboltDevices](#getthunderboltdevices)
* [getUSBDevices](#getusbdevices)
* [getVRAMSize](#getvramsize)
* [hexStringToString](#hexstringtostring)
* [iconFallback](#iconfallback)
* [incrementFilename](#incrementfilename)
* [incrementFilenameInPath](#incrementfilenameinpath)
* [isColor](#iscolor)
* [isImage](#isimage)
* [isNumberString](#isnumberstring)
* [isOffScreen](#isoffscreen)
* [keyStroke](#keystroke)
* [leftClick](#leftclick)
* [lines](#lines)
* [lower](#lower)
* [macOSVersion](#macosversion)
* [mergeTable](#mergetable)
* [ninjaDoubleClick](#ninjadoubleclick)
* [ninjaMouseAction](#ninjamouseaction)
* [ninjaMouseClick](#ninjamouseclick)
* [ninjaRightMouseClick](#ninjarightmouseclick)
* [numberToWord](#numbertoword)
* [optionPressed](#optionpressed)
* [playErrorSound](#playerrorsound)
* [pressSystemKey](#presssystemkey)
* [readFromFile](#readfromfile)
* [removeFilenameFromPath](#removefilenamefrompath)
* [removeFromTable](#removefromtable)
* [replace](#replace)
* [rescale](#rescale)
* [rightClick](#rightclick)
* [rmdir](#rmdir)
* [round](#round)
* [safeFilename](#safefilename)
* [secureInputApplicationTitle](#secureinputapplicationtitle)
* [shiftPressed](#shiftpressed)
* [spairs](#spairs)
* [split](#split)
* [splitOnColumn](#splitoncolumn)
* [startsWith](#startswith)
* [stringMaxLength](#stringmaxlength)
* [stringToHexString](#stringtohexstring)
* [tableContains](#tablecontains)
* [tableCount](#tablecount)
* [tableFilter](#tablefilter)
* [tableMatch](#tablematch)
* [toRegionalNumber](#toregionalnumber)
* [toRegionalNumberString](#toregionalnumberstring)
* [trim](#trim)
* [unescape](#unescape)
* [upper](#upper)
* [urlQueryStringDecode](#urlquerystringdecode)
* [urlToFilename](#urltofilename)
* [volumeFormat](#volumeformat)
* [writeToFile](#writetofile)
---
## API Documentation
#### Functions
### [appleScriptViaTask](#applescriptviatask)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.appleScriptViaTask(script) -> none` |
| **Type** | Function |
| **Description** | Triggers an AppleScript command via `hs.task` to avoid potential memory leaks in `hs.osascript.applescript`. |
| **Parameters** | - script - A single line AppleScript.
|
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 203](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L203) |
---
### [between](#between)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.between(value, min, max) -> boolean` |
| **Type** | Function |
| **Description** | Is a value between the minimum and the maximum value? |
| **Parameters** | - value - the value to check
- min - the minimum value
- max - the maximum value
|
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 188](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L188) |
---
### [camelCase](#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** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 2162](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L2162) |
---
### [centre](#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** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1655](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1655) |
---
### [characterToPercentEncodedString](#charactertopercentencodedstring)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.characterToPercentEncodedString(input) -> string` |
| **Type** | Function |
| **Description** | Encodes a character as a percent encoded string. |
| **Parameters** | - input - The string to process
|
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 2505](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L2505) |
---
### [cleanupButtonText](#cleanupbuttontext)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.cleanupButtonText(value) -> string` |
| **Type** | Function |
| **Description** | Removes the … symbol and multiple >'s from a string. |
| **Parameters** | |
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1966](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1966) |
---
### [contentsInsideBrackets](#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`
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 2425](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L2425) |
---
### [convertSingleHexStringToDecimalString](#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** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 2314](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L2314) |
---
### [desktopPath](#desktoppath)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.desktopPath() -> string` |
| **Type** | Function |
| **Description** | Gets the users Desktop Path |
| **Parameters** | |
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 112](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L112) |
---
### [dirFiles](#dirfiles)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.dirFiles(path) -> table` |
| **Type** | Function |
| **Description** | Gets all the files in a directory |
| **Parameters** | |
| **Returns** | - A table containing filenames as strings, or `nil` followed by the error message if an error occurs.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 2041](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L2041) |
---
### [doesDirectoryExist](#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`
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1494](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1494) |
---
### [doesFileExist](#doesfileexist)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.doesFileExist(path) -> boolean` |
| **Type** | Function |
| **Description** | Returns whether or not a file exists. |
| **Parameters** | |
| **Returns** | - `true` if the file exists otherwise `false`
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1512](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1512) |
---
### [doubleLeftClick](#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** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1706](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1706) |
---
### [encodeURI](#encodeuri)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.encodeURI(input) -> string` |
| **Type** | Function |
| **Description** | Replaces all characters (except for those listed in the notes) with the appropriate UTF-8 escape sequences. |
| **Parameters** | - input - The string to process
|
| **Returns** | |
| **Notes** | - Except these characters: ; , / ? : @ & = + $ # alphabetic, decimal digits, - _ . ! ~' ( )
|
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 2518](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L2518) |
---
### [encodeURIComponent](#encodeuricomponent)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.encodeURIComponent(input) -> string` |
| **Type** | Function |
| **Description** | Escapes all characters (except for those listed in the notes) with the appropriate UTF-8 escape sequences. |
| **Parameters** | - input - The string to process
|
| **Returns** | |
| **Notes** | - Except these characters: alphabetic, decimal digits, - _ . ! ~' ( )
|
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 2534](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L2534) |
---
### [endsWith](#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** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 2214](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L2214) |
---
### [ensureDirectoryExists](#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. If it fails, `nil` is returned. |
| **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.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 2229](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L2229) |
---
### [escapeTilda](#escapetilda)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.escapeTilda(input) -> string` |
| **Type** | Function |
| **Description** | Escapes a tilda. |
| **Parameters** | - input - The string you want to escape.
|
| **Returns** | - A new string or "" if no input is supplied.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 255](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L255) |
---
### [exactMatch](#exactmatch)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.exactMatch(value, pattern, plain, ignoreCase) -> 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`.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 2366](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L2366) |
---
### [executeWithAdministratorPrivileges](#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.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1564](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1564) |
---
### [fileLinesBackward](#filelinesbackward)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.fileLinesBackward(filename) -> function` |
| **Type** | Function |
| **Description** | An iterator function that reads a file backwards. |
| **Parameters** | - filename - The file to open in read only mode
|
| **Returns** | |
| **Notes** | - This is similar to `io.lines`, but works in reverse.
- Example Usage: `for line in cp.tools.fileLinesBackward("file") do print(line) end`
|
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 142](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L142) |
---
### [findCommonWordWithinTwoStrings](#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.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 661](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L661) |
---
### [firstToUpper](#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** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 2182](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L2182) |
---
### [getEmail](#getemail)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.getEmail() -> string` |
| **Type** | Function |
| **Description** | Returns the current users Email, otherwise an empty string. |
| **Parameters** | |
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1313](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1313) |
---
### [getExternalDevices](#getexternaldevices)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.getExternalDevices() -> string` |
| **Type** | Function |
| **Description** | Returns a string of USB & Thunderbolt Devices. |
| **Parameters** | |
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1282](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1282) |
---
### [getFileExtensionFromPath](#getfileextensionfrompath)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.getFileExtensionFromPath(input) -> string` |
| **Type** | Function |
| **Description** | Gets the file extension from a path. |
| **Parameters** | |
| **Returns** | - A string of the file extension.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1913](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1913) |
---
### [getFilenameFromPath](#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.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1890](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1890) |
---
### [getFullname](#getfullname)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.getFullname() -> string` |
| **Type** | Function |
| **Description** | Returns the current users Full Name, otherwise an empty string. |
| **Parameters** | |
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1295](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1295) |
---
### [getKeysSortedByValue](#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** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 501](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L501) |
---
### [getmacOSVersion](#getmacosversion)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.getmacOSVersion() -> string` |
| **Type** | Function |
| **Description** | Returns the macOS Version in the format that Apple's Feedback Form expects. |
| **Parameters** | |
| **Returns** | - The macOS version as a string or "" if unknown.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 950](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L950) |
---
### [getModelName](#getmodelname)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.getModelName() -> string` |
| **Type** | Function |
| **Description** | Returns Model Name of Hardware. |
| **Parameters** | |
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 743](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L743) |
---
### [getRAMSize](#getramsize)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.getRAMSize() -> string` |
| **Type** | Function |
| **Description** | Returns RAM Size in a format Apple's Feedback form expects. |
| **Parameters** | |
| **Returns** | - The RAM size as a string, or "" if unknown.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 710](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L710) |
---
### [getScreenshotsAsBase64](#getscreenshotsasbase64)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.getScreenshotsAsBase64() -> table` |
| **Type** | Function |
| **Description** | Captures all available screens and saves them as base64 encodes in a table. |
| **Parameters** | |
| **Returns** | - A table containing base64 images of all available screens.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1361](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1361) |
---
### [getThunderboltDevices](#getthunderboltdevices)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.getThunderboltDevices() -> string` |
| **Type** | Function |
| **Description** | Returns a string of Thunderbolt Devices. |
| **Parameters** | |
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1235](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1235) |
---
### [getUSBDevices](#getusbdevices)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.getUSBDevices() -> string` |
| **Type** | Function |
| **Description** | Returns a string of USB Devices. |
| **Parameters** | |
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1206](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1206) |
---
### [getVRAMSize](#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** | |
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 881](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L881) |
---
### [hexStringToString](#hexstringtostring)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.hexStringToString(value) -> string` |
| **Type** | Function |
| **Description** | Converts a hex string to a string. |
| **Parameters** | - value - The string to convert
|
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 2407](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L2407) |
---
### [iconFallback](#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** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 2195](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L2195) |
---
### [incrementFilename](#incrementfilename)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.incrementFilename(value) -> string` |
| **Type** | Function |
| **Description** | Increments the filename. |
| **Parameters** | |
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1996](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1996) |
---
### [incrementFilenameInPath](#incrementfilenameinpath)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.incrementFilenameInPath(path) -> string` |
| **Type** | Function |
| **Description** | Increments the filename as it appears in a path. |
| **Parameters** | |
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 2015](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L2015) |
---
### [isColor](#iscolor)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.isColor(object) -> boolean` |
| **Type** | Function |
| **Description** | Is the supplied object an `hs.drawing.color`? |
| **Parameters** | - object - An object to check
|
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 2492](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L2492) |
---
### [isImage](#isimage)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.isImage(object) -> boolean` |
| **Type** | Function |
| **Description** | Is the supplied object an `hs.image`? |
| **Parameters** | - object - An object to check
|
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 2479](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L2479) |
---
### [isNumberString](#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`.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 683](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L683) |
---
### [isOffScreen](#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`
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1401](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1401) |
---
### [keyStroke](#keystroke)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.keyStroke(modifiers, character, app, proper) -> none` |
| **Type** | Function |
| **Description** | Generates and emits a single keystroke event pair for the supplied keyboard modifiers and character to the application. |
| **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
- proper - Use the "proper" method as per Apple's documentation (defaults to `false`)
|
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 268](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L268) |
---
### [leftClick](#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** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1668](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1668) |
---
### [lines](#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.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1538](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1538) |
---
### [lower](#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** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 2147](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L2147) |
---
### [macOSVersion](#macosversion)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.macOSVersion() -> string` |
| **Type** | Function |
| **Description** | Returns a the macOS Version as a single string. |
| **Parameters** | |
| **Returns** | - A string containing the macOS version
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1479](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1479) |
---
### [mergeTable](#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** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 570](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L570) |
---
### [ninjaDoubleClick](#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** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1758](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1758) |
---
### [ninjaMouseAction](#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** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1776](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1776) |
---
### [ninjaMouseClick](#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** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1722](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1722) |
---
### [ninjaRightMouseClick](#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** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1740](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1740) |
---
### [numberToWord](#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** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 2108](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L2108) |
---
### [optionPressed](#optionpressed)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.optionPressed() -> boolean` |
| **Type** | Function |
| **Description** | Is the Option Key being pressed? |
| **Parameters** | |
| **Returns** | - `true` if the option key is being pressed, otherwise `false`.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 389](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L389) |
---
### [playErrorSound](#playerrorsound)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.playErrorSound() -> none` |
| **Type** | Function |
| **Description** | Plays the "Funk" error sound. |
| **Parameters** | |
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 2261](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L2261) |
---
### [pressSystemKey](#presssystemkey)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.pressSystemKey(key) -> none` |
| **Type** | Function |
| **Description** | Virtually presses a system key. |
| **Parameters** | |
| **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
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 335](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L335) |
---
### [readFromFile](#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** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 423](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L423) |
---
### [removeFilenameFromPath](#removefilenamefrompath)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.removeFilenameFromPath(string) -> string` |
| **Type** | Function |
| **Description** | Removes the filename from a path. |
| **Parameters** | |
| **Returns** | - A string of the path without the filename.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1929](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1929) |
---
### [removeFromTable](#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** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1870](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1870) |
---
### [replace](#replace)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.replace(textValue, old, new) -> string` |
| **Type** | Function |
| **Description** | A find and replace feature that doesn't use patterns. |
| **Parameters** | - textValue - 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** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 2445](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L2445) |
---
### [rescale](#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`.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 479](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L479) |
---
### [rightClick](#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** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1687](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1687) |
---
### [rmdir](#rmdir)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.rmdir(path[, recursive]) -> true | nil, err` |
| **Type** | Function |
| **Description** | Attempts to remove the directory at the specified path, optionally removing any contents recursively. |
| **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.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 2069](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L2069) |
---
### [round](#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** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1386](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1386) |
---
### [safeFilename](#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`.
|
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1425](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1425) |
---
### [secureInputApplicationTitle](#secureinputapplicationtitle)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.secureInputApplicationTitle() -> string` |
| **Type** | Function |
| **Description** | Gets the title of the first application that has 'Secure Input' enabled. |
| **Parameters** | |
| **Returns** | - The application title or `nil` if secure input is not enabled or failed to get a title.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 221](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L221) |
---
### [shiftPressed](#shiftpressed)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.shiftPressed() -> boolean` |
| **Type** | Function |
| **Description** | Is the Shift Key being pressed? |
| **Parameters** | |
| **Returns** | - `true` if the shift key is being pressed, otherwise `false`.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 371](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L371) |
---
### [spairs](#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** | |
| **Notes** | - Author: [Michal Kottman](https://stackoverflow.com/a/15706820)
- Example Usage:
- ```lua
- for k,v in cp.tools.spairs(theTableToSort, function(t,a,b) return t[b] < t[a] end) do
- print(k,v)
- end
- ```
|
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 522](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L522) |
---
### [split](#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** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 632](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L632) |
---
### [splitOnColumn](#splitoncolumn)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.splitOnColumn() -> string` |
| **Type** | Function |
| **Description** | Splits a string on a column. |
| **Parameters** | |
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 696](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L696) |
---
### [startsWith](#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`
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 2345](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L2345) |
---
### [stringMaxLength](#stringmaxlength)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.stringMaxLength(string, maxLength[, optionalEnd]) -> string` |
| **Type** | Function |
| **Description** | Trims a string based on a maximum length. |
| **Parameters** | - string - The string
- 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** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1942](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1942) |
---
### [stringToHexString](#stringtohexstring)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.stringToHexString(value) -> string` |
| **Type** | Function |
| **Description** | Converts a string to a hex string. |
| **Parameters** | - value - The string to convert
|
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 2390](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L2390) |
---
### [tableContains](#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** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1815](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1815) |
---
### [tableCount](#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.
|
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1793](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1793) |
---
### [tableFilter](#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** | |
| **Notes** | - This will modify the original table.
|
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1838](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1838) |
---
### [tableMatch](#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`.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 2274](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L2274) |
---
### [toRegionalNumber](#toregionalnumber)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.toRegionalNumber(value) -> number | nil` |
| **Type** | Function |
| **Description** | Takes a string and converts it into a number, with the correct regional decimal separator. |
| **Parameters** | - value - The value you want to process as a string.
|
| **Returns** | - The value as a number or `nil`.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 441](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L441) |
---
### [toRegionalNumberString](#toregionalnumberstring)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.toRegionalNumberString(value) -> string | nil` |
| **Type** | Function |
| **Description** | Takes a number and converts it into a string, with the correct regional decimal separator. |
| **Parameters** | - value - The value you want to process as a number.
|
| **Returns** | - The value as a number or `nil`.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 460](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L460) |
---
### [trim](#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** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1525](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1525) |
---
### [unescape](#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.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 619](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L619) |
---
### [upper](#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** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 2132](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L2132) |
---
### [urlQueryStringDecode](#urlquerystringdecode)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.urlQueryStringDecode() -> string` |
| **Type** | Function |
| **Description** | Decodes a URL Query String |
| **Parameters** | |
| **Returns** | - Decoded URL Query String as string
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 1346](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L1346) |
---
### [urlToFilename](#urltofilename)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.tools.urlToFilename(url) -> string` |
| **Type** | Function |
| **Description** | Converts a URL to a filename. |
| **Parameters** | |
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 125](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L125) |
---
### [volumeFormat](#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`.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 600](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L600) |
---
### [writeToFile](#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** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/tools/init.lua line 407](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/tools/init.lua#L407) |
---
---