Functions+ Help Document

Requires latest version (v3.5.3+) - Made by /u/shirtandtieler

My motivation in creating this library was wanting to create a way to seamlessly integrate custom 
functions with AutoTouch. After many hours of hard work, I have created a whole spectrum of different 
useful functions. If you're familiar with Python, any similar naming conventions are no coincidence :)

Enjoy! (And contact me on reddit if you have any questions/problems/suggestions)

Contents

1. FAQs
2. Functions
   1. Checks / Logic
      1. getActiveApp
      2. isBool
      3. isNil
      4. isNotNil
      5. isNum
      6. isStr
      7. isTable
      8. isin
      9. isnotin
      10. string.startswith
      11. string.endswith
      12. tblsEqual
   2. Variable Modifiers
      1. deepcopy
      2. join
      3. merge
      4. string.format
      5. string.replace
      6. string.split
      7. string.trim
   3. Math
      1. count
      2. div
      3. len
      4. round
   4. File System
      1. copyFile
      2. fileExists
      3. formatLog
      4. getDir
      5. getFileSize
      6. getLine
      7. getLines
      8. replaceInFile
      9. search
   5. Action
      1. clear
      2. draw
      3. exe
      4. help
      5. pause
      6. print
      7. pprint
      8. scroll
   6. Conversion
   1. eval
   2. str
   3. num
   4. hexToInt
   5. hexToName
   6. hexToRgb
   7. intToHex
   8. intToName
   9. rgbToHex
   10. rgbToName
3. xToName Color Scheme Options

Back to top 

FAQs

 name = " shirtANDtieler!? " 

Functions

Back to top 

getActiveApp()

Gets the AppID of the currently active app

Parameters

Return values

Example(s)

-- while in the AutoTouch app
log(getActiveApp())
-- prints 'me.autotouch.AutoTouch.ios8' to the log

Back to top 

isBool(input)

Checks if the input is a boolean

Parameters

Return values

Example(s)

t = true
f = false
if isBool(t) and isBool(f) then
  log("Both variables are booleans!") -- gets logged
end

Back to top 

isNil(input)

Checks if the input is nil (a.k.a. null, None, nothing, etc.)

Parameters

Return values

Example(s)

-- example function that doesn't return anything
function test(x, y)
  local z = x + y
end
set2nil = test(1, 2)
if isNil(set2nil) then
  log("The test function returned nil!") -- gets logged
else
  log("The test function has a return value!") -- does NOT get logged
end

Back to top 

isNotNil(input)

Checks if the input is not nil

Parameters

Return values

Example(s)

-- example function that doesn't return anything
function test(x, y)
  local z = x + y
end
set2nil = test(1, 2)
if isNotNil(set2nil) then
  log("The test function has a return value!") -- does NOT get logged
else
  log("The test function returned nil!") -- gets logged
end

Back to top 

isNum(input)

Checks if the input is a number

Parameters

Return values

Example(s)

integer = 3
float = 3.14159
hexadecimal = 0xbadb07
if isNum(integer) and isNum(float) and isNum(hexadecimal) then
  log("All 3 variables are numbers!") -- gets logged
end

Back to top 

isStr(input)

Checks if the input is a string (i.e. text)

Parameters

Return values

Example(s)

objects = {0xca7d0e, "fat horse"}
if isStr(objects[1]) then
  log(objects[1] .. " is a string.") -- does NOT get logged
elseif isStr(objects[2]) then
  log(objects[2] .. " is a string!") -- gets logged
end

Back to top 

isTable(input)

Checks if the input is a table (a.k.a. array, list)

Parameters

Return values

Example(s)

realTable = {1, false, "hello!"}
stringTable = "{true, 'ohai', 66}"
if isTable(realTable) then
  log("realTable is a real table!") -- gets logged
end
if isTable(stringTable) then
  log("stringTable isn't a table, it's a string!") -- also gets logged
end

Back to top 

isin(x,y)

