---
id: planout-language-reference
title: PlanOut Language Reference
layout: docs
permalink: /docs/planout-language-reference.html
prev: getting-started-with-the-interpreter.html
next: namespaces.html
---

The PlanOut language is a way to concisely define experiments. The language is
designed to be simple enough to be understood by those with little programming
background. It includes basic logical operators, conditional execution, and data
structures.


## Overview
The PlanOut language syntax is similar to JavaScript, but with a few exceptions:

 * Variables (parameters) can be assigned by writing `a <- b` or `a = b`.
 * Operator (function) arguments can be named
 * Some operators, including random assignment operators, require named arguments.
 The ordering of these arguments does not matter.
 * `#`'s are used to write comments
 * `null` is returned when an invalid array or dictionary key accessed.
 * The `&&` and `||` logical operators always return boolean values.

## PlanOut syntax and operators
The following is a reference of all the PlanOut syntax and built-in
operators.

#### Random assignment operators
All of PlanOut's [random assignment operators](random-operators.html) are
available in the language. The variable name given on the left
hand side of an assignment operation is used as the salt, if no salt is
specified manually, e.g.,

```
colors = ['#aa2200', '#22aa00', '#0022aa'];
x = uniformChoice(choices=colors, unit=userid); # 'x' used as salt
y = uniformChoice(choices=colors, unit=userid); # 'y' used as salt, generally != x
z = uniformChoice(choices=colors, unit=userid, salt='x'); # same value as x
```

Units can be scalars or arrays:

```
x = uniformChoice(choices=colors, unit=userid);
y = uniformChoice(choices=colors, unit=[userid, url]);
```

All random assignment operators are available via the PlanOut language:

```
a = uniformChoice(choices=colors, unit=userid);
b = weightedChoice(choices=colors weights=[0.2, 0.8], unit=userid);
c = bernoulliTrial(p=0.2, unit=userid);
d = randomFloat(min=1.0, max=2.0, unit=userid);
e = randomInteger(min=1, max=10, unit=userid);
f = sample(choices=colors, num_draws = 2);
```


#### Arrays
Arrays can include constants and variables, and can be arbitrarily nested, and can contain arbitrary types.

```
a = [4, 5, 'foo'];
b = [a, 2, 3];      # evaluates to [[1,2,'foo'], 2,3]
x = a[0];           # evaluates to 4
y = b[0][2];        # evaluates to 'foo'
z = b[22];          # evaluates to null
```

#### Dictionaries
PlanOut also has limited support for dictionaries, which may be passed in as inputs
into PlanOut or expressed in terms of constant JSON literals, denoted by `@`:

```
a = @{'foo':1, 'bar': [2,3]};
x = a['bar'][0];               # evaluates to 2
y = a['bogus']                 # evaluates to null
```

Note that the following code is not supported:

```
v = 1;
a = @{'foo': v};
b = {'foo': v};
```

When invalid indexes are accessed, PlanOut returns `null`.

```
b = [1,2,3];
n = b[5];                     # evaluates to null
m = b[5][1];                  # evaluates to null
```

The null-coalescing operator, `coalesce()` can be used to protect against
invalid indexes:

```
c = coalesce(b[5], 42);       # evaluates to 42
c2 = coalesce(b[5][2], 42);   # evaluates to 42
```

#### Logical operators
Logical operators include *and* (`&&`), *or* (`||`), *not* (`!`), as in:

```
  a = 1; b = 0; c = 1;
  x = a && b;       # evaluates to False
  y = a || b || c;  # evaluates to True
  y = !b;           # evaluates to True
```

#### Control flow
Conditional execution can be implemented via if / else if / else.

```
if (country == 'US') {
  p = 0.2;
} else if (country == 'UK') {
  p = 0.4;
} else {
  p = 0.1;
}
```

#### Arithmetic
PlanOut supports basic arithmetic operations.

```
 a = 2 + 3 + 4;  # 9
 b = 2 * 3 * 4;  # 24
 c = -2;         # -2
 d = 2 + 3 - 4;  # 1
 e = 4 % 2;      # 0
 f = 4 / 2;      # 2.0
 g = round(2.3); # 2
```

Note that a space is required between `-` and `4` in the above example.


#### Other operators
Other built-in operators include `min`, `max`, and the null coalescing operator, `coalesce`.

```
x = [];
a = min(1, 2, -4);                # -4
b = min(values=[1, 2, -4]);       # -4
c = coalesce(x[42], null, 0, 8);  # 0
```

These operators can either be written as taking an arbitrary number of unnamed arguments, or as taking a single array argument, called `values`.

#### Return

```
return true;   # short circuits execution
return false;  # short circuits execution, disables logging
```