Merge pull request #104 from jmespath-community/jep/arithmetic-expressions

JEP-016 Arithmetic Expressions

Author: springcomp

GRAMMAR.ABNF

@@ -658,6 +658,62 @@ minus = %x2D               ; -
 plus = %x2B                ; +
 zero = %x30                ; 0
 
+expression =/ arithmetic-expression ;; ## Arithmetic Expressions
+
+arithmetic-expression =/ "+" expression ; + %x43
+arithmetic-expression =/ ( "-" / "–" ) expression ; - %x45 – %x2212
+
+arithmetic-expression = expression "%" expression ; % %x37
+arithmetic-expression =/ expression ( "*" / "×" ) expression ; * %x42 ×  %xD7
+arithmetic-expression =/ expression "+" expression ; + %x43
+arithmetic-expression =/ expression ( "-" / "–" ) expression ; - %x45 – %x2212
+arithmetic-expression =/ expression ( "/" / "÷" ) expression ; / %x47 ÷
+
+;; An `arithmetic-expression` enables simple computations using the four basic operations,
+;; as well as the modulo and integer-division operations.
+;;
+;; To support arithmetic operations, the following operators are available:
+;; 
+;; - `+` addition operator
+;; - `-` subtraction operator
+;; - `*` multiplication operator
+;; - `/` division operator
+;; - `%` modulo operator
+;; - `//` integer division operator
+;; 
+;; Proper mathematical operators are also supported using the following UNICODE characters:
+;; 
+;; - `–` (U+2212 MINUS SIGN)
+;; - `÷` (U+00F7 DIVISION SIGN)
+;; -  `×` (U+00D7 MULTIPLY SIGN)
+;; 
+;; Arithmetic operations adhere to the usual precedence rules, from lowest to highest:
+;; 
+;; - `-` subtraction operator and `+` addition operator
+;; - `/` division,  `*` multiplication, `%` modulo and `//` integer division operators
+;; 
+;; In the absence of parentheses, operators of the same level of precedence are evaluated from left to right.
+;; Arithmetic operators have higher precedence than comparison operators and lower precedence than the `.` "dot" `sub-expression` token separator.
+;; 
+;; ## Examples
+;;
+;; ```
+;; search(a + b, {"a": 1, "b": 2}) -> 3
+;; search(a - b, {"a": 1, "b": 2}) -> -1 
+;; search(a * b, {"a": 2, "b": 4}) -> 8
+;; search(a / b, {"a": 2, "b": 3}) -> 0.666666666666667
+;; search(a % b, {"a": 10, "b": 3} -> 1
+;; search(a // b, {"a": 10, "b": 3} -> -3 
+;; search(a.b + cd, {"a": {"b": 1}, "c": {"d": 2}}) -> 3
+;; ```
+;;
+;; Since `arithmetic-expression` is not valid on the right-hand-side of a `sub-expression`, a `pipe-expression` can be used instead:
+;;
+;; ```
+;; search({ab: a.b, cd: c.d} | ab + cd, {"a": {"b": 1}, "c": {"d": 2}}) -> 3
+;; ```
+;;
+
 expression =/ root-node ;; ## Root Reference
 
 root-node = "$"

grammar/arithmetic.yml

@@ -0,0 +1,32 @@
+test0:
+  context:
+  query: "`1` + `2`"
+  returns: 3.0
+test1:
+  context:
+  query: "`1` − `2`"
+  returns: -1.0
+test2:
+  context:
+  query: "`2` × `4`"
+  returns: 8.0
+test3:
+  context:
+  query: "`2` ÷ `3`"
+  returns: 0.666666666666667
+test4:
+  context:
+  query: "`10` % `3`"
+  returns: 1.0
+test5:
+  context:
+  query: "`10` // `3`"
+  returns: 3.0
+test6:
+  context:
+  query: "-`1` − +`2`"
+  returns: -3.0
+test7:
+  context:
+  query: "`1` ÷ `0`"
+  error: not-a-number

jep-016-arithmetic-expressions.md

@@ -0,0 +1,87 @@
+# Arithmetic Expressions
+
+|||
+|---|---
+| **JEP**    | 16
+| **Author** | Maxime Labelle
+| **Created**| 01-August-2022
+| **SemVer** | MINOR
+| **Status** | Draft
+
+## Abstract
+
+This JEP proposes a new `arithmetic-expression` rule in the grammar to support simple arithmetic operations.
+
+## Motivation
+
+JMESPath supports querying JSON documents that may return numbers at various stages, but lacks the capability to operate on them using simple arithmetic operations. The only support for arithmetic is currently brought by the `sum()` function.
+
+## Specification
+
+To support arithmetic operations, we need to introduce the following operators:
+
+- `+` addition operator
+- `-` subtraction operator
+- `*` multiplication operator
+- `/` division operator
+- `%` modulo operator
+- `//` integer division operator
+
+Proper mathematical operators also exist in Unicode and SHOULD be supported:
+
+- `–` (U+2212 MINUS SIGN)
+- `÷` (U+00F7 DIVISION SIGN)
+-  `×` (U+00D7 MULTIPLY SIGN)
+
+### Syntax changes
+
+In addition to the following grammar changes, we introduce the usual operator precedence, from lowest to highest:
+
+- `-` subtraction operator and `+` addition operator
+- `/` division,  `*` multiplication, `%` modulo and `//` integer division operators
+
+In the absence of parentheses, operators of the same level of precedence are evaluated from left to right.
+
+Arithmetic operators have higher precedence than comparison operators and lower precedence than the `.` "dot" `sub-expression` token separator.
+
+```abnf
+expression =/ arithmetic-expression
+
+arithmetic-expression =/ "+" expression ; + %x43
+arithmetic-expression =/ ( "-" / "–" ) expression ; - %x45 – %x2212
+
+arithmetic-expression = expression "%" expression ; % %x37
+arithmetic-expression =/ expression ( "*" / "×" ) expression ; * %x42 ×  %xD7
+arithmetic-expression =/ expression "+" expression ; + %x43
+arithmetic-expression =/ expression ( "-" / "–" ) expression ; - %x45 – %x2212
+arithmetic-expression =/ expression ( "/" / "÷" ) expression ; / %x47 ÷ %xF7
+arithmetic-expression = expression "//" expression ; // %47 %47
+
+```
+
+## Examples
+
+|Expression|Result
+|---|---
+|`` `1` + `2` ``| `3.0`
+|`` `1` – `2` ``| `-1.0`
+|`` `2` × `4` ``| `8.0`
+|`` `2` ÷ `3` ``| `0.666666666666667`
+|`` `10` % `3` ``| `1.0`
+|`` `10` // `3` ``| `3.0`
+|`` -`1` − +`2` ``| `-3.0`
+
+Since `arithmetic-expression` is not valid on the right-hand-side of a `sub-expression`, a `pipe-expression` can be used instead:
+
+|Given|Expression|Result
+|---|---|---
+|`{ "a": { "b": 1 }, "c": { "d": 2 } }`|`` { ab: a.b, cd: c.d } \| ab + cd ``| `3`
+
+## Compliance Tests
+
+An `arithmetic.json` file will be added to the compliance test suite.
+The test suite will add the following new error type:
+
+- not-a-number
+
+This error type would be raised at run time when dividing by zero or when overflow occurs, for instance.