Merge pull request #52 from jmespath-community/functions

Add function docs

Author: innovate-invent

functions/abs.yml

@@ -0,0 +1,108 @@
+name: abs
+topic:
+args:
+  required:
+  - name: value
+    type: [number]
+    desc:
+  optional: []
+returns:
+  type: number
+  desc:
+desc: |
+  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))`.
+examples:
+- context: None
+  args: [1]
+  returns: 1
+- context: None
+  args: [-1]
+  returns: 1
+- context: None
+  args: ["abc"]
+  returns: "<error: invalid-type>"

functions/avg.yml

@@ -0,0 +1,28 @@
+name: avg
+topic:
+args:
+  required:
+  - name: elements
+    type: ['array[number]']
+    desc:
+  optional: []
+returns:
+  type: number
+  desc:
+desc: |
+  Returns the average of the elements in the provided array.
+  
+  An empty array will produce a return value of null.
+examples:
+- context: [10, 15, 20]
+  args: [@]
+  returns: 15
+- context: [10, false, 20]
+  args: [@]
+  returns: "<error: invalid-type>"
+- context: [false]
+  args: [@]
+  returns: "<error: invalid-type>"
+- context: false
+  args: [@]
+  returns: "<error: invalid-type>"

functions/ceil.yml

@@ -0,0 +1,26 @@
+name: ceil
+topic:
+args:
+  required:
+  - name: value
+    type: [number]
+    desc:
+  optional: []
+returns:
+  type: number
+  desc:
+desc: |
+  Returns the next highest integer value by rounding up if necessary.
+examples:
+- context: None
+  args: [1.001]
+  returns: 2
+- context: None
+  args: [1.9]
+  returns: 2
+- context: None
+  args: [1]
+  returns: 1
+- context: None
+  args: [abc]
+  returns: null

functions/contains.yml

@@ -0,0 +1,54 @@
+name: contains
+topic:
+args:
+  required:
+  - name: subject,
+    type: [array, string]
+    desc:
+  - name: search
+    type: [any]
+    desc:
+  optional: []
+returns:
+  type: boolean
+  desc:
+desc: |
+  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.
+examples:
+- context: None
+  args: [foobar, foo]
+  returns: true
+- context: None
+  args: [foobar, not]
+  returns: false
+- context: None
+  args: [foobar, bar]
+  returns: true
+- context: None
+  args: [false, bar]
+  returns: "<error: invalid-type>"
+- context: None
+  args: [foobar, 123]
+  returns: false
+- context: ["a", "b"]
+  args: [@, a]
+  returns: true
+- context: ["a"]
+  args: [@, a]
+  returns: true
+- context: ["a"]
+  args: [@, b]
+  returns: false
+- context: ["foo", "bar"]
+  args: [@, foo]
+  returns: true
+- context: ["foo", "bar"]
+  args: [@, b]
+  returns: false

functions/ends_with.yml

@@ -0,0 +1,27 @@
+name: ends_with
+topic:
+args:
+  required:
+  - name: subject,
+    type: [string]
+    desc:
+  - name: prefix
+    type: [string]
+    desc:
+  optional: []
+returns:
+  type: boolean
+  desc:
+desc: |
+  Returns `true` if the `$subject` ends with the `$prefix`, otherwise this
+  function returns `false`.
+examples:
+- context: foobarbaz
+  args: [@, baz]
+  returns: true
+- context: foobarbaz
+  args: [@, foo]
+  returns: false
+- context: foobarbaz
+  args: [@, z]
+  returns: true

functions/floor.yml

@@ -0,0 +1,23 @@
+name: floor
+topic:
+args:
+  required:
+  - name: value
+    type: [number]
+    desc:
+  optional: []
+returns:
+  type: number
+  desc:
+desc: |
+  Returns the next lowest integer value by rounding down if necessary.
+examples:
+- context: None
+  args: [1.001]
+  returns: 1
+- context: None
+  args: [1.9]
+  returns: 1
+- context: None
+  args: [1]
+  returns: 1

functions/join.yml

@@ -0,0 +1,30 @@
+name: join
+topic:
+args:
+  required:
+  - name: glue
+    type: [string]
+    desc:
+  - name: stringsarray
+    type: ['array[string]']
+    desc:
+  optional: []
+returns:
+  type: string
+  desc:
+desc: |
+  Returns all of the elements from the provided `$stringsarray` array joined
+  together using the `$glue` argument as a separator between each.
+examples:
+- context: ["a", "b"]
+  args: [", ", @]
+  returns: "a, b"
+- context: ["a", "b"]
+  args: ["", @]
+  returns: "ab"
+- context: ["a", false, "b"]
+  args: [", ", @]
+  returns: "<error: invalid-type>"
+- context: [false]
+  args: [", ", @]
+  returns: "<error: invalid-type>"

functions/keys.yml

@@ -0,0 +1,30 @@
+name: keys
+topic:
+args:
+  required:
+  - name: obj
+    type: [object]
+    desc:
+  optional: []
+returns:
+  type: array
+  desc:
+desc: |
+  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.
+examples:
+- context: {"foo": "baz", "bar": "bam"}
+  args: [@]
+  returns: ["foo", "bar"]
+- context: {}
+  args: [@]
+  returns: []
+- context: false
+  args: [@]
+  returns: "<error: invalid-type>"
+- context: [b, a, c]
+  args: [@]
+  returns: "<error: invalid-type>"

functions/length.yml

@@ -0,0 +1,44 @@
+name: length
+topic:
+args:
+  required:
+  - name: subject
+    type: [string, array, object]
+    desc:
+  optional: []
+returns:
+  type: number
+  desc:
+desc: |
+  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
+examples:
+- context: None
+  args: [abc]
+  returns: 3
+- context: None
+  args: [@]
+  returns: 7
+- context: None
+  args: [not_there]
+  returns: "<error: invalid-type>"
+- context: ["a", "b", "c"]
+  args: [@]
+  returns: 3
+- context: []
+  args: [@]
+  returns: 0
+- context: {}
+  args: [@]
+  returns: 0
+- context: {"foo": "bar", "baz": "bam"}
+  args: [@]
+  returns: 2