From 1a65324750e377b40ad27fb1c5d3496c86f27973 Mon Sep 17 00:00:00 2001
From: Anton Gilgur <agilgur5@gmail.com>
Date: Wed, 4 Oct 2023 13:29:20 -0400
Subject: [PATCH 1/4] docs: categorize Language Definition functions

- multi-type / misc functions
- Type Conversion functions
- String functions
- Date functions
- Number functions
- Array functions
- Map functions

- also consistently use `str`, `array`, `n`, `v` for the variable name when referring to a specific type
  - `array` was used consistently for older functions, but not some newer ones
  - `str` added to match `array`
  - `n` was sometimes used for numbers or ints, but not always
  - `v` is for multi-type "values"

Signed-off-by: Anton Gilgur <agilgur5@gmail.com>
---
 docs/Language-Definition.md | 418 +++++++++++++++++++-----------------
 1 file changed, 215 insertions(+), 203 deletions(-)

diff --git a/docs/Language-Definition.md b/docs/Language-Definition.md
index 026d1fe26..05cc8c118 100644
--- a/docs/Language-Definition.md
+++ b/docs/Language-Definition.md
@@ -205,161 +205,129 @@ date("2023-08-14") - date("2023-08-13") == duration("24h")
 
 ## Built-in Functions
 