Checks if x is a substring or subelement of y

Parameters

Return values

Example(s)

-- Example 1: (String, String)
if isin("o", "AutoTouch") then
  log("There's an 'o' in 'AutoTouch!")
  -- since there is an 'o' in the word 'AutoTouch', this gets logged
end
-- Example 2: (String, Table)
itemToCheck = "baby"
pets = {"dog", "cat", "bird"}
if isin(itemToCheck, animals) then
  log("A baby is a pet too!")
  -- since "baby" is not in the table, this does NOT get logged
end

Back to top 

isnotin(x,y)

The inverse of 'isin' - made as an easier way to type than 'not isin(,)'

Parameters

Return values

Example(s)

-- Example 1: (Number, String)
birth_year = 1992
birthday = "My birthday falls on August 14th"
if isnotin(birth_year, birthday) then
  log("No details on the birth year in the birthday description text!")
  -- gets logged since the string '1992' is nowhere in the description
end

Back to top 

string.startswith(input, starts)

A check to see if a string starts with a certain string

Parameters

Return values

Example(s)

diss = "You are so dumb that your dog teaches you tricks."
if string.startswith(diss, "Yo mama") then
  log("You just got schooled by a yo-mama diss!")
elseif diss:startswith("You") then
  log("You just got schooled with a diss on you!")
  -- this is what gets logged
else
  log("Some other diss was made")
end

Back to top 

string.endswith(input, ends)

A check to see if a string ends with a certain string

Parameters

Return values

Example(s)

diss = "You are so dumb that your dog teaches you tricks."
if string.endswith(diss, "Yo mama") then
  log("You just got schooled by a yo-mama diss!")
elseif diss:endswith("You") then
  log("You just got schooled with a diss on you!")
  -- this is what gets logged
else
  log("Some other diss was made")
end

Back to top 

tblsEqual(t1, t2)

Checks (recursively) if the two given tables are the same - Order of the given tables does not matter

Parameters

Return values

Example(s)

someRandomStuff = {1, "potato", {"jk", "!!!", 5}}
sameRandomStuff = {"potato", {"jk", "!!!", 5}, 1}
areSame = tblsEqual(someRandomStuff, moreRandomStuff)
if areSame then
  log("They're the same!") -- this gets logged as order of elements does not matter
end

Back to top 

deepycopy(orig)

Recursively copies/duplicates the given table so that it is separate and independent from the original

Parameters

Return values

Example(s)

origTable = {1, "dog", {false, "cat"}}
fakeCopy = origTable
dupdCopy = deepcopy(origTable)
-- to show the difference between the 'fakeCopy' and the 'dupdCopy'...
origTable[3][1] = true -- changes the first item of the third item (i.e. false)
print(origTable) -- logs: {1, "dog", {true, "cat"}}
print(fakeCopy)  -- logs: {1, "dog", {true, "cat"}} -- setting one variable equal to another simply makes a link
print(dupdCopy)  -- logs: {1, "dog", {false, "cat"}} -- whereas a deep copy remains separate/independent

Back to top 

join(...)

Concatenates folder/file paths using proper formatting

Parameters

Return values

Example(s)

FuncPlus_File = join(rootDir(), "Functions+.lua")
-- FuncPlus_File == "/var/mobile/Library/AutoTouch/Scripts/Functions+.lua"
random_Image = join("var/", "/mobile/", "/Media", "DCIM", "100APPLE", "/IMG_2011.PNG")
-- random_Image == "/var/mobile/Media/DCIM/100APPLE/IMG_2011.PNG"

Back to top 

merge(...)

Merges the objects into one table (if custom keys are used in inputted tables, the later items will take precendence)

Parameters

Return values

Example(s)

