From e3c2d0e4cefd3885b00caaeee02084d80748f2f3 Mon Sep 17 00:00:00 2001
From: Anton Gilgur <4970083+agilgur5@users.noreply.github.com>
Date: Wed, 4 Oct 2023 17:34:04 -0400
Subject: [PATCH] docs: categorize Language Definition functions (#452)

* 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>

* 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>

* move type functions to second-to-last before misc functions, per code review

Signed-off-by: Anton Gilgur <agilgur5@gmail.com>

* move number to after string per code review

Signed-off-by: Anton Gilgur <agilgur5@gmail.com>

---------

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

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