Updated embedded JavaScript implementation that powers live examples and tutorials.Feature/js

documentation/grammar/functions/abs.inc

@@ -0,0 +1,87 @@
+.. _func-abs:
+
+abs
+---
+
+::
+
+    number abs(number $value)
+
+Returns the absolute value of the provided argument.  The signature indicates
+that a number is returned, and that the input argument ``$value`` **must**
+resolve to a number, otherwise a ``invalid-type`` error is triggered.
+
+Below is a worked example.  Given::
+
+    {"foo": -1, "bar": "2"}
+
+Evaluating ``abs(foo)`` works as follows:
+
+1. Evaluate the input argument against the current data::
+
+     search(foo, {"foo": -1, "bar": "2"}) -> -1
+
+2. Validate the type of the resolved argument.  In this case
+   ``-1`` is of type ``number`` so it passes the type check.
+
+3. Call the function with the resolved argument::
+
+     abs(-1) -> 1
+
+4. The value of ``1`` is the resolved value of the function expression
+   ``abs(foo)``.
+
+
+Below is the same steps for evaluating ``abs(bar)``:
+
+1. Evaluate the input argument against the current data::
+
+     search(bar, {"foo": -1, "bar": "2"}) -> "2"
+
+2. Validate the type of the resolved argument.  In this case
+   ``"2"`` is of type ``string`` so we immediately indicate that
+   an ``invalid-type`` error occurred.
+
+
+As a final example, here is the steps for evaluating ``abs(to_number(bar))``:
+
+1. Evaluate the input argument against the current data::
+
+    search(to_number(bar), {"foo": -1, "bar": "2"})
+
+2. In order to evaluate the above expression, we need to evaluate
+   ``to_number(bar)``::
+
+    search(bar, {"foo": -1, "bar": "2"}) -> "2"
+    # Validate "2" passes the type check for to_number, which it does.
+    to_number("2") -> 2
+
+   Note that `to_number`_ is defined below.
+
+3. Now we can evaluate the original expression::
+
+    search(to_number(bar), {"foo": -1, "bar": "2"}) -> 2
+
+4. Call the function with the final resolved value::
+
+    abs(2) -> 2
+
+5. The value of ``2`` is the resolved value of the function expression
+   ``abs(to_number(bar))``.
+
+
+.. cssclass:: table
+
+.. list-table:: Examples
+  :header-rows: 1
+
+  * - Expression
+    - Result
+  * - ``abs(1)``
+    - ``1``
+  * - ``abs(-1)``
+    - ``1``
+  * - ``abs(`abc`)``
+    - ``<error: invalid-type>``
+
+

documentation/grammar/functions/avg.inc

@@ -0,0 +1,35 @@
+.. _func-avg:
+
+avg
+---
+
+::
+
+    number avg(array[number] $elements)
+
+Returns the average of the elements in the provided array.
+
+An empty array will produce a return value of null.
+
+.. cssclass:: table
+
+.. list-table:: Examples
+  :header-rows: 1
+
+  * - Given
+    - Expression
+    - Result
+  * - ``[10, 15, 20]``
+    - ``avg(@)``
+    - ``15``
+  * - ``[10, false, 20]``
+    - ``avg(@)``
+    - ``<error: invalid-type>``
+  * - ``[false]``
+    - ``avg(@)``
+    - ``<error: invalid-type>``
+  * - ``false``
+    - ``avg(@)``
+    - ``<error: invalid-type>``
+
+

documentation/grammar/functions/ceil.inc

@@ -0,0 +1,28 @@
+.. _func-ceil:
+
+ceil
+----
+
+::
+
+    number ceil(number $value)
+
+Returns the next highest integer value by rounding up if necessary.
+
+.. cssclass:: table
+
+.. list-table:: Examples
+  :header-rows: 1
+
+  * - Expression
+    - Result
+  * - ``ceil(`1.001`)``
+    - ``2``
+  * - ``ceil(`1.9`)``
+    - ``2``
+  * - ``ceil(`1`)``
+    - ``1``
+  * - ``ceil(`abc`)``
+    - ``null``
+
+

documentation/grammar/functions/contains.inc

@@ -0,0 +1,58 @@
+.. _func-contains:
+
+contains
+--------
+
+::
+
+    boolean contains(array|string $subject, any $search)
+
+Returns ``true`` if the given ``$subject`` contains the provided ``$search``
+string.
+
+If ``$subject`` is an array, this function returns true if one of the elements
+in the array is equal to the provided ``$search`` value.
+
+If the provided ``$subject`` is a string, this function returns true if
+the string contains the provided ``$search`` argument.
+
+.. cssclass:: table
+
+.. list-table:: Examples
+  :header-rows: 1
+
+  * - Given
+    - Expression
+    - Result
+  * - n/a
+    - ``contains(`foobar`, `foo`)``
+    - ``true``
+  * - n/a
+    - ``contains(`foobar`, `not`)``
+    - ``false``
+  * - n/a
+    - ``contains(`foobar`, `bar`)``
+    - ``true``
+  * - n/a
+    - ``contains(`false`, `bar`)``
+    - ``<error: invalid-type>``
+  * - n/a
+    - ``contains(`foobar`, 123)``
+    - ``false``
+  * - ``["a", "b"]``
+    - ``contains(@, `a`)``
+    - ``true``
+  * - ``["a"]``
+    - ``contains(@, `a`)``
+    - ``true``
+  * - ``["a"]``
+    - ``contains(@, `b`)``
+    - ``false``
+  * - ``["foo", "bar"]``
+    - ``contains(@, `foo`)``
+    - ``true``
+  * - ``["foo", "bar"]``
+    - ``contains(@, `b`)``
+    - ``false``
+
+

