Comments

Users can insert comments anywhere in a script. Comments are not executed like regular code. Instead, they can be used for documentation or to temporarily disable blocks of code.

JavaScript supports two types of comments:

• Single-line comments start with // and end when the line ends.

• Block comments start with /* and end with */. These can extend across multiple lines, or can be used within a single line.

Example:

// This is a single-line comment
/* This is a
 * multi-line
 * comment.*/

This manual will use comments to indicate the result from pieces of code. For example:

1 + 2 // 3

indicates that the result of the expression 1 + 2 is 3.

Calling Functions

A function takes in some parameters and returns a value. This lets you re-use pieces of code without re-writing everything.

Functions can be executed by using the function name, followed by parentheses. Any arguments should be placed inside of the parentheses.

For example, the script below calls the function notification.send with the argument "Hello, world!":

notification.send("Hello, world!"); // brings up a notification saying "Hello, world!"

Some functions do not require any arguments:

system.exit(); // exits the runtime project

Other functions require multiple arguments. In this case, arguments should be separated by commas.

For example, tag.write takes two arguments. The first argument is the tag name, and the second argument is the value to write:

tag.write("myTag", true); writes the value true to the tag named "myTag"

Declaring Variables

Variables let you store values and access them later in the script.

Variable names must not contain spaces, and must begin with either a letter or an underscore _. Variable names are case-sensitive.

Variables can be declared using the following format:

var variableName;

To declare more than one variable, use a comma , between each variables:

var variable1, variable2, ... , variablen;

Users can also define an initial value for the variable when declaring it using the following format:

var variableName = 1;

If you do not specify an initial value, then the variable’s value is undefined.

A variable’s data type is determined automatically based on the value used to initialize it.

Using and Setting Variables

Once a variable has been declared, you can assign a new value to it using the assignment operator =. For example:

var a = 1; // a has value 1
a = 2;     // a now has value 2

Once a variable has a value, you can use the variable name to access that value. For example:

var tag_name = "myTag";
var value = 1;
tag.write(tagName, value);

This is the same as:

tag.write("myTag", 1);

Operators, Expressions, and Parentheses

You can add, subtract, multiply, and use other operators on variables and other values. See the “Operators” section for more information.

1 + 2;        // 3 (addition)
1 - 2;        // -1 (subtraction)
1 * 2;        // 2 (multiplication)
1 / 2;        // 0.5 (division)
1 == 2;       // false (equal to)
1 < 2;        // true (less than)
!true         // false (not)
true && false // false (logical and)
true || false // true (logical or)

Just like in mathematics, expressions can be combined and nested within each other. The values will be computed only when they are needed.
Parentheses can be used to group expressions together and to specify the order of operations. For example:

1 + (2 * 3)       // 7
(1 + 2) * 3       // 9
((1 + 2) * 3) - 4 // 5

You may also nest function calls:

tag.write("myTag", !tag.read("myTag")) // toggles the value of the tag named "myTag"

It is worth noting that the comparison operator == is different from the assignment operator =. The comparison operator == compares two values and returns true if they are equal, and returns false if they are not equal. The assignment operator = sets the variable on the left side to the value on the right side, and always returns assigned value. For example:

var x = 3;
x == 5; // false (because 3 does not equal 5)
x = 5;  // 5 (because 5 is the value being assigned)
x == 5; // true (because we set x to 5 in the line above)

Data Types

In JavaScript, every expression and variable has a data type. The most basic types are Boolean, Number, and String, which can be used to read and write tag values.

The type of a variable or expression is determined at runtime. If you attempt to use multiple data types in one expression, JavaScript will attempt to convert (coerce) the types so that they are compatible. Coercion can be useful, but it can sometimes lead to unexpected results. The programmer should always be mindful of what data types are expected for a given variable or expression.

Here are some examples of expressions and their types:

"asdf"  // string
123.456 // number
1       // number
true    // boolean
false   // boolean

Here are some examples of type coercion:

!1        // false
2 + true  // 3
"a" + "b" // "ab"
2 + "3"   // "23"
2 * "3"   // 6

You can use the typeof keyword to check the type of an expression:

var x = 3;
typeof x; // "number"

Strings, Quotes, and Escape Characters

Anything wrapped in either double quotes " or single quotes ' will be treated as a string value. For example, x without quotes would refer to the variable x. But "x" or 'x' would be a string with the value "x". For example:

var x = 3;
notification.send(x);   // 3
notification.send("x"); // x
notification.send('x'); // x

In order to use quotes or other special characters within a string, you must use the escape character \ (backslash), followed by the character you want to use. For example:

"\"x\"";             // "x"
'"x"';               // "x"
"'x'";               // 'x'
'\'x\'';             // 'x'
"C:\\Program Files"; // C:\Program Files

You can also use escape characters to insert line breaks \n and tabs \t into strings:

"Line 1\nLine 2"; // Line 1
                  // Line 2
"1\t2\t3";         // 1   2   3

Reading and Writing Tag Values

To get a tag’s current value, use tag.read. This function has one argument, which is the name of the tag, and returns the tag’s value.

var myVal = tag.read(“myTag“); // assigns the value of the tag "myTag" to the variable myVal

To set a tag’s value, use tag.write. This takes in two arguments: (1) the name of the tag and (2) the value to write.

tag.write(“myTag”, 1); // writes the value 1 to the tag "myTag"

Tags in tag groups can be accessed using the / character. For example:

tag.write("outerGroup/innerGroup/myTag", 1);

Note that tag.read and tag.write do not bind the tag to a variable. For example, consider the following script:

var value = tag.read("myTag");
// do some stuff that takes a long time
value = value + 1;

This would not affect the tag myTag, and value on line 3 might not be using the most recent tag value.

Each time you want to get the most recent tag value, you must use tag.read, and each time you want to write to the tag, you must use tag.write. To fix the example above:

var value = tag.read("myTag");
// do some stuff that takes a long time
value = tag.read("myTag");
value = value + 1;
tag.write("myTag", value);

Semicolons

JavaScript uses semicolons to indicate the end of expressions. Using semicolons at the end of lines is not required, but is recommended for better organization and clarity:

some_function();
some_other_function();

This is the same as:

some_function()
some_other_function()

Semicolons allow you to perform multiple actions in one line of code without line breaks:

some_function();some_other_function;

Whitespace

JavaScript ignores whitespace characters like spaces, tabs, and line breaks.

For example, the two scripts below are equivalent:

var a = 1;if(tag.read("my_tag")){a=0;}

var a = 1;
if (tag.read("my_tag")) {
  a = 0;
}