#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