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] 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})