two_letter_words = {"by", "if", "up"}
three_letter_words = {"can", "how", "you"}
X_letter_words = merge(two_letter_words, three_letter_words, "touch")
-- X_letter_words == {"by", "if", "up", "can", "how", "you", "touch"}
-- map letters of words to their position in the word
hello = {["h"]=1, ["e"]=2, ["l"]={3,4}, ["o"]=5}
world = {["w"]=1, ["o"]=2, ["r"]=3, ["l"]=4, ["d"]=5}
greeting = merge(hello, world)
-- greeting == {["h"]=1, ["e"]=2, ["l"]=4, ["o"]=2, ["w"]=1, ["r"]=3, ["d"]=5}
--  note that the "l" and "o" keys from  were replaced by the indicies of the letters in 

Back to top 

string.format(input, ...)

An easier way to format a string than to use Lua's string.format function

Parameters

Return values

Example(s)

fav_fruit = "mango"
fav_vegi = "artichoke"
fav_candy = "KitKat"
intro = string.format("My favorite fruit is the {}, favorite vegi is the {}, and favorite candy is {}", fav_fruit, fav_vegi, fav_candy)
-- intro == "My favorite fruit is the mango, favorite vegi is the artichoke, and favorite candy is KitKat"
madlib = "'There are too many {} {} on this {} plane!', he screamed."
verb_endIn_ing = "flip flopping"
plural_noun = "fishes"
adj = "drunk"
madlib = madlib:format(verb_endIn_ing, plural_noun, adj)
-- madlib == "'There are too many flip flopping fishes on this drunk plane!', he screamed."

Back to top 

string.replace(input, before, after, limit)

Replaces any occurances of a substring within a string

Parameters

Return values

Example(s)

tongue_twister = "peter piper picked a peck of pickled peppers"
new_tongue_twister = string.replace(tongue_twister, "p", "shm")
-- new_tongue_twister == "shmeter shmiper shmicked a shmeck of shmickled shmeppers"
incorrect = "Young man, your going to keep your room clean, or else you're grounded!"
correct = incorrect:replace("your", "you're", 1)
-- correct == "Young man, you're going to keep your room clean, or else you're grounded!"

Back to top 

string.split(input, delim, autoNum)

Splits a string into a table

Parameters

Return values

Example(s)

drinks = 'tea, coffee, water, beer'
drinks_table = string.split(drinks, ", ") -- autoNum is optional
-- drinks_table == {"tea", "coffee", "water", "beer"}
grocery_list = "5 apples 2 oranges 8 bananas 1 mango"
grocery_table = grocery_list:split(" ", true)
-- grocery_table == {5, "apples", 2, "oranges", 8, "bananas", 1, "mango"}
hello = "Hello"
helloTable = hello:split()
-- helloTable == {"H", "e", "l", "l", "o"}

Back to top 

string.trim(input)

Removes any whitespace around of a string

Parameters

Return values

Example(s)

code = "    if x then y"
trimmedCode = string.trim(code)
-- trimmedCode == "if x then y"
title = " [    HELLO    ] "
trimmedTitle = title:trim()
-- trimmedTitle == "[    HELLO    ]"

Back to top 

count(value, input)

Counts the number of occurances that appear in an object

Parameters

Return values

Example(s)

-- Example 1: (String, String)
letter = "o"
word = "AutoTouch"
numOs = count(letter, word)
-- numOs is set to 2, as there are two 'o's in the word 'AutoTouch'
-- Example 2: (String, Table)
drink = "Bleach"
drinksHadToday = {"vodka", "water", "vodka", "coca-cola", "vodka"}
poisonsConsumed = count(drink, drinksHadToday)
 -- set to 0, as no bleach was drunken (at least for today)

Back to top 

div(d1, d2)

Does floor division on the two values

Parameters

Return values

Example(s)

div(10, 2) -- results in 5
div(11, 2) -- also results in 5

Back to top 

len(input)

Gets the length or size of an object

Parameters

Return values

Example(s)

