# APL Data-Binding Syntax

**Note:**This public beta release of Alexa Presentation Language (APL) includes the APL documentation, authoring tool, and APL beta forums. Please note that we may improve or change APL as we receive feedback and iterate on the feature.

APL data binding expressions occur inside JSON strings and take the form "${expression}". Any number of expressions may occur inside a string, such as `"${2}+${2} = ${2+2}"`

. Expressions are evaluated within the current data-binding context. The data-binding context is a global dictionary that supports booleans, numbers, strings, arrays, objects, null, and references to defined resources.

## Supported value types

### String literals

Strings are defined using either single or double quotes. The starting and ending quote must match. Quotes, carriage returns, and line-feeds may be escaped.

```
${"Double-quoted string"}
${'Single-quoted string'}
${"Inner quote: \" or '"}
```

Expressions may be nested inside of a string.

```
${"Two plus two is ${2+2}"}
```

### Numbers

Positive, negative, and floating point numbers are supported. Scientific notation is not supported. In JavaScript, all numbers are doubles.

### Booleans

Boolean values of `true`

and `false`

are supported.

```
${true}
${false}
```

### null

The `null`

constant is supported.

```
${null}
```

### Resources

Resources defined in the data-binding context use the reserved character "@". For example:

```
${@myBlue}
${@isLandscape ? @myWideValue : @myNarrowValue}
```

APL packages define resources exposed in data-binding.

## Truthy and Coercion

A **truthy** value is a value that is considered `true`

when evaluated in a boolean context. All values are truthy except for `false`

, `0`

, `""`

, and `null`

.

## Operators

APL supports different types of operators: arithmetic, logical, comparison, and ternary.

### Arithmetic operators

The standard arithmetic operations for addition, subtraction, multiplication, division, and remainder are supported:

```
${1+2} // 3
${1-2} // -1
${1*2} // 2
${1/2} // 0.5
${1%2} // 1.
```

The addition operator also acts as a string-concatenation operator if either the left or right operand is a string.

```
${27+""} // '27'
${1+" dog"} // '1 dog'
${"have "+3} // 'have 3'
```

The remainder operator behaves as in JavaScript. That is,

```
${10 % 3} // 1
${-1 % 2} // -1
${3 % -6} // 3
${6.5 % 2} // 0.5
```

### Logical operators

The standard logical and/or/not operators are supported.

```
${true || false} // true
${true && false} // false
${!true} // false
```

The `&&`

returns the first operand if it is not truthy and the second otherwise. The `||`

operator returns the first operand if it is truthy and the second otherwise.

```
${7 && 2} // 2
${null && 3} // null
${7 || 2} // 7
${0 || -16} // 0
```

### Comparison Operators

Comparison operators return boolean values.

```
${1 < 2}
${75 <= 100}
${3 > -1}
${4 >= 4}
${myNullValue == null}
${(2>1) == true}
${1 != 2}
```

The comparison operators do not apply to arrays and objects.

The `??`

operator is the null-coalescing operator. It returns the left-hand operand if the operand is not null, and otherwise it returns the right-hand operand.

```
${person.name ?? person.surname ?? 'Hey, you!'}
```

### Ternary Operator

The ternary conditional operator `${a ? b : c}`

evaluates the left-hand operand. If it evaluates to true, the middle operand is returned. Otherwise the right-hand operand is returned.

```
${person.rank > 8 ? 'General' : 'Private'}
```

## Array and Object access

### Array

Array access uses the `[]`

operator, where the operand should be an integer. Arrays also support the `.length`

operator to return the length of the array. Accessing an element outside of the array bounds returns `null`

.

```
${myArray[4]} // 5th element in the array (0-indexed)
${myArray.length} // Length of the array
${myArray[-1])} // Last element in the array
```

Passing a negative index counts backwards through the array.

```
${a[-1] == a[a.length - 1]} // True
```

### Object

Objects support the `.`

operator and the `[]`

array access operator with string values.

```
${myObject.name} // The 'name' property of myObject
${myObject['name']} // The 'name' property of myObject
```

If the property is not defined, `null`

is returned.

Calling the `.`

or `[]`

operator on `null`

returns `null`

.

```
${myNullObject.address.zipcode} // Returns null
```

## Function calls

Data-binding supports a limited number of built-in functions. Functions are of the form:

```
functionName( arg1, arg2, … )
```

Functions do not have to have arguments. A function returns a single value. Some functional expressions are shown here:

```
${Math.floor(1.1)} // 1
${Math.ceil(1.2)} // 2
${Math.round(1.2)} // 1
${Math.min(1,2,3,4)} // 1
${Math.max(1,2,3,4)} // 4
${String.toUpperCase('Hello')} // HELLO
${String.toLowerCase('Hello')} // hello
${String.slice('Hello', 1, -1)} // ell
```

### Built-in functions

Some mathematical and string functions are built in to APL.

Property | Description | Example |

Math.abs(x) | Return the absolute value of x | ${Math.abs(-2.3)} == 2.3 |

Math.acos(x) | The arccosine of x | ${Math.acos(1)} == 0 |

Math.asin(x) | The arcsine of x | ${Math.asin(0)} == 0 |

Math.atan(x) | The arctangent of x | ${Math.atan(1)} == 0.7853981633974483 |

Math.ceil(x) | Return the smallest integer greater than or equal to x. | ${Math.ceil(2.3)} == 3 |

Math.clamp(x,y,z) | Return x if y<x, z if y>z, and otherwise y. | ${Math.clamp(1, 22.3, 10)} == 10 |

Math.cos(x) | The cosine of x | ${Math.cos(0)} == 1 |

Math.floor(x) | Return the largest integer less than or equal to x. | ${Math.floor(2.3)} = 2 |

Math.max(x1,x2,…) | Return the largest argument | ${Math.max(2,3)} == 3 |

Math.min(x1,x2,…) | Return the smallest argument | ${Math.min(2,3)} == 2 |

Math.PI | The value of PI | 3.141592653589793 |

Math.random() | A random number between 0 and 1 | ${Math.random()} == 0.7113654073137101 (the actual random number returned will be different) |

Math.round(x) | Return the nearest integer to x | ${Math.round(2.3)} == 2 |

Math.sign(x) | The sign of x: -1, 0, or 1 | ${Math.sign(-43.1) == -1} |

Math.sin(x) | The sine of x | ${Math.sin(Math.PI/6)} == 0.5 |

Math.sqrt(x) | The square root of x | ${Math.sqrt(9)} == 3 |

Math.tan(x) | The tangent of x | ${Math.tan(Math.PI/4)} == 0.5 |

String.slice(x,y[,z]) | Return the subset of x starting at index y and extending to but not including index z. If z is omitted, the remainder of the string is returned. If y is a negative number, select from the end of the string. | ${String.slice('berry', 2, 4)} == "rr" ${String.slice('berry', -2)} == "ry" |

String.toLowerCase(x) | Return a lower-case version of x | ${String.toLowerCase('bEn')} == "ben" |

String.toUpperCase(x) | Return an upper-case version of x. | ${String.toUpperCase('bEn')} == "BEN" |