hanzoai/expr
2
0
Fork 0
mirror of https://github.com/hanzoai/expr.git synced 2026-09-24 16:58:58 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: categorize Language Definition functions (#452)

Browse Source 
* 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 <[email protected]>

* 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 <[email protected]>

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

Signed-off-by: Anton Gilgur <[email protected]>

* move number to after string per code review

Signed-off-by: Anton Gilgur <[email protected]>

---------

Signed-off-by: Anton Gilgur <[email protected]>
This commit is contained in:
Anton Gilgur
2023-10-04 23:34:04 +02:00
committed by GitHub
parent 63496e6fe7
commit 5ba4704bf8
1 changed files with 297 additions and 287 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/Language-Definition.md
+297 -287
View File
@@ -193,7 +193,117 @@ For example, expression `split(lower(user.Name), " ")` can be written as:
user.Name | lower() | split(" ")
```
### Date Manipulation
## String Functions
### 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
trim(" Hello ") == "Hello"
trim("__Hello__", "_") == "Hello"
```
### trimPrefix(str, prefix)
Removes the specified prefix from the string `str` if it starts with that prefix.
```expr
trimPrefix("HelloWorld", "Hello") == "World"
```
### trimSuffix(str, suffix)
Removes the specified suffix from the string `str` if it ends with that suffix.
```expr
trimSuffix("HelloWorld", "World") == "Hello"
```
### upper(str)
Converts all the characters in string `str` to uppercase.
```expr
upper("hello") == "HELLO"
```
### lower(str)
Converts all the characters in string `str` to lowercase.
```expr
lower("HELLO") == "hello"
```
### split(str, delimiter[, n])
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(str, delimiter[, n])
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(str, old, new)
Replaces all occurrences of `old` in string `str` with `new`.
```expr
replace("Hello World", "World", "Universe") == "Hello Universe"
```
### repeat(str, n)
Repeats the string `str` `n` times.
```expr
repeat("Hi", 3) == "HiHiHi"
```
### indexOf(str, substring)
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(str, substring)
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(str, prefix)
Returns `true` if string `str` starts with the given prefix.
```expr
hasPrefix("HelloWorld", "Hello") == true
```
### hasSuffix(str, suffix)
Returns `true` if string `str` ends with the given suffix.
```expr
hasSuffix("HelloWorld", "World") == true
```
## Date Functions
The following operators can be used to manipulate dates:
@@ -203,7 +313,74 @@ date("2023-08-14") - duration("1h")
date("2023-08-14") - date("2023-08-13") == duration("24h")
```
## Built-in Functions
### now()
Returns the current date and time.
```expr
createdAt > now() - duration(1h)
```
### duration(str)
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
duration("1h").Seconds() == 3600
```
### date(str[, format[, timezone]])
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
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")
```
## 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)
@@ -300,6 +477,16 @@ Equivalent to:
len(filter(array, predicate))
```
### 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.
```expr
join(["apple", "orange", "grape"], ",") == "apple,orange,grape"
join(["apple", "orange", "grape"]) == "appleorangegrape"
```
### reduce(array, predicate[, initialValue])
Applies a predicate to each element in the array, reducing the array to a single value.
@@ -317,180 +504,6 @@ reduce(1..9, #acc + #)
reduce(1..9, #acc + #, 0)
```
### len(v)
Returns the length of an array, a map or a string.
### 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"
```
### abs(v)
Returns the absolute value of a number.
### 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"
```
### trim(v[, chars])
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.
```expr
trim(" Hello ") == "Hello"
trim("__Hello__", "_") == "Hello"
```
### trimPrefix(v, prefix)
Removes the specified prefix from the string `v` if it starts with that prefix.
```expr
trimPrefix("HelloWorld", "Hello") == "World"
```
### trimSuffix(v, suffix)
Removes the specified suffix from the string `v` if it ends with that suffix.
```expr
trimSuffix("HelloWorld", "World") == "Hello"
```
### upper(v)
Converts all the characters in string `v` to uppercase.
```expr
upper("hello") == "HELLO"
```
### lower(v)
Converts all the characters in string `v` to lowercase.
```expr
lower("HELLO") == "hello"
```
### split(v, delimiter[, n])
Splits the string `v` 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])
Splits the string `v` 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)
Replaces all occurrences of `old` in string `v` with `new`.
```expr
replace("Hello World", "World", "Universe") == "Hello Universe"
```
### repeat(v, n)
Repeats the string `v` `n` times.
```expr
repeat("Hi", 3) == "HiHiHi"
```
### join(v[, delimiter])
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.
```expr
indexOf("apple pie", "pie") == 6
```
### lastIndexOf(v, substring)
Returns the index of the last occurrence of the substring in string `v` or -1 if not found.
```expr
lastIndexOf("apple pie apple", "apple") == 10
```
### hasPrefix(v, prefix)
Returns `true` if string `v` starts with the given prefix.
```expr
hasPrefix("HelloWorld", "Hello") == true
```
### hasSuffix(v, suffix)
Returns `true` if string `v` ends with the given suffix.
```expr
hasSuffix("HelloWorld", "World") == true
```
### max(v1, v2)
Returns the maximum of the two values `v1` and `v2`.
```expr
max(5, 7) == 7
```
### min(v1, v2)
Returns the minimum of the two values `v1` and `v2`.
```expr
min(5, 7) == 5
```
### sum(array)
Returns the sum of all numbers in the array.
@@ -515,6 +528,102 @@ Returns the median of all numbers in the array.
median([1, 2, 3]) == 2.0
```
### first(array)
Returns the first element from an array. If the array is empty, returns `nil`.
```expr
first([1, 2, 3]) == 1
```
### last(array)
Returns the last element from an array. If the array is empty, returns `nil`.
```expr
last([1, 2, 3]) == 3
```
### take(array, n)
Returns the first `n` elements from an array. If the array has fewer than `n` elements, returns the whole array.
```expr
take([1, 2, 3, 4], 2) == [1, 2]
```
### sort(array[, order])
Sorts an array in ascending order. Optional `order` argument can be used to specify the order of sorting: `asc`
or `desc`.
```expr
sort([3, 1, 4]) == [1, 3, 4]
sort([3, 1, 4], "desc") == [4, 3, 1]
```
### 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`.
```expr
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]
```
## 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.
@@ -547,101 +656,6 @@ Decodes the Base64 encoded string `v` back to its original form.
fromBase64("SGVsbG8gV29ybGQ=") == "Hello World"
```
### now()
Returns the current date and time.
```expr
createdAt > now() - duration(1h)
```
### duration(v)
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".
```expr
duration("1h").Seconds() == 3600
```
### date(v[, format[, timezone]])
Converts the given value `v` 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
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")
```
### first(v)
Returns the first element from an array `v`. If the array is empty, returns `nil`.
```expr
first([1, 2, 3]) == 1
```
### last(v)
Returns the last element from an array `v`. If the array is empty, returns `nil`.
```expr
last([1, 2, 3]) == 3
```
### 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"
```
### take(array, n)
Returns the first `n` elements from an array. If the array has fewer than `n` elements, returns the whole array.
```expr
take([1, 2, 3, 4], 2) == [1, 2]
```
### 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]
```
### toPairs(map)
Converts a map to an array of key-value pairs.
@@ -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)
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
sort([3, 1, 4]) == [1, 3, 4]
sort([3, 1, 4], "desc") == [4, 3, 1]
```
### 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`.
```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})