-### all(array, predicate)
-
-Returns **true** if all elements satisfies the [predicate](#predicate).
-If the array is empty, returns **true**.
-
-```expr
-all(tweets, {.Size < 280})
-```
-
-### any(array, predicate)
+### len(v)
 
-Returns **true** if any elements satisfies the [predicate](#predicate).
-If the array is empty, returns **false**.
+Returns the length of an array, a map or a string.
 
-### one(array, predicate)
+### get(v, index)
 
-Returns **true** if _exactly one_ element satisfies the [predicate](#predicate).
-If the array is empty, returns **false**.
+Retrieves the element at the specified index from an array or map `v`. If the index is out of range, returns `nil`.
+Or the key does not exist, returns `nil`.
 
 ```expr
-one(participants, {.Winner})
+get([1, 2, 3], 1) == 2
+get({"name": "John", "age": 30}, "name") == "John"
 ```
 
-### none(array, predicate)
-
-Returns **true** if _all elements does not_ satisfy the [predicate](#predicate).
-If the array is empty, returns **true**.
+#### Type Conversion Functions
 
-### map(array, predicate)
+#### type(v)
 
-Returns new array by applying the [predicate](#predicate) to each element of
-the array.
+Returns the type of the given value `v`.
+Returns on of the following types: `nil`, `bool`, `int`, `uint`, `float`, `string`, `array`, `map`.
+For named types and structs, the type name is returned.
 
 ```expr
-map(tweets, {.Size})
+type(42) == "int"
+type("hello") == "string"
+type(now()) == "time.Time"
 ```
 
-### filter(array, predicate)
+#### int(v)
 
-Returns new array by filtering elements of the array by [predicate](#predicate).
+Returns the integer value of a number or a string.
 
 ```expr
-filter(users, .Name startsWith "J")
+int("123") == 123
 ```
 
-### find(array, predicate)
+#### float(v)
 
-Finds the first element in an array that satisfies the [predicate](#predicate).
+Returns the float value of a number or a string.
+
+#### string(v)
+
+Converts the given value `v` into a string representation.
 
 ```expr
-find([1, 2, 3, 4], # > 2) == 3
+string(123) == "123"
 ```
 
-### findIndex(array, predicate)
+#### toJSON(v)
 
-Finds the index of the first element in an array that satisfies the [predicate](#predicate).
+Converts the given value `v` to its JSON string representation.
 
 ```expr
-findIndex([1, 2, 3, 4], # > 2) == 2
+toJSON({"name": "John", "age": 30})
 ```
 
-### findLast(array, predicate)
+#### fromJSON(v)
 
-Finds the last element in an array that satisfies the [predicate](#predicate).
+Parses the given JSON string `v` and returns the corresponding value.
 
 ```expr
-findLast([1, 2, 3, 4], # > 2) == 4
+fromJSON('{"name": "John", "age": 30}')
 ```
 
-### findLastIndex(array, predicate)
+#### toBase64(v)
 
-Finds the index of the last element in an array that satisfies the [predicate](#predicate).
+Encodes the string `v` into Base64 format.
 
 ```expr
-findLastIndex([1, 2, 3, 4], # > 2) == 3
+toBase64("Hello World") == "SGVsbG8gV29ybGQ="
 ```
 
-### groupBy(array, predicate)
+#### fromBase64(v)
 
-Groups the elements of an array by the result of the [predicate](#predicate).
+Decodes the Base64 encoded string `v` back to its original form.
 
 ```expr
-groupBy(users, .Age)
+fromBase64("SGVsbG8gV29ybGQ=") == "Hello World"
 ```
 
-### count(array, predicate)
-
-Returns the number of elements what satisfies the [predicate](#predicate).
+#### toPairs(map)
 
-Equivalent to:
+Converts a map to an array of key-value pairs.
 
 ```expr
-len(filter(array, predicate))
+toPairs({"name": "John", "age": 30}) == [["name", "John"], ["age", 30]]
 ```
 
-### reduce(array, predicate[, initialValue])
-
-Applies a predicate to each element in the array, reducing the array to a single value.
-Optional `initialValue` argument can be used to specify the initial value of the accumulator.
-If `initialValue` is not given, the first element of the array is used as the initial value.
-
-Following variables are available in the predicate:
+#### fromPairs(array)
 
-- `#` - the current element
-- `#acc` - the accumulator
-- `#index` - the index of the current element
+Converts an array of key-value pairs to a map.
 
 ```expr
-reduce(1..9, #acc + #)
-reduce(1..9, #acc + #, 0)
+fromPairs([["name", "John"], ["age", 30]]) == {"name": "John", "age": 30}
 ```
 
-### len(v)
+### Number Functions
 
-Returns the length of an array, a map or a string.
+#### max(n1, n2)
 
-### type(v)
-
-Returns the type of the given value `v`.
-Returns on of the following types: `nil`, `bool`, `int`, `uint`, `float`, `string`, `array`, `map`.
-For named types and structs, the type name is returned.
+Returns the maximum of the two numbers `n1` and `n2`.
 
 ```expr
-type(42) == "int"
-type("hello") == "string"
-type(now()) == "time.Time"
+max(5, 7) == 7
 ```
 
-### abs(v)
-
-Returns the absolute value of a number.
-
-### int(v)
+#### min(n1, n2)
 
-Returns the integer value of a number or a string.
+Returns the minimum of the two numbers `n1` and `n2`.
 
 ```expr
-int("123") == 123
+min(5, 7) == 5
 ```
 
-### float(v)
-
-Returns the float value of a number or a string.
-
-### string(v)
+#### abs(n)
 
-Converts the given value `v` into a string representation.
+Returns the absolute value of a number.
 
-```expr
-string(123) == "123"
-```
+### String Functions
 
-### trim(v[, chars])
+#### trim(str[, chars])
 
-Removes white spaces from both ends of a string `v`.
+Removes white spaces from both ends of a string `str`.
 If the optional `chars` argument is given, it is a string specifying the set of characters to be removed.
 
 ```expr
@@ -367,298 +335,324 @@ trim("  Hello  ") == "Hello"
 trim("__Hello__", "_") == "Hello"
 ```
 
-### trimPrefix(v, prefix)
+#### trimPrefix(str, prefix)
 
-Removes the specified prefix from the string `v` if it starts with that prefix.
+Removes the specified prefix from the string `str` if it starts with that prefix.
 
 ```expr
 trimPrefix("HelloWorld", "Hello") == "World"
 ```
 
-### trimSuffix(v, suffix)
+#### trimSuffix(str, suffix)
 
-Removes the specified suffix from the string `v` if it ends with that suffix.
+Removes the specified suffix from the string `str` if it ends with that suffix.
 
 ```expr
 trimSuffix("HelloWorld", "World") == "Hello"
 ```
 
-### upper(v)
+#### upper(str)
 
-Converts all the characters in string `v` to uppercase.
+Converts all the characters in string `str` to uppercase.
 
 ```expr
 upper("hello") == "HELLO"
 ```
 
-### lower(v)
+#### lower(str)
 
-Converts all the characters in string `v` to lowercase.
+Converts all the characters in string `str` to lowercase.
 
 ```expr
 lower("HELLO") == "hello"
 ```
 
-### split(v, delimiter[, n])
+#### split(str, delimiter[, n])
 
-Splits the string `v` at each instance of the delimiter and returns an array of substrings.
+Splits the string `str` at each instance of the delimiter and returns an array of substrings.
 
 ```expr
 split("apple,orange,grape", ",") == ["apple", "orange", "grape"]
 split("apple,orange,grape", ",", 2) == ["apple", "orange,grape"]
 ```
 
-### splitAfter(v, delimiter[, n])
+#### splitAfter(str, delimiter[, n])
 
-Splits the string `v` after each instance of the delimiter.
+Splits the string `str` after each instance of the delimiter.
 
 ```expr
 splitAfter("apple,orange,grape", ",") == ["apple,", "orange,", "grape"]
 splitAfter("apple,orange,grape", ",", 2) == ["apple,", "orange,grape"]
 ```
 
-### replace(v, old, new)
+#### replace(str, old, new)
 
-Replaces all occurrences of `old` in string `v` with `new`.
+Replaces all occurrences of `old` in string `str` with `new`.
 
 ```expr
 replace("Hello World", "World", "Universe") == "Hello Universe"
 ```
 
-### repeat(v, n)
+#### repeat(str, n)
 
-Repeats the string `v` `n` times.
+Repeats the string `str` `n` times.
 
 ```expr
 repeat("Hi", 3) == "HiHiHi"
 ```
 
-### join(v[, delimiter])
+#### indexOf(str, substring)
 
-Joins an array of strings `v` into a single string with the given delimiter.
-If no delimiter is given, an empty string is used.
-
-```expr
-join(["apple", "orange", "grape"], ",") == "apple,orange,grape"
-join(["apple", "orange", "grape"]) == "appleorangegrape"
-```
-
-### indexOf(v, substring)
-
-Returns the index of the first occurrence of the substring in string `v` or -1 if not found.
+Returns the index of the first occurrence of the substring in string `str` or -1 if not found.
 
 ```expr
 indexOf("apple pie", "pie") == 6
 ```
 
-### lastIndexOf(v, substring)
+#### lastIndexOf(str, substring)
 
-Returns the index of the last occurrence of the substring in string `v` or -1 if not found.
+Returns the index of the last occurrence of the substring in string `str` or -1 if not found.
 
 ```expr
 lastIndexOf("apple pie apple", "apple") == 10
 ```
 
-### hasPrefix(v, prefix)
+#### hasPrefix(str, prefix)
 
-Returns `true` if string `v` starts with the given prefix.
+Returns `true` if string `str` starts with the given prefix.
 
 ```expr
 hasPrefix("HelloWorld", "Hello") == true
 ```
 
-### hasSuffix(v, suffix)
+#### hasSuffix(str, suffix)
 
-Returns `true` if string `v` ends with the given suffix.
+Returns `true` if string `str` ends with the given suffix.
 
 ```expr
 hasSuffix("HelloWorld", "World") == true
 ```
 
-### max(v1, v2)
+### Date Functions
 
-Returns the maximum of the two values `v1` and `v2`.
+#### now()
+
+Returns the current date and time.
 
 ```expr
-max(5, 7) == 7
+createdAt > now() - duration(1h)
 ```
 
-### min(v1, v2)
+#### duration(str)
 
-Returns the minimum of the two values `v1` and `v2`.
+Returns [time.Duration](https://pkg.go.dev/time#Duration) value of the given string `str`.
+
+Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
 
 ```expr
-min(5, 7) == 5
+duration("1h").Seconds() == 3600
 ```
 
-### sum(array)
+#### date(str[, format[, timezone]])
 
-Returns the sum of all numbers in the array.
+Converts the given string `str` into a date representation.
+
+If the optional `format` argument is given, it is a string specifying the format of the date.
+The format string uses the same formatting rules as the standard
+Go [time package](https://pkg.go.dev/time#pkg-constants).
+
+If the optional `timezone` argument is given, it is a string specifying the timezone of the date.
+
+If the `format` argument is not given, the `v` argument must be in one of the following formats:
+
+- 2006-01-02
+- 15:04:05
+- 2006-01-02 15:04:05
+- RFC3339
+- RFC822,
+- RFC850,
+- RFC1123,
 
 ```expr
-sum([1, 2, 3]) == 6
+date("2023-08-14")
+date("15:04:05")
+date("2023-08-14T00:00:00Z")
+date("2023-08-14 00:00:00", "2006-01-02 15:04:05", "Europe/Zurich")
 ```
 
-### mean(array)
+### Array Functions
 
-Returns the average of all numbers in the array.
+#### all(array, predicate)
+
+Returns **true** if all elements satisfies the [predicate](#predicate).
+If the array is empty, returns **true**.
 
 ```expr
-mean([1, 2, 3]) == 2.0
+all(tweets, {.Size < 280})
 ```
 
-### median(array)
+#### any(array, predicate)
 
-Returns the median of all numbers in the array.
+Returns **true** if any elements satisfies the [predicate](#predicate).
+If the array is empty, returns **false**.
+
+#### one(array, predicate)
+
+Returns **true** if _exactly one_ element satisfies the [predicate](#predicate).
+If the array is empty, returns **false**.
 
 ```expr
-median([1, 2, 3]) == 2.0
+one(participants, {.Winner})
 ```
 
-### toJSON(v)
+#### none(array, predicate)
 
-Converts the given value `v` to its JSON string representation.
+Returns **true** if _all elements does not_ satisfy the [predicate](#predicate).
+If the array is empty, returns **true**.
+
+#### map(array, predicate)
+
+Returns new array by applying the [predicate](#predicate) to each element of
+the array.
 
 ```expr
-toJSON({"name": "John", "age": 30})
+map(tweets, {.Size})
 ```
 
-### fromJSON(v)
+#### filter(array, predicate)
 
-Parses the given JSON string `v` and returns the corresponding value.
+Returns new array by filtering elements of the array by [predicate](#predicate).
 
 ```expr
-fromJSON('{"name": "John", "age": 30}')
+filter(users, .Name startsWith "J")
 ```
 
-### toBase64(v)
+#### find(array, predicate)
 
-Encodes the string `v` into Base64 format.
+Finds the first element in an array that satisfies the [predicate](#predicate).
 
 ```expr
-toBase64("Hello World") == "SGVsbG8gV29ybGQ="
+find([1, 2, 3, 4], # > 2) == 3
 ```
 
-### fromBase64(v)
+#### findIndex(array, predicate)
 
-Decodes the Base64 encoded string `v` back to its original form.
+Finds the index of the first element in an array that satisfies the [predicate](#predicate).
 
 ```expr
-fromBase64("SGVsbG8gV29ybGQ=") == "Hello World"
+findIndex([1, 2, 3, 4], # > 2) == 2
 ```
 
-### now()
+#### findLast(array, predicate)
 
-Returns the current date and time.
+Finds the last element in an array that satisfies the [predicate](#predicate).
 
 ```expr
-createdAt > now() - duration(1h)
+findLast([1, 2, 3, 4], # > 2) == 4
 ```
 
-### duration(v)
+#### findLastIndex(array, predicate)
 
-Returns [time.Duration](https://pkg.go.dev/time#Duration) value of the given string `v`.
-
-Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
+Finds the index of the last element in an array that satisfies the [predicate](#predicate).
 
 ```expr
-duration("1h").Seconds() == 3600
+findLastIndex([1, 2, 3, 4], # > 2) == 3
 ```
 
-### date(v[, format[, timezone]])
+#### groupBy(array, predicate)
 
-Converts the given value `v` into a date representation.
+Groups the elements of an array by the result of the [predicate](#predicate).
 
-If the optional `format` argument is given, it is a string specifying the format of the date.
-The format string uses the same formatting rules as the standard
-Go [time package](https://pkg.go.dev/time#pkg-constants).
+```expr
+groupBy(users, .Age)
+```
 
-If the optional `timezone` argument is given, it is a string specifying the timezone of the date.
+#### count(array, predicate)
 
-If the `format` argument is not given, the `v` argument must be in one of the following formats:
+Returns the number of elements what satisfies the [predicate](#predicate).
 
-- 2006-01-02
-- 15:04:05
-- 2006-01-02 15:04:05
-- RFC3339
-- RFC822,
-- RFC850,
-- RFC1123,
+Equivalent to:
 
 ```expr
-date("2023-08-14")
-date("15:04:05")
-date("2023-08-14T00:00:00Z")
-date("2023-08-14 00:00:00", "2006-01-02 15:04:05", "Europe/Zurich")
+len(filter(array, predicate))
 ```
 
-### first(v)
+#### join(array[, delimiter])
 
-Returns the first element from an array `v`. If the array is empty, returns `nil`.
+Joins an array of strings into a single string with the given delimiter.
+If no delimiter is given, an empty string is used.
 
 ```expr
-first([1, 2, 3]) == 1
+join(["apple", "orange", "grape"], ",") == "apple,orange,grape"
+join(["apple", "orange", "grape"]) == "appleorangegrape"
 ```
 
-### last(v)
+#### reduce(array, predicate[, initialValue])
 
-Returns the last element from an array `v`. If the array is empty, returns `nil`.
+Applies a predicate to each element in the array, reducing the array to a single value.
+Optional `initialValue` argument can be used to specify the initial value of the accumulator.
+If `initialValue` is not given, the first element of the array is used as the initial value.
+
+Following variables are available in the predicate:
+
+- `#` - the current element
+- `#acc` - the accumulator
+- `#index` - the index of the current element
 
 ```expr
-last([1, 2, 3]) == 3
+reduce(1..9, #acc + #)
+reduce(1..9, #acc + #, 0)
 ```
 
-### get(v, index)
+#### sum(array)
 
-Retrieves the element at the specified index from an array or map `v`. If the index is out of range, returns `nil`.
-Or the key does not exist, returns `nil`.
+Returns the sum of all numbers in the array.
 
 ```expr
-get([1, 2, 3], 1) == 2
-get({"name": "John", "age": 30}, "name") == "John"
+sum([1, 2, 3]) == 6
 ```
 
-### take(array, n)
+#### mean(array)
 
-Returns the first `n` elements from an array. If the array has fewer than `n` elements, returns the whole array.
+Returns the average of all numbers in the array.
 
 ```expr
-take([1, 2, 3, 4], 2) == [1, 2]
+mean([1, 2, 3]) == 2.0
 ```
 
-### keys(map)
+#### median(array)
 
-Returns an array containing the keys of the map.
+Returns the median of all numbers in the array.
 
 ```expr
-keys({"name": "John", "age": 30}) == ["name", "age"]
+median([1, 2, 3]) == 2.0
 ```
 
-### values(map)
+#### first(array)
 
-Returns an array containing the values of the map.
+Returns the first element from an array. If the array is empty, returns `nil`.
 
 ```expr
-values({"name": "John", "age": 30}) == ["John", 30]
+first([1, 2, 3]) == 1
 ```
 
-### toPairs(map)
+#### last(array)
 
-Converts a map to an array of key-value pairs.
+Returns the last element from an array. If the array is empty, returns `nil`.
 
 ```expr
-toPairs({"name": "John", "age": 30}) == [["name", "John"], ["age", 30]]
+last([1, 2, 3]) == 3
 ```
 
-### fromPairs(array)
+#### take(array, n)
 
-Converts an array of key-value pairs to a map.
+Returns the first `n` elements from an array. If the array has fewer than `n` elements, returns the whole array.
 
 ```expr
-fromPairs([["name", "John"], ["age", 30]]) == {"name": "John", "age": 30}
+take([1, 2, 3, 4], 2) == [1, 2]
 ```
 
-### sort(array[, order])
+#### sort(array[, order])
 
 Sorts an array in ascending order. Optional `order` argument can be used to specify the order of sorting: `asc`
 or `desc`.
@@ -668,7 +662,7 @@ sort([3, 1, 4]) == [1, 3, 4]
 sort([3, 1, 4], "desc") == [4, 3, 1]
 ```
 
-### sortBy(array, key[, order])
+#### sortBy(array, key[, order])
 
 Sorts an array of maps by a specific key in ascending order. Optional `order` argument can be used to specify the order
 of sorting: `asc` or `desc`.
@@ -678,10 +672,28 @@ sortBy(users, "Age")
 sortBy(users, "Age", "desc")
 ```
 
+### Map Functions
+
+#### keys(map)
+
+Returns an array containing the keys of the map.
+
+```expr
+keys({"name": "John", "age": 30}) == ["name", "age"]
+```
+
+#### values(map)
+
+Returns an array containing the values of the map.
+
+```expr
+values({"name": "John", "age": 30}) == ["John", 30]
+```
+
 ## Predicate
 
 The predicate is an expression. It takes one or more arguments and returns a boolean value.
-To access the arguments, the `#` symbol is used. 
+To access the arguments, the `#` symbol is used.
 
 ```expr
 map(0..9, {# / 2})

From 5ebfba93c1fa41e1065e99b32c607ff6b7fd36ac Mon Sep 17 00:00:00 2001
From: Anton Gilgur <agilgur5@gmail.com>
Date: Wed, 4 Oct 2023 16:22:19 -0400
Subject: [PATCH 2/4] review feedback -- categories to h2

- categories to h2, individual functions to h3 per review feedback

- rename "Built-in Functions" -> "Miscellaneous Functions" as this is now only around the uncategorized functions
  - move this to the bottom of the function list as well so that "miscellaneous" is not first

- combine "Date Manipulation" with "Date Functions"

Signed-off-by: Anton Gilgur <agilgur5@gmail.com>
---
 docs/Language-Definition.md | 168 ++++++++++++++++++------------------
 1 file changed, 83 insertions(+), 85 deletions(-)

diff --git a/docs/Language-Definition.md b/docs/Language-Definition.md
index 05cc8c118..118605a33 100644
--- a/docs/Language-Definition.md
+++ b/docs/Language-Definition.md
@@ -193,35 +193,9 @@ For example, expression `split(lower(user.Name), " ")` can be written as:
 user.Name | lower() | split(" ")
 ```
 
-### Date Manipulation
+## Type Conversion Functions
 
-The following operators can be used to manipulate dates:
-
-```expr
-date("2023-08-14") + duration("1h")
-date("2023-08-14") - duration("1h")
-date("2023-08-14") - date("2023-08-13") == duration("24h")
-```
-
-## Built-in Functions
-
-### len(v)
-
-Returns the length of an array, a map or a string.
-
-### get(v, index)
-
-Retrieves the element at the specified index from an array or map `v`. If the index is out of range, returns `nil`.
-Or the key does not exist, returns `nil`.
-
-```expr
-get([1, 2, 3], 1) == 2
-get({"name": "John", "age": 30}, "name") == "John"
-```
-
-#### Type Conversion Functions
-
-#### type(v)
+### type(v)
 
 Returns the type of the given value `v`.
 Returns on of the following types: `nil`, `bool`, `int`, `uint`, `float`, `string`, `array`, `map`.
@@ -233,7 +207,7 @@ type("hello") == "string"
 type(now()) == "time.Time"
 ```
 
-#### int(v)
+### int(v)
 
 Returns the integer value of a number or a string.
 
@@ -241,11 +215,11 @@ Returns the integer value of a number or a string.
 int("123") == 123
 ```
 
-#### float(v)
+### float(v)
 
 Returns the float value of a number or a string.
 
-#### string(v)
+### string(v)
 
 Converts the given value `v` into a string representation.
 
@@ -253,7 +227,7 @@ Converts the given value `v` into a string representation.
 string(123) == "123"
 ```
 
-#### toJSON(v)
+### toJSON(v)
 
 Converts the given value `v` to its JSON string representation.
 
@@ -261,7 +235,7 @@ Converts the given value `v` to its JSON string representation.
 toJSON({"name": "John", "age": 30})
 ```
 
-#### fromJSON(v)
+### fromJSON(v)
 
 Parses the given JSON string `v` and returns the corresponding value.
 
@@ -269,7 +243,7 @@ Parses the given JSON string `v` and returns the corresponding value.
 fromJSON('{"name": "John", "age": 30}')
 ```
 
-#### toBase64(v)
+### toBase64(v)
 
 Encodes the string `v` into Base64 format.
 
@@ -277,7 +251,7 @@ Encodes the string `v` into Base64 format.
 toBase64("Hello World") == "SGVsbG8gV29ybGQ="
 ```
 
-#### fromBase64(v)
+### fromBase64(v)
 
 Decodes the Base64 encoded string `v` back to its original form.
 
@@ -285,7 +259,7 @@ Decodes the Base64 encoded string `v` back to its original form.
 fromBase64("SGVsbG8gV29ybGQ=") == "Hello World"
 ```
 
-#### toPairs(map)
+### toPairs(map)
 
 Converts a map to an array of key-value pairs.
 
@@ -293,7 +267,7 @@ Converts a map to an array of key-value pairs.
 toPairs({"name": "John", "age": 30}) == [["name", "John"], ["age", 30]]
 ```
 
-#### fromPairs(array)
+### fromPairs(array)
 
 Converts an array of key-value pairs to a map.
 
@@ -301,9 +275,9 @@ Converts an array of key-value pairs to a map.
 fromPairs([["name", "John"], ["age", 30]]) == {"name": "John", "age": 30}
 ```
 
-### Number Functions
+## Number Functions
 
-#### max(n1, n2)
+### max(n1, n2)
 
 Returns the maximum of the two numbers `n1` and `n2`.
 
@@ -311,7 +285,7 @@ Returns the maximum of the two numbers `n1` and `n2`.
 max(5, 7) == 7
 ```
 
-#### min(n1, n2)
+### min(n1, n2)
 
 Returns the minimum of the two numbers `n1` and `n2`.
 
@@ -319,13 +293,13 @@ Returns the minimum of the two numbers `n1` and `n2`.
 min(5, 7) == 5
 ```
 
-#### abs(n)
+### abs(n)
 
 Returns the absolute value of a number.
 
-### String Functions
+## String Functions
 
-#### trim(str[, chars])
+### trim(str[, chars])
 
 Removes white spaces from both ends of a string `str`.
 If the optional `chars` argument is given, it is a string specifying the set of characters to be removed.
@@ -335,7 +309,7 @@ trim("  Hello  ") == "Hello"
 trim("__Hello__", "_") == "Hello"
 ```
 
-#### trimPrefix(str, prefix)
+### trimPrefix(str, prefix)
 
 Removes the specified prefix from the string `str` if it starts with that prefix.
 
@@ -343,7 +317,7 @@ Removes the specified prefix from the string `str` if it starts with that prefix
 trimPrefix("HelloWorld", "Hello") == "World"
 ```
 
-#### trimSuffix(str, suffix)
+### trimSuffix(str, suffix)
 
 Removes the specified suffix from the string `str` if it ends with that suffix.
 
@@ -351,7 +325,7 @@ Removes the specified suffix from the string `str` if it ends with that suffix.
 trimSuffix("HelloWorld", "World") == "Hello"
 ```
 
-#### upper(str)
+### upper(str)
 
 Converts all the characters in string `str` to uppercase.
 
@@ -359,7 +333,7 @@ Converts all the characters in string `str` to uppercase.
 upper("hello") == "HELLO"
 ```
 
-#### lower(str)
+### lower(str)
 
 Converts all the characters in string `str` to lowercase.
 
@@ -367,7 +341,7 @@ Converts all the characters in string `str` to lowercase.
 lower("HELLO") == "hello"
 ```
 
-#### split(str, delimiter[, n])
+### split(str, delimiter[, n])
 
 Splits the string `str` at each instance of the delimiter and returns an array of substrings.
 
@@ -376,7 +350,7 @@ split("apple,orange,grape", ",") == ["apple", "orange", "grape"]
 split("apple,orange,grape", ",", 2) == ["apple", "orange,grape"]
 ```
 
-#### splitAfter(str, delimiter[, n])
+### splitAfter(str, delimiter[, n])
 
 Splits the string `str` after each instance of the delimiter.
 
@@ -385,7 +359,7 @@ splitAfter("apple,orange,grape", ",") == ["apple,", "orange,", "grape"]
 splitAfter("apple,orange,grape", ",", 2) == ["apple,", "orange,grape"]
 ```
 
-#### replace(str, old, new)
+### replace(str, old, new)
 
 Replaces all occurrences of `old` in string `str` with `new`.
 
@@ -393,7 +367,7 @@ Replaces all occurrences of `old` in string `str` with `new`.
 replace("Hello World", "World", "Universe") == "Hello Universe"
 ```
 
-#### repeat(str, n)
+### repeat(str, n)
 
 Repeats the string `str` `n` times.
 
@@ -401,7 +375,7 @@ Repeats the string `str` `n` times.
 repeat("Hi", 3) == "HiHiHi"
 ```
 
-#### indexOf(str, substring)
+### indexOf(str, substring)
 
 Returns the index of the first occurrence of the substring in string `str` or -1 if not found.
 
@@ -409,7 +383,7 @@ Returns the index of the first occurrence of the substring in string `str` or -1
 indexOf("apple pie", "pie") == 6
 ```
 
-#### lastIndexOf(str, substring)
+### lastIndexOf(str, substring)
 
 Returns the index of the last occurrence of the substring in string `str` or -1 if not found.
 
@@ -417,7 +391,7 @@ Returns the index of the last occurrence of the substring in string `str` or -1
 lastIndexOf("apple pie apple", "apple") == 10
 ```
 
-#### hasPrefix(str, prefix)
+### hasPrefix(str, prefix)
 
 Returns `true` if string `str` starts with the given prefix.
 
@@ -425,7 +399,7 @@ Returns `true` if string `str` starts with the given prefix.
 hasPrefix("HelloWorld", "Hello") == true
 ```
 
-#### hasSuffix(str, suffix)
+### hasSuffix(str, suffix)
 
 Returns `true` if string `str` ends with the given suffix.
 
@@ -433,9 +407,17 @@ Returns `true` if string `str` ends with the given suffix.
 hasSuffix("HelloWorld", "World") == true
 ```
 
-### Date Functions
+## Date Functions
 
-#### now()
+The following operators can be used to manipulate dates:
+
+```expr
+date("2023-08-14") + duration("1h")
+date("2023-08-14") - duration("1h")
+date("2023-08-14") - date("2023-08-13") == duration("24h")
+```
+
+### now()
 
 Returns the current date and time.
 
@@ -443,7 +425,7 @@ Returns the current date and time.
 createdAt > now() - duration(1h)
 ```
 
-#### duration(str)
+### duration(str)
 
 Returns [time.Duration](https://pkg.go.dev/time#Duration) value of the given string `str`.
 
@@ -453,7 +435,7 @@ Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
 duration("1h").Seconds() == 3600
 ```
 
-#### date(str[, format[, timezone]])
+### date(str[, format[, timezone]])
 
 Converts the given string `str` into a date representation.
 
@@ -480,9 +462,9 @@ date("2023-08-14T00:00:00Z")
 date("2023-08-14 00:00:00", "2006-01-02 15:04:05", "Europe/Zurich")
 ```
 
-### Array Functions
+## Array Functions
 
-#### all(array, predicate)
+### all(array, predicate)
 
 Returns **true** if all elements satisfies the [predicate](#predicate).
 If the array is empty, returns **true**.
@@ -491,12 +473,12 @@ If the array is empty, returns **true**.
 all(tweets, {.Size < 280})
 ```
 
-#### any(array, predicate)
+### any(array, predicate)
 
 Returns **true** if any elements satisfies the [predicate](#predicate).
 If the array is empty, returns **false**.
 
-#### one(array, predicate)
+### one(array, predicate)
 
 Returns **true** if _exactly one_ element satisfies the [predicate](#predicate).
 If the array is empty, returns **false**.
@@ -505,12 +487,12 @@ If the array is empty, returns **false**.
 one(participants, {.Winner})
 ```
 
-#### none(array, predicate)
+### none(array, predicate)
 
 Returns **true** if _all elements does not_ satisfy the [predicate](#predicate).
 If the array is empty, returns **true**.
 
-#### map(array, predicate)
+### map(array, predicate)
 
 Returns new array by applying the [predicate](#predicate) to each element of
 the array.
@@ -519,7 +501,7 @@ the array.
 map(tweets, {.Size})
 ```
 
-#### filter(array, predicate)
+### filter(array, predicate)
 
 Returns new array by filtering elements of the array by [predicate](#predicate).
 
@@ -527,7 +509,7 @@ Returns new array by filtering elements of the array by [predicate](#predicate).
 filter(users, .Name startsWith "J")
 ```
 
-#### find(array, predicate)
+### find(array, predicate)
 
 Finds the first element in an array that satisfies the [predicate](#predicate).
 
@@ -535,7 +517,7 @@ Finds the first element in an array that satisfies the [predicate](#predicate).
 find([1, 2, 3, 4], # > 2) == 3
 ```
 
-#### findIndex(array, predicate)
+### findIndex(array, predicate)
 
 Finds the index of the first element in an array that satisfies the [predicate](#predicate).
 
@@ -543,7 +525,7 @@ Finds the index of the first element in an array that satisfies the [predicate](
 findIndex([1, 2, 3, 4], # > 2) == 2
 ```
 
-#### findLast(array, predicate)
+### findLast(array, predicate)
 
 Finds the last element in an array that satisfies the [predicate](#predicate).
 
@@ -551,7 +533,7 @@ Finds the last element in an array that satisfies the [predicate](#predicate).
 findLast([1, 2, 3, 4], # > 2) == 4
 ```
 
-#### findLastIndex(array, predicate)
+### findLastIndex(array, predicate)
 
 Finds the index of the last element in an array that satisfies the [predicate](#predicate).
 
@@ -559,7 +541,7 @@ Finds the index of the last element in an array that satisfies the [predicate](#
 findLastIndex([1, 2, 3, 4], # > 2) == 3
 ```
 
-#### groupBy(array, predicate)
+### groupBy(array, predicate)
 
 Groups the elements of an array by the result of the [predicate](#predicate).
 
@@ -567,7 +549,7 @@ Groups the elements of an array by the result of the [predicate](#predicate).
 groupBy(users, .Age)
 ```
 
-#### count(array, predicate)
+### count(array, predicate)
 
 Returns the number of elements what satisfies the [predicate](#predicate).
 
@@ -577,7 +559,7 @@ Equivalent to:
 len(filter(array, predicate))
 ```
 
-#### join(array[, delimiter])
+### join(array[, delimiter])
 
 Joins an array of strings into a single string with the given delimiter.
 If no delimiter is given, an empty string is used.
@@ -587,7 +569,7 @@ join(["apple", "orange", "grape"], ",") == "apple,orange,grape"
 join(["apple", "orange", "grape"]) == "appleorangegrape"
 ```
 
-#### reduce(array, predicate[, initialValue])
+### reduce(array, predicate[, initialValue])
 
 Applies a predicate to each element in the array, reducing the array to a single value.
 Optional `initialValue` argument can be used to specify the initial value of the accumulator.
@@ -604,7 +586,7 @@ reduce(1..9, #acc + #)
 reduce(1..9, #acc + #, 0)
 ```
 
-#### sum(array)
+### sum(array)
 
 Returns the sum of all numbers in the array.
 
@@ -612,7 +594,7 @@ Returns the sum of all numbers in the array.
 sum([1, 2, 3]) == 6
 ```
 
-#### mean(array)
+### mean(array)
 
 Returns the average of all numbers in the array.
 
@@ -620,7 +602,7 @@ Returns the average of all numbers in the array.
 mean([1, 2, 3]) == 2.0
 ```
 
-#### median(array)
+### median(array)
 
 Returns the median of all numbers in the array.
 
@@ -628,7 +610,7 @@ Returns the median of all numbers in the array.
 median([1, 2, 3]) == 2.0
 ```
 
-#### first(array)
+### first(array)
 
 Returns the first element from an array. If the array is empty, returns `nil`.
 
@@ -636,7 +618,7 @@ Returns the first element from an array. If the array is empty, returns `nil`.
 first([1, 2, 3]) == 1
 ```
 
-#### last(array)
+### last(array)
 
 Returns the last element from an array. If the array is empty, returns `nil`.
 
@@ -644,7 +626,7 @@ Returns the last element from an array. If the array is empty, returns `nil`.
 last([1, 2, 3]) == 3
 ```
 
-#### take(array, n)
+### take(array, n)
 
 Returns the first `n` elements from an array. If the array has fewer than `n` elements, returns the whole array.
 
@@ -652,7 +634,7 @@ Returns the first `n` elements from an array. If the array has fewer than `n` el
 take([1, 2, 3, 4], 2) == [1, 2]
 ```
 
-#### sort(array[, order])
+### sort(array[, order])
 
 Sorts an array in ascending order. Optional `order` argument can be used to specify the order of sorting: `asc`
 or `desc`.
@@ -662,7 +644,7 @@ sort([3, 1, 4]) == [1, 3, 4]
 sort([3, 1, 4], "desc") == [4, 3, 1]
 ```
 
-#### sortBy(array, key[, order])
+### sortBy(array, key[, order])
 
 Sorts an array of maps by a specific key in ascending order. Optional `order` argument can be used to specify the order
 of sorting: `asc` or `desc`.
@@ -672,9 +654,9 @@ sortBy(users, "Age")
 sortBy(users, "Age", "desc")
 ```
 
-### Map Functions
+## Map Functions
 
-#### keys(map)
+### keys(map)
 
 Returns an array containing the keys of the map.
 
@@ -682,7 +664,7 @@ Returns an array containing the keys of the map.
 keys({"name": "John", "age": 30}) == ["name", "age"]
 ```
 
-#### values(map)
+### values(map)
 
 Returns an array containing the values of the map.
 
@@ -690,6 +672,22 @@ Returns an array containing the values of the map.
 values({"name": "John", "age": 30}) == ["John", 30]
 ```
 
+## Miscellaneous Functions
+
+### len(v)
+
+Returns the length of an array, a map or a string.
+
+### get(v, index)
+
+Retrieves the element at the specified index from an array or map `v`. If the index is out of range, returns `nil`.
+Or the key does not exist, returns `nil`.
+
+```expr
+get([1, 2, 3], 1) == 2
+get({"name": "John", "age": 30}, "name") == "John"
+```
+
 ## Predicate
 
 The predicate is an expression. It takes one or more arguments and returns a boolean value.

From 0dd854c02508481cadf37a9d65bd266468b13444 Mon Sep 17 00:00:00 2001
From: Anton Gilgur <agilgur5@gmail.com>
Date: Wed, 4 Oct 2023 17:18:10 -0400
Subject: [PATCH 3/4] move type functions to second-to-last before misc
 functions, per code review

Signed-off-by: Anton Gilgur <agilgur5@gmail.com>
---
 docs/Language-Definition.md | 164 ++++++++++++++++++------------------
 1 file changed, 82 insertions(+), 82 deletions(-)

diff --git a/docs/Language-Definition.md b/docs/Language-Definition.md
index 118605a33..31abf733e 100644
--- a/docs/Language-Definition.md
+++ b/docs/Language-Definition.md
@@ -193,88 +193,6 @@ For example, expression `split(lower(user.Name), " ")` can be written as:
 user.Name | lower() | split(" ")
 ```
 
-## Type Conversion Functions
-
-### type(v)
-
-Returns the type of the given value `v`.
-Returns on of the following types: `nil`, `bool`, `int`, `uint`, `float`, `string`, `array`, `map`.
-For named types and structs, the type name is returned.
-
-```expr
-type(42) == "int"
-type("hello") == "string"
-type(now()) == "time.Time"
-```
-
-### int(v)
-
-Returns the integer value of a number or a string.
-
-```expr
-int("123") == 123
-```
-
-### float(v)
-
-Returns the float value of a number or a string.
-
-### string(v)
-
-Converts the given value `v` into a string representation.
-
-```expr
-string(123) == "123"
-```
-
-### toJSON(v)
-
-Converts the given value `v` to its JSON string representation.
-
-```expr
-toJSON({"name": "John", "age": 30})
-```
-
-### fromJSON(v)
-
-Parses the given JSON string `v` and returns the corresponding value.
-
-```expr
-fromJSON('{"name": "John", "age": 30}')
-```
-
-### toBase64(v)
-
-Encodes the string `v` into Base64 format.
-
-```expr
-toBase64("Hello World") == "SGVsbG8gV29ybGQ="
-```
-
-### fromBase64(v)
-
-Decodes the Base64 encoded string `v` back to its original form.
-
-```expr
-fromBase64("SGVsbG8gV29ybGQ=") == "Hello World"
-```
-
-### toPairs(map)
-
-Converts a map to an array of key-value pairs.
-
-```expr
-toPairs({"name": "John", "age": 30}) == [["name", "John"], ["age", 30]]
-```
-
-### fromPairs(array)
-
-Converts an array of key-value pairs to a map.
-
-```expr
-fromPairs([["name", "John"], ["age", 30]]) == {"name": "John", "age": 30}
-```
-
 ## Number Functions
 
 ### max(n1, n2)
@@ -672,6 +590,88 @@ Returns an array containing the values of the map.
 values({"name": "John", "age": 30}) == ["John", 30]
 ```
 
+## Type Conversion Functions
+
+### type(v)
+
+Returns the type of the given value `v`.
+Returns on of the following types: `nil`, `bool`, `int`, `uint`, `float`, `string`, `array`, `map`.
+For named types and structs, the type name is returned.
+
+```expr
+type(42) == "int"
+type("hello") == "string"
+type(now()) == "time.Time"
+```
+
+### int(v)
+
+Returns the integer value of a number or a string.
+
+```expr
+int("123") == 123
+```
+
+### float(v)
+
+Returns the float value of a number or a string.
+
+### string(v)
+
+Converts the given value `v` into a string representation.
+
+```expr
+string(123) == "123"
+```
+
+### toJSON(v)
+
+Converts the given value `v` to its JSON string representation.
+
+```expr
+toJSON({"name": "John", "age": 30})
+```
+
+### fromJSON(v)
+
+Parses the given JSON string `v` and returns the corresponding value.
+
+```expr
+fromJSON('{"name": "John", "age": 30}')
+```
+
+### toBase64(v)
+
+Encodes the string `v` into Base64 format.
+
+```expr
+toBase64("Hello World") == "SGVsbG8gV29ybGQ="
+```
+
+### fromBase64(v)
+
+Decodes the Base64 encoded string `v` back to its original form.
+
+```expr
+fromBase64("SGVsbG8gV29ybGQ=") == "Hello World"
+```
+
+### toPairs(map)
+
+Converts a map to an array of key-value pairs.
+
+```expr
+toPairs({"name": "John", "age": 30}) == [["name", "John"], ["age", 30]]
+```
+
+### fromPairs(array)
+
+Converts an array of key-value pairs to a map.
+
+```expr
+fromPairs([["name", "John"], ["age", 30]]) == {"name": "John", "age": 30}
+```
+
 ## Miscellaneous Functions
 
 ### len(v)

From 223806316ac6f2b31f77310ff2a6b95c08f28148 Mon Sep 17 00:00:00 2001
From: Anton Gilgur <agilgur5@gmail.com>
Date: Wed, 4 Oct 2023 17:19:09 -0400
Subject: [PATCH 4/4] move number to after string per code review

Signed-off-by: Anton Gilgur <agilgur5@gmail.com>
---
 docs/Language-Definition.md | 44 ++++++++++++++++++-------------------
 1 file changed, 22 insertions(+), 22 deletions(-)

diff --git a/docs/Language-Definition.md b/docs/Language-Definition.md
index 31abf733e..352b2ec79 100644
--- a/docs/Language-Definition.md
+++ b/docs/Language-Definition.md
@@ -193,28 +193,6 @@ For example, expression `split(lower(user.Name), " ")` can be written as:
 user.Name | lower() | split(" ")
 ```
 
-## Number Functions
-
-### max(n1, n2)
-
-Returns the maximum of the two numbers `n1` and `n2`.
-
-```expr
-max(5, 7) == 7
-```
-
-### min(n1, n2)
-
-Returns the minimum of the two numbers `n1` and `n2`.
-
-```expr
-min(5, 7) == 5
-```
-
-### abs(n)
-
-Returns the absolute value of a number.
-
 ## String Functions
 
 ### trim(str[, chars])
@@ -380,6 +358,28 @@ date("2023-08-14T00:00:00Z")
 date("2023-08-14 00:00:00", "2006-01-02 15:04:05", "Europe/Zurich")
 ```
 
+## Number Functions
+
+### max(n1, n2)
+
+Returns the maximum of the two numbers `n1` and `n2`.
+
+```expr
+max(5, 7) == 7
+```
+
+### min(n1, n2)
+
+Returns the minimum of the two numbers `n1` and `n2`.
+
+```expr
+min(5, 7) == 5
+```
+
+### abs(n)
+
+Returns the absolute value of a number.
+
 ## Array Functions
 
 ### all(array, predicate)