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.

...

// 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.

...

For example, the script below calls the function notification.send with the argument "Hello, world!". This will bring up a notification that says “Hello, world!”::

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

Some functions do not require any arguments, for example system.exit, which exits the runtime project. In a script, it would look like this::

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. The script below writes the value 1 to the tag called "my_tag"::

tag.write("my_tag",

...

 true); writes the value true to the tag named "my_tag"

Declaring Variables

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

...

Using and Setting Variables

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

...

tag.write("my_tag", 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 evaluated as soon as 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("my_tag", !tag.read("my_tag")) // toggles the value of the tag named "my_tag"

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 valuemy_val = tag.read(“my_tag“); // assigns the value of the tag "my_tag" to the variable my_val

To write a tag value, use tag.write. This takes in two arguments: the name of the tag and the value to write. There is no return value tag.write always returns undefined.

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

...

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;

Whitespace

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

...

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

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

...