-- in Lua, you can use # before a table name to get its length
--   however, this doesn't work if the indices are non-numbers
--   as you'll see below, this function doesn't have that problem
partOfBody = {["eyes"]="head", ["thumb"]="hand", ["butt"]="legs"}
log(#partOfBody) -- logs 0, which is wrong
log(len(partOfBody)) -- logs 3, which is correct
item = "potato"
log(len(item)) -- logs 6

Back to top 

round(num, places)

Rounds a number to specified number of places

Parameters

Return values

Example(s)

pi = round(math.pi, 2)
  -- pi == 3.14
e = round(2.71828, 0)
  -- e == 3

Back to top 

copyFile(srcFilePath, dstFilePath, overwrite)

Copies a file from one location to another

Parameters

Return values

Example(s)

copyFile("/var/mobile/Downloads/script1.lua", "script1.lua")
-- copies the "script1.lua" file to the AutoTouch scripts directory
-- since  was not given, it is set to false by default

Back to top 

fileExists(file)

Checks if a certain file or folder exists

Parameters

Return values

Example(s)

if fileExists("/var/mobile/Library/AutoTouch/Library/log.log") then
  log("The log exists!") -- which it does, so this gets printed to the log
end
if fileExists("/var/mobile/fakeFolder") then
  log("This should not get logged....")
else
  log("Fake folder is fake!") -- this is what gets printed to the log
end

Back to top 

formatLog(option, value)

Formats the log for easier viewing 
Note: You only have to run this once. After that, anything added to the log will be in the 
specified format.
If you want it to go back to the default settings, run the function with no parameters (this will apply to anything logged after reverting it)

Parameters

Return values

Example(s)

-- log.log
--[[
02-11 12:18:44 Testing 1, 2, 3 ....
02-11 12:19:00 Did this pause for 16 seconds?
02-11 14:56:36 Script ran successfully!
--]]
editLog('p', '>')
editLog('s', '*')
-- log.log
--[[
> Testing 1, 2, 3 ....
* * * * * * * * * * * * * * * * * * * *
> Did this pause for 16 seconds?
* * * * * * * * * * * * * * * * * * * *
> Script ran successfully!
--]]

Back to top 

getDir(dir)

Gets all the folders/files in specific directory

Parameters

Return values

Example(s)

AT_Library_Files = getDir("/var/mobile/Library/AutoTouch/Library") -- the last slash is optional
print(AT_Library_Files)
-- prints "{'data.sqlite3', 'license', 'log.log'}" to the log

Back to top 

getFileSize(fileName)

Gets the size of the specified file

Parameters

Return values

Example(s)

oneKB = getFileSize("oneKilobyteFile.lua")
-- oneKB == 1024

Back to top 

getLine(file, lineNum)

Similar to getLines, but just gets one specified line

Parameters

Return values

Example(s)

-- mySecrets.txt (located in /var/mobile/Documents/)
--[[
I have 6 toes
Crosswords make me horny
I ate dog food once out of curiosity
--]]
secret_crosswords = getLine("/var/mobile/Documents/mySecrets.txt", 2)
print(secret_crosswords) -- prints "Crosswords make me horny" to the log

Back to top 

getLines(file)

Get the lines of a specified file

Parameters

Return values

Example(s)

-- Using the "mySecrets.txt" file in the getLine example....
secrets = getLines("/var/mobile/Documents/mySecrets.txt")
print(secrets)
-- prints "{'I have 6 toes', 'Crosswords make me horny', 'I ate dog food once out of curiosity'}" to the log

Back to top 

replaceInFile(file, before, after, limit, backup)

Replaces some text within a specified file

Parameters

Return values

Example(s)

-- example.lua (located in scripts directory)
  tap(100, 75)
  usleep(16000)
  tap(180, 200)
  usleep(16000)
replaceInFile("example.lua", "16000", "32000", 0, false)
-- example.lua now looks like:
  tap(100, 75)
  usleep(32000)
  tap(180, 200)
  usleep(32000)
-- and does not create a backup

Back to top 

search(file, query, startSearch, endSearch)

Searches a specified file for some text

Parameters

Return values

Example(s)

-- log.log
--[[
02-12 20:31:59 Script ran successfully!
02-12 20:32:00 Script ran successfully!
02-15 12:18:36 Script ran successfully!
02-22 17:09:03 Script failed to run!
02-26 0l:46:28 Script ran successfully!
--]]
entries_from_feb12 = search("/var/mobile/Library/AutoTouch/Library/log.log", "02-12")
print(entries_from_feb12)
-- prints "{{1,5}, {41, 45}}" to the log

Back to top 

clear()

Erases the AutoTouch log

Parameters

Return values

Example(s)

-- log.log
--[[
02-24 23:53:03 SUPER SECRET MESSAGE!!!
--]]
clear()
-- log.log
--[[
--]]

Back to top 

draw(shape, size, centerPos)

Draws a shape on the screen

Parameters

Return values

Example(s)

draw("circle", 20, {400, 400})
  -- draws a 20 pixel wide circle around x=400, y=400
width, height = getScreenResolution()
draw("square", width/4, {width/2, height/2})
  -- draws a square, with a length/width of a quarter of the width, around the center of the screen

Back to top 

exe(cmd)

Runs a specified command (Be careful when using!)

Parameters

Return values

Example(s)

ip = exe("ipconfig getifaddr en0")
  -- ip == the user's local IP address (if connected to wifi)
exe("cd /var/mobile/Downloads; mkdir YoutubeVideos")
  -- makes a folder called "YoutubeVideos" in the "/var/mobile/Downloads" folder

Back to top 

help(func)

Print to the log more information about a topic

Parameters

Return values

Example(s)

help() -- logs contact info and other general-info kind of stuff
help("functions") -- logs a list of functions
help("str") -- logs help about the function 'str'

Back to top 

pause(time, unit)

An easier way to use usleep without having to wonder if you've used enough 0s

Parameters

Return values

Example(s)

pause(1000000) -- pauses for 1 million microseconds, aka a second
pause(1, "s") -- also pauses for 1 second

Back to top 

print(...)

Implements Lua's print function while also adding in support for tables

Parameters

Return values

Example(s)

print("The following", 3, "objects were found on the deceased's body:",{"keys", "a used straw", "cucumber"})

Back to top 

pprint(tabl)

Pretty prints a table to the log using indents and formatting

Parameters

Return values

Example(s)

letters2nums = {["a"]=1, ["b"]=2, ["cde"]={3,4,5}, ["f"]=6}
pprint(letters2nums)
--[[ logs the following:
{
  ["a"] = 1,
  ["b"] = 2, 
  ["cde"] = {
    3, 
    4, 
    5
  }, 
  ["f"]=6
}
--]]

Back to top 

scroll(dir, speed, repeats)

Scrolls the screen in a cardinal direction

Parameters

Return values

Example(s)

scroll('d', 1)
  -- scrolls down (ie simulates a finger drag upwards) at a snail's pace, doing so one time

Back to top 

eval(input)

Evaluates the given input, converting it into code

Parameters

Return values

Example(s)

math_string = "8*3-10"
answer = eval(math_string)
log(answer) -- logs: 14
toEval = "beersDrank = 5" -- you can set a value to a variable within the string 
consumed = eval(toEval) -- now both consumed and beersDrank are equal to 5
log(consumed .. " / " .. beersDrank) -- logs: 5 / 5
toEval:replace("5", "6", 1) -- replacing stuff in the original string will effect the outcome
eval(toEval)
log(beersDrank) -- now logs: 6

---

Back to top 

str(input)

An improved version of Lua's "tostring" which allows you to turn any object into a string (good for printing to the log)

Parameters

Parameter	Type	Description
input	Any (String, Number, Boolean, Table, Nil)	The thing to be turned into a string

Return values

Type	Description
String	A string-ified version of input

Example(s)

log("Does " .. str(3) .. " * 2 == 6? " .. str(3*2==6))
-- logs "Does 3 * 2 == 6? true"
randomObjects = {"a", 14, false, "b", nil, true}
log(str(randomObjects))
-- logs "{'a', 14, false, 'b', nil, true}" 

---

Back to top 

num(input)

A shorter version of Lua's tonumber

Parameters

Parameter	Type	Description
input	String	The thing to be turned into a number

Return values

Type	Description
Number	A number-ified version of input

Example(s)

result = "5 is my answer"
answer = num(result:sub(1,2))
-- takes a substring of the first character to the second (doesn't include the second) and then converts it to a number
score = answer/5*100
log("Your answer is " .. str(score) .. "% correct!")
-- score == 100

---

Back to top 

hexToInt(hex)

Convert a hexadecimal color to its integer equivalent

Parameters

Parameter	Type	Description
hex	Number	The hex value, prefixed with "0x"

Return values

Type	Description
Number	The integer representation

Example(s)

{None currently given}

---

Back to top 

hexToName(hex, colorScheme)

Converts a color in hexadecimal to the closest matching name

Parameters

Parameter	Type	Description
hex	Number	The hexadecimal value, prefixed with "0x"
colorScheme	String	See this section for your options.

Return values

Type	Description
String	The closest matching name based on the inputs

Example(s)

{None currently given}

---

Back to top 

hexToRgb(hex)

Converts a hexadecimal to red, green, blue format

Parameters

Parameter	Type	Description
hex	Number	The hex value, prefixed by "0x"

Return values

Type	Description
Number	The number representation

Example(s)

{None currently given}

---

Back to top 

intToHex(int)

Converts an integer representation of a color to hexadecimal

Parameters

Parameter	Type	Description
int	Number	The integer color you want to be converted

Return values

Type	Description
String	A string of the hexidecimal value

Example(s)

{None currently given}

---

Back to top 

intToName(i, colorScheme)

Converts an integer color to its closest name

Parameters

Parameter	Type	Description
i	Number	The color in integer format that you want to convert
colorScheme	String	See this section for your options.

Return values

Type	Description
String	The closest matching name based on the input

Example(s)

{None currently given}

---

Back to top 

rgbToHex(r,g,b)

Converts a color in RGB format to its hexadecimal value

Parameters

Parameter	Type	Description
r, g, b	Numbers	The red, green, and blue values for the color; Note that I comressed these values into one row for simplicity. When calling the function, these values are separated

Return values

Type	Description
String	The hexadecimal equivalent

Example(s)

{None currently given}

---

Back to top 

rgbToName(r, g, b, colorScheme)

Converts a color in red, green, blue format to the closest matching name

Parameters

Parameter	Type	Description
r, g, b	Numbers	The red, green, and blue values
colorScheme	String	See this section for your options.

Return values

Type	Description
String	The closest matching color name based on the input

Example(s)

{None currently given}

---

Back to top 

xToName Color Scheme Options

For the xToName functions, the second parameter allows for a "colorScheme". Of the 4 choices for schemes, pick the one which suits your needs the best.

Below, I list a description of all 4 and your options for the "colorScheme" parameter.

Note that, for each of the color schemes, each level builds upon the previous; in addition, colors #1 takes 3 from grayscale, #2 takes 9 from grayscale, and #3 takes the remaining 7 from grayscale.

1. Grayscale - This scheme includes black and white, along with 19 shades of gray in between. Available options to use this scheme are:
• 0
• "gray"
• "grey"
2. Colors #1 - This scheme has 20 colors total (3 from previous + 17 new). Available options to use this scheme are:
• 1
• "small"
• "basic"
3. Colors #2 - This scheme has 59 colors total (20 from previous + 39 new). Available options to use this scheme are:
• 2
• "medium"
• "indepth"
4. Colors #3 - This scheme has 89 colors total (59 from previous + 30 new). Available options to use this scheme are:
• 3
• "large"
• "complete"