Skip to content

Reorganize docs/syntax.md functions into categorized sections #30

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Sander-Toonen merged 2 commits into from
Jan 23, 2026
+17 −15
Merged

Reorganize docs/syntax.md functions into categorized sections #30

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
779f9df
Initial plan
Copilot Jan 23, 2026
e169a8f
Rearrange functions in docs/syntax.md into categorized sections
Copilot Jan 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 17 additions & 15 deletions docs/syntax.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112,6 +112,8 @@ The unary `+` and `-` operators are an exception, and always have their normal p

Besides the "operator" functions, there are several pre-defined functions. You can provide your own, by binding variables to normal JavaScript functions. These are not evaluated by simplify.

### Numeric Functions

| Function | Description |
|:------------- |:----------- |
| random(n) | Get a random number in the range [0, n). If n is zero, or not provided, it defaults to 1. |
Expand All @@ -124,15 +126,27 @@ Besides the "operator" functions, there are several pre-defined functions. You c
| pow(x, y) | Equivalent to x^y. For consistency with JavaScript's Math object. |
| atan2(y, x) | Arc tangent of x/y. i.e. the angle between (0, 0) and (x, y) in radians. |
| roundTo(x, n) | Rounds x to n places after the decimal point. |

### Array Functions

| Function | Description |
|:------------- |:----------- |
| count(a) | Returns the number of items in an array. |
| map(f, a) | Array map: Pass each element of `a` the function `f`, and return an array of the results. |
| fold(f, y, a) | Array fold: Fold/reduce array `a` into a single value, `y` by setting `y = f(y, x, index)` for each element `x` of the array. |
| filter(f, a) | Array filter: Return an array containing only the values from `a` where `f(x, index)` is `true`. |
| indexOf(x, a) | Return the first index of string or array `a` matching the value `x`, or `-1` if not found. |
| join(sep, a) | Concatenate the elements of `a`, separated by `sep`. |
| naturalSort(arr) | Sorts an array of strings using natural sort order (alphanumeric-aware). For example, `["file10", "file2", "file1"]` becomes `["file1", "file2", "file10"]`. |
Copy link

Copilot AI Jan 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

naturalSort is listed under Array Functions but uses a different parameter name (arr) than the rest of this section (a). For consistency with the other signatures (count/map/fold/filter/indexOf/join), consider renaming the signature here to naturalSort(a) (or standardize the whole section on arr).

Suggested change
| naturalSort(arr) | Sorts an array of strings using natural sort order (alphanumeric-aware). For example, `["file10", "file2", "file1"]` becomes `["file1", "file2", "file10"]`. |
| naturalSort(a) | Sorts an array of strings using natural sort order (alphanumeric-aware). For example, `["file10", "file2", "file1"]` becomes `["file1", "file2", "file10"]`. |

Copilot uses AI. Check for mistakes.

### Utility Functions

| Function | Description |
|:------------- |:----------- |
| if(c, a, b) | Function form of c ? a : b. Note: This always evaluates both `a` and `b`, regardless of whether `c` is `true` or not. Use `c ? a : b` instead if there are side effects, or if evaluating the branches could be expensive. |
| coalesce(a, b, ...) | Returns the first non-null and non-empty string value from the arguments. Numbers and booleans (including 0 and false) are considered valid values. |

## String Manipulation Functions
## String Functions
Copy link

Copilot AI Jan 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After moving naturalSort and coalesce out of the String Functions list, the “String Function Examples” section still includes examples for both (naturalSort at ~246 and coalesce at ~272). This makes the section misleading and may also make the subsequent note about “All string functions…” ambiguous. Consider moving those examples to the relevant Pre-defined subsections (Array/Utility) or renaming/restructuring the examples section so it only contains string functions.

Copilot uses AI. Check for mistakes.

The parser includes comprehensive string manipulation capabilities.

Expand Down Expand Up @@ -166,19 +180,13 @@ The parser includes comprehensive string manipulation capabilities.
| right(str, n) | Returns the rightmost `n` characters from a string. |
| split(str, delim)| Splits a string by delimiter and returns an array. |

### String Manipulation
### String Replacement

| Function | Description |
|:--------------------------- |:----------- |
| replace(str, old, new) | Replaces all occurrences of `old` with `new` in `str`. |
| replaceFirst(str, old, new) | Replaces only the first occurrence of `old` with `new` in `str`. |

### String/Array Sorting

| Function | Description |
|:---------------- |:----------- |
| naturalSort(arr) | Sorts an array of strings using natural sort order (alphanumeric-aware). For example, `["file10", "file2", "file1"]` becomes `["file1", "file2", "file10"]`. |

### Type Conversion

| Function | Description |
Expand All @@ -203,12 +211,6 @@ The parser includes comprehensive string manipulation capabilities.
| base64Encode(str) | Base64-encodes a string with proper UTF-8 support. |
| base64Decode(str) | Base64-decodes a string with proper UTF-8 support. |

### Utility Functions

| Function | Description |
|:--------------------- |:----------- |
| coalesce(a, b, ...) | Returns the first non-null and non-empty string value from the arguments. Numbers and booleans (including 0 and false) are considered valid values. |

### String Function Examples

```js
Expand Down Expand Up @@ -277,7 +279,7 @@ parser.evaluate('toUpper(trim(left(" hello world ", 10)))'); // "HELLO WOR"

> **Note:** All string functions return `undefined` if any of their required arguments are `undefined`, allowing for safe chaining and conditional logic.

## Object Manipulation Functions
## Object Functions

The parser includes functions for working with objects.

Expand Down