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. Functions let This lets you re-use pieces of code without re-writing everything.

...

For example, the script below calls the function notification.send function 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 project::

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("

...

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.

...

Variables can be declared using the following format:

var variable_namevariableName;

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

var variable_name_1, variable_name_2variable1, variable2, ... , variable_name_nvariablen;

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

var variable_name variableName = 1;

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

...

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 tag_name = "my_tagmyTag";
var value = 1;
tag.write(tag_nametagName, value);

This is the same as:

tag.write("my_tagmyTag", 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 . This lets you change and to specify the order of operations. For example:

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

You do not need to store values to variables to use them. Expressions will be evaluated as soon as they are needed. For example:

add(1, 2)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 3
add(add(1, 2), 3) // 62
"1\t2\t3";         // 1   2   3

Reading and Writing Tag Values

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

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. There is no return value.The following script increments a tag’s value by 1:

var value = tag.read(“my_tag“write(“myTag”, 1); value =// writes the value 1 +to 1;the tag.write(“my_tag”, value);

...

 "myTag"

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

tag.write("my_tagouterGroup/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"); // get the most recent tag value
value = value + 1;
tag.write("myTag", value); // write the script value to the 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;
}

...