Merge branch 'main' into jep/object-manipulation-functions

Author: springcomp

GRAMMAR.ABNF

@@ -19,7 +19,7 @@
 ;; The result of applying a JMESPath expression against a JSON document will always result in valid JSON, provided there
 ;; are no errors during the evaluation process. Structured data in, structured data out.
 ;;
-;; This also means that, with the exception of JMESPath expression types, JMESPath only supports the same types support by JSON:
+;; This also means that, with the exception of JMESPath expression types, JMESPath only supports the same types supported by JSON:
 ;;
 ;; - number (integers and double-precision floating-point format in JSON)
 ;; - string
@@ -62,7 +62,8 @@ sub-expression    = expression "." ( identifier / multi-select-list / multi-sele
 ;; In pseudocode:
 ;; ```
 ;; left-evaluation = search(left-expression, original-json-document)
-;; result = search(right-expression, left-evaluation)
+;; if left-evaluation is `null` then result = `null`
+;; else result = search(right-expression, left-evaluation)
 ;; ```
 ;; A sub-expression is itself an expression, so there can be multiple levels of sub-expressions: grandparent.parent.child.
 ;; Examples
@@ -252,36 +253,36 @@ bracket-specifier =/ "[]" ;; ## Flatten Operator
 ;; ```
 
 slice-expression  = [number] ":" [number] [ ":" [number] ] ;; ## Slices
-;; A slice expression allows you to select a subset of an array. A slice has a start, stop, and step value. The
-;; general form of a slice is [start:stop:step], but each component is optional and can be omitted.
+;; A slice expression allows you to select a subset of an array or a string. A slice has a `start`, `stop`, and `step` value. The
+;; general form of a slice is `[start:stop:step]`, but each component is optional and can be omitted.
 ;;
 ;; ```note
 ;; Slices in JMESPath have the same semantics as python slices. If you're familiar with python slices, you're familiar with
 ;; JMESPath slices.
 ;; ```
 ;;
-;; Given a start, stop, and step value, the sub elements in an array are extracted as follows:
+;; Given a `start`, `stop`, and `step` value, the sub elements in an array or characters in a string are extracted as follows:
 ;;
-;; - The first element in the extracted array is the index denoted by start.
-;; - The last element in the extracted array is the index denoted by end - 1.
-;; - The step value determines how many indices to skip after each element is selected from the array.
-;;   The default step value of 1 will not skip any indices and will return a contiguous subset of the original array.
-;;   A step value greater than 1 will skip indices while extracting elements from an array. For instance, a step value of 2 will
-;;   skip every other index.
-;;   Negative step values start from the end of the array and extract elements in reverse order.
+;; - The first element in the extracted array or first character in the extracted string is the index denoted by `start`.
+;; - The last element in the extracted array or last character in the extracted string is the index denoted by `end - 1`.
+;; - The `step` value determines how many indices to skip after each element is selected from the array or each character is selected from the string.
+;;   The default `step` value of `1` will not skip any indices and will return a contiguous subset of the original array or a substring of the original string.
+;;   A `step` value greater than `1` will skip indices while extracting elements from an array or characters from a string. For instance, a `step` value of `2` will
+;;   skip every other element or character.
+;;   Negative `step` values start from the end of the array or string and extract elements or characters in reverse order.
 ;;
 ;; Slice expressions adhere to the following rules:
 ;;
-;; - If a negative start position is given, it is calculated as the total length of the array plus the given start position.
-;; - If no start position is given, it is assumed to be 0 if the given step is greater than 0 or the end of the array if
-;;   the given step is less than 0.
-;; - If a negative stop position is given, it is calculated as the total length of the array plus the given stop position.
-;; - If no stop position is given, it is assumed to be the length of the array if the given step is greater than 0 or 0 if
-;;   the given step is less than 0.
-;; - If the given step is omitted, it it assumed to be 1.
-;; - If the given step is 0, an error MUST be raised.
-;; - If the element being sliced is not an array, the result is null.
-;; - If the element being sliced is an array and yields no results, the result MUST be an empty array.
+;; - If a negative `start` position is given, it is calculated as the total length of the array or string plus the given `start` position.
+;; - If no `start` position is given, it is assumed to be `0` if the given `step` is greater than 0 or the end of the array or string if
+;;   the given `step` is less than `0`.
+;; - If a negative `stop` position is given, it is calculated as the total length of the array or string plus the given `stop` position.
+;; - If no `stop` position is given, it is assumed to be the length of the array or string if the given `step` is greater than `0` or `0` if
+;;   the given `step` is less than `0`.
+;; - If the given `step` is omitted, it it assumed to be `1`.
+;; - If the given `step` is `0`, an error MUST be raised.
+;; - If the element being sliced is not an array or a string, the result is `null`.
+;; - If the element being sliced is an array or string and yields no results, the result MUST be an empty array.
 ;;
 ;; ### Examples
 ;; ```
@@ -293,6 +294,12 @@ slice-expression  = [number] ":" [number] [ ":" [number] ] ;; ## Slices
 ;; search([::-1], [0, 1, 2, 3]) -> [3, 2, 1, 0]
 ;; search([-2:], [0, 1, 2, 3]) -> [2, 3]
 ;; ```
+;; Slicing operates on strings exactly as if a string were thought of as an array of characters.
+;; ```
+;; search(foo[0:4], {"foo": "hello, world!"}) -> "hell"
+;; search([::], 'raw-string') -> "raw-string"
+;; search([::2], 'raw-string') -> "rwsrn"
+;; search([::-1], 'raw-string') -> "gnirts-war"
 
 multi-select-list = "[" ( expression *( "," expression ) ) "]" ;; # MultiSelect List
 ;; A multiselect expression is used to extract a subset of elements from a JSON hash. There are two version of multiselect,
@@ -601,7 +608,7 @@ unquoted-string   = (%x41-5A / %x61-7A / %x5F) *(  ; A-Za-z_
                         %x5F    /  ; _
                         %x61-7A)   ; a-z
 quoted-string     = quote 1*(unescaped-char / escaped-char) quote
-unescaped-char    = %x20-21 / %x23-5B / %x5D-10FFFF
+unescaped-char    = %x20-21 / %x23-2E / %30-5B / %x5D-10FFFF
 escape            = "\"
 quote             = %x22   ; Double quote: '"'
 escaped-char      = escape (
@@ -650,3 +657,39 @@ int = zero / ( digit1-9 *digit )
 minus = %x2D               ; -
 plus = %x2B                ; +
 zero = %x30                ; 0
+
+expression =/ root-node ;; ## Root Reference
+
+root-node = "$"
+
+;; ## root-node
+;;
+;; The `root-node` token can be used to represent the original input JSON document.
+;;
+;; As a JMESPath expression is being evaluated, the current scope changes.
+;; Given a simple sub expression such as `foo.bar`, first the `foo` expression is evaluated
+;; with the starting input JSON document, and the result of that expression is then used as
+;; the current scope when the `bar` element is evaluated.
+;; 
+;; Once we’ve drilled down to a specific scope, the `root-node` token can be used
+;; to refer to the original JSON document.
+;;
+;; Example
+;;
+;; Given a JSON document:
+;; 
+;; ```json
+;; {
+;;   "first_choice": "WA",
+;;   "states": [
+;;      {"name": "WA", "cities": ["Seattle", "Bellevue", "Olympia"]},
+;;      {"name": "CA", "cities": ["Los Angeles", "San Francisco"]},
+;;      {"name": "NY", "cities": ["New York City", "Albany"]}
+;;  ]
+;; }
+;; ```
+;; We can retrieve the list of cities of the state corresponding to the `first_choice` key
+;; using the following expression:
+;;
+;; ` states[? name == $.first_choice ].cities[] `
+;;

function_schema.yml

@@ -51,15 +51,17 @@ properties:
         type: array
         description: ""
         items:
-          type: object
           allOf:
             - $ref: "#/$defs/unnamed_arg"
+            - type: object
+              required:
+              - name
+              properties:
+                name:
+                  type: string
+                  description: ""
           description: ""
           unevaluatedProperties: false
-          properties:
-            name:
-              type: string
-              description: ""
       optional: *arg
       variadic: *unnamed_arg
   returns:

functions/find_first.yml

@@ -0,0 +1,64 @@
+name: find_first
+topic: strings
+args:
+  required:
+  - name: subject
+    type: [string]
+    desc: 'Subject string'
+  - name: sub
+    type: [string]
+    desc: 'Substring'
+  optional: 
+    - name: start
+      type: [number]
+      desc: 'Position in the subject string where searching should start.'
+    - name: end
+      type: [number]
+      desc: 'Position in the subject string where searching should end.'
+returns:
+  type: number
+  desc: ''
+desc: |
+  Given the `subject` string, `find_first()` returns the index of the first occurence where the `sub` substring appears in `subject` or `null`.
+
+  The `start` and `end` parameters are optional and allow to select where `find_first()` must perform its search within `subject`.
+
+  * If `start` is omitted, it defaults to `0` which is the start of the `subject` string.
+  * If `end` is omitted, it defaults to `length(subject) - 1` which is is the end of the `subject` string.
+examples:
+  find_first:
+    context: &subject subject string
+    args: ['@', 'string']
+    returns: 8.0
+  find_first_start:
+    context: *subject
+    args: ['@', 'string', '`0`']
+    returns: 8.0
+  find_first_start_end:
+    context: *subject
+    args: ['@', 'string', '`0`', '`14`']
+    returns: 8.0
+  find_first_start_before_end_after:
+    context: *subject
+    args: ['@', 'string', '`-99`', '`100`']
+    returns: 8.0
+  find_first_ends_prematurely:
+    context: *subject
+    args: ['@', 'string', '`0`', '`13`']
+    returns: null
+  find_first_start_boundary:
+    context: *subject
+    args: ['@', 'string', '`8`']
+    returns: 8.0
+  find_first_incomplete:
+    context: *subject
+    args: ['@', 'string', '`9`']
+    returns: null
+  find_first_first_occurrence:
+    context: *subject
+    args: ['@', 's', '`0`']
+    returns: 0.0
+  find_first_second_occurrence:
+    context: *subject
+    args: ['@', 's', '`1`']
+    returns: 8.0

functions/find_last.yml

@@ -0,0 +1,44 @@
+name: find_last
+topic: strings
+args:
+  required:
+  - name: subject
+    type: [string]
+    desc: 'Subject string'
+  - name: sub
+    type: [string]
+    desc: 'Substring'
+  optional: 
+    - name: pos
+      type: [number]
+      desc: 'Position in the subject string where searching should start.'
+returns:
+  type: number
+  desc: ''
+desc: |
+  Given the `subject` string, `find_last()` returns the index of the last occurence where the `sub` substring appears in `subject` or `null`.
+
+  The `pos` parameter is optional and allow to select where `find_first()` must perform its search within `subject`.
+  If this is parameter omitted, it defaults to `length(subject) - 1` which is is the end of the `subject` string.
+  `find_last()` then searches backwards in the `subject` string for the first occurrence of the `sub` substring.
+examples:
+  find_last:
+    context: &subject subject string
+    args: ['@', 'string']
+    returns: 8.0
+  find_last_pos:
+    context: *subject
+    args: ['@', 'string', '`8`']
+    returns: 8.0
+  find_last_pos_ends_prematurely:
+    context: *subject
+    args: ['@', 'string', '`7`']
+    returns: null
+  find_last_second_occurrence:
+    context: *subject
+    args: ['@', 's', '`8`']
+    returns: 8.0
+  find_last_first_occurrence:
+    context: *subject
+    args: ['@', 's', '`7`']
+    returns: 0.0

functions/group_by.yml

@@ -0,0 +1,77 @@
+name: group_by
+topic: collections
+args:
+  required:
+  - name: elements
+    type: ['array[object]']
+    desc: ''
+  - name: expr
+    type: [expression->string]
+    desc: ''
+  optional: []
+returns:
+  type: object
+  desc: ''
+desc: |
+  Groups an array of objects `$elements` using an expression `$expr` as the group key.
+  The `$expr` expression is applied to each element in the array `$elements` and the 
+  resulting value is used as a group key.
+
+  The result is an object whose keys are the unique set of string keys and whose respective values are an array of objects array matching the group criteria.
+
+  Objects that do not match the group criteria are discarded from the output.
+  This includes objects for which applying the `$expr` expression evaluates to `null`.
+
+  If the result of applying the `$expr` expression against the current array element
+  results in type other than `string` or `null`, a type error MUST be raised.
+examples:
+  group_by:
+    context:
+      items:
+        - spec:
+            nodeName: node_01
+            other: values_01
+        - spec:
+            nodeName: node_02
+            other: values_02
+        - spec:
+            nodeName: node_03
+            other: values_03
+        - spec:
+            nodeName: node_01
+            other: values_04
+    args: [items, '&nodeName']
+    returns: 
+      nodeName:
+        node_01:
+          - spec:
+              nodeName: node_01
+              other: values_01
+          - spec:
+              nodeName: node_01
+              other: values_04
+        node_02:
+          - spec:
+              nodeName: node_02
+              other: values_02
+        node_03:
+          - spec:
+              nodeName: node_03
+              other: values_03
+  group_by_discards_null_keyed_objects:
+    context: &data
+      array:
+      - b: true
+        name: one
+      - b: false
+        name: two
+      - b: false
+    args: [array, '&name']
+    returns: [{age: 10, age_str: '10', bool: true, name: 3}, {age: 20, age_str: '20',
+        bool: true, name: a, extra: foo}, {age: 30, age_str: '30', bool: true, name: c},
+      {age: 40, age_str: '40', bool: false, name: b, extra: bar}, {age: 50, age_str: '50',
+        bool: false, name: d}]
+  group_by_errs_invalid_type:
+    context: *data
+    args: [array, '&b']
+    error: invalid-type