documentation/grammar/functions/ends-with.inc

@@ -0,0 +1,30 @@
+.. _func-ends-with:
+
+ends_with
+---------
+
+::
+
+    boolean ends_with(string $subject, string $prefix)
+
+Returns ``true`` if the ``$subject`` ends with the ``$prefix``, otherwise this
+function returns ``false``.
+
+
+.. list-table:: Examples
+  :header-rows: 1
+
+  * - Given
+    - Expression
+    - Result
+  * - ``foobarbaz``
+    - ``ends_with(@, `baz`)``
+    - ``true``
+  * - ``foobarbaz``
+    - ``ends_with(@, `foo`)``
+    - ``false``
+  * - ``foobarbaz``
+    - ``ends_with(@, `z`)``
+    - ``true``
+
+

documentation/grammar/functions/floor.inc

@@ -0,0 +1,26 @@
+.. _func-floor:
+
+floor
+-----
+
+::
+
+    number floor(number $value)
+
+Returns the next lowest integer value by rounding down if necessary.
+
+.. cssclass:: table
+
+.. list-table:: Examples
+  :header-rows: 1
+
+  * - Expression
+    - Result
+  * - ``floor(`1.001`)``
+    - ``1``
+  * - ``floor(`1.9`)``
+    - ``1``
+  * - ``floor(`1`)``
+    - ``1``
+
+

documentation/grammar/functions/join.inc

@@ -0,0 +1,34 @@
+.. _func-join:
+
+join
+----
+
+::
+
+    string join(string $glue, array[string] $stringsarray)
+
+Returns all of the elements from the provided ``$stringsarray`` array joined
+together using the ``$glue`` argument as a separator between each.
+
+
+.. cssclass:: table
+
+.. list-table:: Examples
+  :header-rows: 1
+
+  * - Given
+    - Expression
+    - Result
+  * - ``["a", "b"]``
+    - ``join(`, `, @)``
+    - ``"a, b"``
+  * - ``["a", "b"]``
+    - :literal:`join(\`\`, @)`
+    - ``"ab"``
+  * - ``["a", false, "b"]``
+    - ``join(`, `, @)``
+    - ``<error: invalid-type>``
+  * - ``[false]``
+    - ``join(`, `, @)``
+    - ``<error: invalid-type>``
+

documentation/grammar/functions/keys.inc

@@ -0,0 +1,37 @@
+.. _func-keys:
+
+keys
+----
+
+::
+
+    array keys(object $obj)
+
+Returns an array containing the keys of the provided object.
+Note that because JSON hashes are inheritently unordered, the
+keys associated with the provided object ``obj`` are inheritently
+unordered.  Implementations are not required to return keys in
+any specific order.
+
+.. cssclass:: table
+
+.. list-table:: Examples
+  :header-rows: 1
+
+  * - Given
+    - Expression
+    - Result
+  * - ``{"foo": "baz", "bar": "bam"}``
+    - ``keys(@)``
+    - ``["foo", "bar"]``
+  * - ``{}``
+    - ``keys(@)``
+    - ``[]``
+  * - ``false``
+    - ``keys(@)``
+    - ``<error: invalid-type>``
+  * - ``[b, a, c]``
+    - ``keys(@)``
+    - ``<error: invalid-type>``
+
+

documentation/grammar/functions/length.inc

@@ -0,0 +1,45 @@
+.. _func-length:
+
+length
+------
+
+::
+
+    number length(string|array|object $subject)
+
+Returns the length of the given argument using the following types rules:
+
+1. string: returns the number of code points in the string
+2. array: returns the number of elements in the array
+3. object: returns the number of key-value pairs in the object
+
+.. cssclass:: table
+
+.. list-table:: Examples
+  :header-rows: 1
+
+  * - Given
+    - Expression
+    - Result
+  * - n/a
+    - ``length(`abc`)``
+    - ``3``
+  * - "current"
+    - ``length(@)``
+    - ``7``
+  * - "current"
+    - ``length(not_there)``
+    - ``<error: invalid-type>``
+  * - ``["a", "b", "c"]``
+    - ``length(@)``
+    - ``3``
+  * - ``[]``
+    - ``length(@)``
+    - ``0``
+  * - ``{}``
+    - ``length(@)``
+    - ``0``
+  * - ``{"foo": "bar", "baz": "bam"}``
+    - ``length(@)``
+    - ``2``
+