[Advanced features] Ambiency Language : What is AMBLANG?

 [Advanced features] Ambiency Language : What is AMBLANG? 

1. Overview

* Amblang is a mini language for specifying filters and actuator input parameters.


###### The grammar
The context-free grammar of amblang is as follows.

  ````
  expr          ::= "{{" (expr | sym) [conv] "}}"
                    | "{{" [expr] conv "}}"
  sym           ::= identifier
                    | literal
  identifier    ::= \w [(\w | \d)+]
  conv          ::= "!" func
  func          ::= identifier "(" args ")"
  args          ::= arg [args]
                    | expr
                    | sym
                    | e
  literal       ::= number
                    | ('"' | "'") .* ('"' | "'")
  number        ::= ["-"] \d+ ["." \d+]
  ````

Expressions can be embedded in any kind of text. When evaluated, the result can be any type of object and will be accordingly put into the enclosing text.

###### Evaluation
An expression is evaluated into one of the following types.
* symbol
* number
* bool
* object

A symbol is not evaluated unless it's enclosed with double curly braces ({{}}). The value of a symbol is retrieved from the provided symbol table containing sensor data with corresponding names.
A literal is either a string enclosed with quotations (single or double) or a number (integer or float).

If the result is an object, it must be consumed by a converter function until the end of evaluation. Failing to do so, the original expression will be remained.


A converter function can be applied to any expression with zero or more arguments. When failed, the original expression will be remained but without the converter function itself.


2. Examples
---
---

Amblang is used in sensor filters and actuator inputs. In sensor filters, amblang must be evaluted into a bool-type result. For actuator inputs, amblang must produce values of a type the actuator expects; otherwise, the actuator will not be executed.


###### Sensor Filters

When specifying filters for sensor data, users can write a filter expression in amblang. All sensor data fields can be used in a expression, and more than one expression are allowed but must result in a single boolean value at the end.

Consider the following filter expression for the Email sensor.

  ````
      {{ sender!endswith("thenaran.com") }}
  ````

This will check if the first sender's domain is "thenaran.com." and get evaluated to a boolean value; true or false.

  ````
      {{ {{ receivers!len }}!gt(1) }}
  ````

This expression will be evaluated to true only if the number of receivers is greater than 1, meaning the email was sent to multiple recipients.
Specifying multiple expressions in more than one depth is also allowed.

  ````
      {{ {{ {{ receivers!len }}!gt(1) }}!and({{ sender!endswith("thenaran.com") }}) }}
  ````

This evaluates to true only if the email is from "thenaran.com" and sent to multiple recipients.


###### Actuator Inputs
Actuators consumes sensor data. However, from time to time, sensor data have different types and formats making direct feeding impossible. Amblang can be used to re-format any type of sensor data and assign to actuator inputs accordingly.

As an example, the Email application has an actuator which can send an email message with or without attachments.
The email's send actuator expects the following inputs.

* receivers : string
* subject : string
* message : string
* file : binary
* file name : string

Each input field has its type and it must be respected in order for a rule to succeed. For each field, amblang can be used for formatting and converting sensor data.

For instance, in a string field, an amblang expression must be evaluated into a string. If it fails to produce a corresponding input type, the expression leaves as it is written before evaluation. In other types of fields, the actuator will not be executed unless all inputs have appropriately-typed values.

Consider the following input expression for the Email actuator's subject field. The WebCam application is used as an example sensor, and the trigger is "snapshot available". 

  ````
      Snapshot taken at {{ time!strftime("%a, %d %b %Y %H:%M:%S +0000") }}
  ````

the message field,

  ````
      Checkout the snapshot below.
  ````

and the file field which expects a binary data,

  ````
      {{image}}
  ````

The "snapshot available" trigger produces two types of sensor data; timestamp and snapshot image file.
Each data is available under the symbols "time" and "image" respectively. The "time" data is an integer type so it must be converted to a string. In this example, the "strftime" converter is used to format the millisecond timestamp into a human-readable text.
The "image" data is a binary data so it can be directly fed to the file field.


Once a motion is detected on the webcam and the snapshot gets ready, an email with the above inputs is sent with the snapshot as an attachment file.


3. Recap
---
---

Amblang is a micro-programming language that defines sensor data filter and actuator input values. It is an advanced feature of possibilities that may require getting used to, but it is not a big deal for most users because Rules can be shared and applied with almost no effort.

This is only a part of Amblang and more will be shared in the coming weeks.

4. Rule Example
---
---

Try out now with a drag-and-drop of the below image file onto your Ambiency. All you need to do is drop the image file onto the app, you can see it applied instantly.