Phonebot developer's reference/Script language

Operators and literals

Operator	Description
+ - * /	Numeric
&	String concatenation
== != < <= > >=	Comparison
! && ||	Boolean

Strings:

"Delimited by double quotes."
"Allow \"special characters\" with escape sequences.\nA new line."

--see Characters listing valid escape sequences

Numbers (integers and floating-point):

0 1 2 3.14 9.9999

Boolean keywords:

true false

Variables and basic types

Variables are created the first time they are referenced. The first reference must be a write action as opposed to a read action. The first two lines are valid and the third is not:

temp1 = "New variable."
control1.text = temp1
control1.text = temp2 /* invalid: temp2 was never initialized */

Variables are dynamically typed and so can hold a value for any intrinsic data type. All below are valid:

temp1 = "New variable."
temp1 = 12 / 4
temp1 = 12.0 / 5.0                /* temp1 = 2.4 */
temp1 = "Result is: " & (12 / 4)  /* temp1 = "Result is: 3" */
temp1 = (12 / 4) + "9"            /* temp1 = 12 */
temp1 = false
temp1 = (12 / 4) == 3             /* temp1 = true */

The intrinsic data types are:

Intrinsic type name	Description
integer	No decimal places
double	Floating-point
string	Double-quote delimited
boolean	true or false, non-empty strings and non-zero numbers evaluated as true

Coersion to boolean can be used as a shorthand to test if values are present:

if (name)
    // the variable contains data
end

if (values:array.size)
    // the array contains items
end

Complex types

Variables can be coerced into different types. This means that a variable must be told it's a specific type in order to use the type's properties and methods. The second and third lines below show the variable temp1 being coerced into a database type:

temp1 = application1.get_database("contacts")
db_size = temp1:database.size
new_record = temp1:database.add_record()

The coercible types are:

Coercible type name	Description
array	A collection of values
database	A persistent data store
datetime	A date and time
file	A file or folder
json	Data formatted as a JSON data structure
map	A collection of associated values
number	An integer or double
record	A collection of related data from a database
string	Double-quote delimited
xml	Data formatted as XML

Use uncoerced variables to access the intrinsic value of the variable. A variable must be coerced to a type in order to use the type's properties and methods.

temp1 = "A string value."
temp2 = temp1              /* copy the intrinsic value, temp2 = "A string value." */
temp2 = temp1:string.size  /* coerce to access the string size, temp2 = 15 */

Scope

Variables are defined within a specific scope. A variable's scope determines where it can be accessed.

Scope	Description
Local	Visible only within the current script.
Module	Visible within any events on the module and any events on controls within the module.
Application	Visible within any events on the application and any events across all modules, controls, and services.

By default, variables are in local scope and can only be accessed from the event where they are defined. Variables in module and application scope can be used to pass data between scripts. For example, a button's OnClick event could set the value of a module variable, and a different button's OnClick event could read that value to perform a calculation. Similarly, a module could store the value of an edit control within an application variable, and a different module could read that value to display in a label.

The following script illustrates the syntax for the three scope levels:

temp1 = "local scope"
edit1.text = temp1
module1.temp1 = "module scope"
edit1.text = module1.temp1
application1.temp1 = "application scope"
edit1.text = application1.temp1

temp1 can be referenced only within the current script. module1.temp1 can be referenced within any script within the module and will retain the last value set. application1.temp1 can be referenced within any script within the application and will retain the last value set.

Visual and container types

Visual and container objects are anything that the user interacts with. Visual types include items such as buttons and edit controls; container types consist of modules and applications. Visual types are also called controls.

Container type	Description
Application	Contains modules and databases
Module	Contains controls

Visual type/Control	Description
Button	Responds to a user click
Check box	Displayed as checked or unchecked
Drop down list
Edit box	Accepts typed text
Image	Displays an image
Label	Displays a message
List	Contains a vertical list of text
Radio button	Grouped in two or more to offer a single selection

Note: In computer science, type, class, and object all have specific definitions. Here, they will be used in the following more general sense:

• Type - A distinct data item with specific characteristics. Integers, strings, databases, and edit boxes are all types. Some types may share characteristics: both edit boxes and labels can display text. Others have unique characteristics: integers can be added together but databases cannot.
• Object - An object is an instance of a type. A specific integer object may equal 5 and because it is an integer type, it can be added to another integer. A specific label object may have its text property set to Hello, world!.

In addition to properties and methods, visual and container types have events. Events can contain script to be executed when something happens to the object. Visual types have OnClick. Container types have OnOpen, OnClose, and OnService.

The this keywords

Within an event, the object whose event is being fired can be referred to by its name or with the special keyword this. this enables you to copy the same code to different objects' events and have it perform the same.

/* in button1.on_click, updates button1 */
this.text = "clicked!"

/* in button2.on_click, updates button2 */
this.text = "clicked!"

this can be used within any object's events including those of applications, services, modules, and controls. In addition, thisapp can be used as a synonym for the currently running application, and thismod can be used for the currently loaded module. These are useful if you want to copy a module from one application to another.

The previous example showing scoped variables could be rewritten as follows:

temp1 = "local scope"
edit1.text = temp1
thismod.temp1 = "module scope"
edit1.text = thismod.temp1
thisapp.temp1 = "application scope"
edit1.text = thisapp.temp1

Object name collisions

Object names are restricted to avoid duplicates based on where they are contained.

• Application names must be unique across all other applications.
• Within an application, module names must be different than the application name, and unique across other modules and services.
• Within an application, service names must be different than the application name, and unique across modules and other services.
• Within a module, control names must be different than the application and module names, and unique across other controls.

	Applications	Modules	Services	Controls
Application	X
Module	X	X	X
Service	X	X	X
Control	X	X	X	X

Control structures

Assignments copy one value to a variable or object property. The right-hand side of assignments can use variables, object properties, literals, or complex expressions.

temp1 = temp2 /* assumes temp2 was defined elsewhere */
temp1 = application1.name
temp1 = 5
temp1 = (12 / 4) * temp2

Methods take zero or more arguments and request an object to perform an action. A method may return a value or object as a result.

application1.open_module("module1")
db = application1.get_database("contacts")   /* store the database into a variable */
db_size = db:database.size                   /* coerce db into a database object and store the size */

Phonebot Plus also provides user-defined methods.

Conditionals test one or more expressions and process a block of script based on the first test that returned true.

if (temp1 < 0)
    msg = "Negative number"
elseif (temp1 == 0)
    msg = "Zero"
elseif (temp1 < 10)
    msg = "Positive number, less than 10"
else
    msg = "Positive number, 10 or greater"
end

Loops process a block of script zero or more times based on the value of a counter.

msg = "List of numbers zero through nine: "
for (index = 0; index < 10; index = index + 1)
    msg = msg & " " & index
end

Comments

Both C-style block comments and C++ style inline comments:

/* Test for:
   zero
   one
*/
if (x == 0 || x == 1)
    // Display results
    edit.text = "Success!"
end