cp.tools

A collection of handy miscellaneous tools for Lua development.

API Overview

Functions - API calls offered directly by the extension

  • appleScriptViaTask
  • between
  • camelCase
  • centre
  • characterToPercentEncodedString
  • cleanupButtonText
  • contentsInsideBrackets
  • convertSingleHexStringToDecimalString
  • desktopPath
  • dirFiles
  • doesDirectoryExist
  • doesFileExist
  • doubleLeftClick
  • encodeURI
  • encodeURIComponent
  • endsWith
  • ensureDirectoryExists
  • escapeTilda
  • exactMatch
  • executeWithAdministratorPrivileges
  • fileLinesBackward
  • findCommonWordWithinTwoStrings
  • firstToUpper
  • getEmail
  • getExternalDevices
  • getFileExtensionFromPath
  • getFilenameFromPath
  • getFullname
  • getKeysSortedByValue
  • getmacOSVersion
  • getModelName
  • getRAMSize
  • getScreenshotsAsBase64
  • getThunderboltDevices
  • getUSBDevices
  • getVRAMSize
  • hexStringToString
  • iconFallback
  • incrementFilename
  • incrementFilenameInPath
  • isColor
  • isImage
  • isNumberString
  • isOffScreen
  • keyStroke
  • leftClick
  • lines
  • lower
  • macOSVersion
  • mergeTable
  • ninjaDoubleClick
  • ninjaMouseAction
  • ninjaMouseClick
  • ninjaRightMouseClick
  • numberToWord
  • optionPressed
  • playErrorSound
  • pressSystemKey
  • readFromFile
  • removeFilenameFromPath
  • removeFromTable
  • replace
  • rescale
  • rightClick
  • rmdir
  • round
  • safeFilename
  • secureInputApplicationTitle
  • shiftPressed
  • spairs
  • split
  • splitOnColumn
  • startsWith
  • stringMaxLength
  • stringToHexString
  • tableContains
  • tableCount
  • tableFilter
  • tableMatch
  • toRegionalNumber
  • toRegionalNumberString
  • trim
  • unescape
  • upper
  • urlQueryStringDecode
  • urlToFilename
  • volumeFormat
  • writeToFile

API Documentation

Functions

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
  • None
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 203

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
  • A boolean
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 188

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 2162

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 1655

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
  • A string
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 2505

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 1966

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

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 2314

desktopPath

   
Signature cp.tools.desktopPath() -> string
Type Function
Description Gets the users Desktop Path
Parameters
  • None
Returns
  • The path as a string.
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 112

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.
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 2041

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

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 1512

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 1706

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
  • A string
Notes
  • Except these characters: ; , / ? : @ & = + $ # alphabetic, decimal digits, - _ . ! ~' ( )
Examples None
Source src/extensions/cp/tools/init.lua line 2518

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
  • A string
Notes
  • Except these characters: alphabetic, decimal digits, - _ . ! ~' ( )
Examples None
Source src/extensions/cp/tools/init.lua line 2534

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 2214

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

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

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

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

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
  • An iterator function
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

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

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 2182

getEmail

   
Signature cp.tools.getEmail() -> string
Type Function
Description Returns the current users Email, otherwise an empty string.
Parameters
  • None
Returns
  • String
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 1313

getExternalDevices

   
Signature cp.tools.getExternalDevices() -> string
Type Function
Description Returns a string of USB & Thunderbolt Devices.
Parameters
  • None
Returns
  • String
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 1282

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.
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 1913

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

getFullname

   
Signature cp.tools.getFullname() -> string
Type Function
Description Returns the current users Full Name, otherwise an empty string.
Parameters
  • None
Returns
  • String
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 1295

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 501

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.
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 950

getModelName

   
Signature cp.tools.getModelName() -> string
Type Function
Description Returns Model Name of Hardware.
Parameters
  • None
Returns
  • String
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 743

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.
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 710

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.
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 1361

getThunderboltDevices

   
Signature cp.tools.getThunderboltDevices() -> string
Type Function
Description Returns a string of Thunderbolt Devices.
Parameters
  • None
Returns
  • String
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 1235

getUSBDevices

   
Signature cp.tools.getUSBDevices() -> string
Type Function
Description Returns a string of USB Devices.
Parameters
  • None
Returns
  • String
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 1206

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 881

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 2407

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 2195

incrementFilename

   
Signature cp.tools.incrementFilename(value) -> string
Type Function
Description Increments the filename.
Parameters
  • value - A string
Returns
  • A string
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 1996

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 2015

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
  • A boolean
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 2492

isImage

   
Signature cp.tools.isImage(object) -> boolean
Type Function
Description Is the supplied object an hs.image?
Parameters
  • object - An object to check
Returns
  • A boolean
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 2479

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

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

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
  • None
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 268

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 1668

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

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 2147

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 1479

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 570

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 1758

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 1776

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 1722

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 1740

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 2108

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.
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 389

playErrorSound

   
Signature cp.tools.playErrorSound() -> none
Type Function
Description Plays the "Funk" error sound.
Parameters
  • None
Returns
  • None
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 2261

pressSystemKey

   
Signature cp.tools.pressSystemKey(key) -> none
Type Function
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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 335

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 423

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.
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 1929

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 1870

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
  • A new string
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 2445

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

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 1687

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

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 1386

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

secureInputApplicationTitle

   
Signature cp.tools.secureInputApplicationTitle() -> string
Type Function
Description Gets the title of the first application that has 'Secure Input' enabled.
Parameters
  • None
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

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.
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 371

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
  • Example Usage:
  • lua</li><li> for k,v in cp.tools.spairs(theTableToSort, function(t,a,b) return t[b] < t[a] end) do</li><li> print(k,v)</li><li> end</li><li>
Examples None
Source src/extensions/cp/tools/init.lua line 522

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 632

splitOnColumn

   
Signature cp.tools.splitOnColumn() -> string
Type Function
Description Splits a string on a column.
Parameters
  • Input
Returns
  • String
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 696

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

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
  • A string
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 1942

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 2390

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 1815

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

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.
Notes
  • This will modify the original table.
Examples None
Source src/extensions/cp/tools/init.lua line 1838

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

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

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

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 1525

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

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 2132

urlQueryStringDecode

   
Signature cp.tools.urlQueryStringDecode() -> string
Type Function
Description Decodes a URL Query String
Parameters
  • None
Returns
  • Decoded URL Query String as string
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 1346

urlToFilename

   
Signature cp.tools.urlToFilename(url) -> string
Type Function
Description Converts a URL to a filename.
Parameters
  • url - The URL.
Returns
  • The filename.
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 125

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

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
Notes None
Examples None
Source src/extensions/cp/tools/init.lua line 407

© Copyright 2026 LateNite Films Pty Ltd. All rights reserved.