Docs vs parser mismatches: `substring ... from ... length`, `split ... by ...`, and `is not equal to`

[logbie]

Summary

Three constructs that appear in the documentation (or read as natural WFL) are rejected by the parser in the current build. Either the parser or the docs should change so they agree.

Environment

• WFL built from source, .build_meta.json: { "year": 26, "month": 6, "build": 5 }
• Linux, release build

1. substring of <text> from <start> length <length>

Documented in Docs/05-standard-library/text-module.md:

substring of <text> from <start> length <length>

and used in Docs/04-advanced-features/web-servers.md:

store filename as substring of path from 8 length 100

But it fails to parse:

store t as substring of "abcdefghij" from 0 length 5   // Parse error: Unexpected token in expression: KeywordFrom

The and form works:

store t as substring of "abcdefghij" and 0 and 5       // OK -> "abcde"

2. split of <text> by <delimiter>

Documented in Docs/05-standard-library/text-module.md:

split of <text> by <delimiter>
...
store parts as split of csv by ","

But it fails to parse:

store parts as split of "a-b-c" by "-"                 // Parse error

The string_split ... and form works:

store parts as string_split of "a-b-c" and "-"         // OK -> ["a","b","c"]

3. is not equal to

is equal to works, but the natural negation does not parse:

check if n is not equal to 3:                          // Parse error: Unexpected token: KeywordEqual

Current workaround:

check if not (n is equal to 3):                        // OK

Expected

Either implement these documented/natural forms in the parser, or update the docs (and any example programs / web-servers.md) to only show the supported spellings (substring of X and START and LENGTH, string_split of X and DELIM, not (X is equal to Y)).

These are minor but they trip up anyone following the docs.

[logbie]

Triage: confirmed on all three — two are parser gaps, one is a genuine docs↔parser mismatch. Verdicts and locations below.

3. is not equal to — confirmed parser bug, and the cleanest to fix. In src/parser/expr/binary.rs, the Token::KeywordIs handler has an arm:

Token::KeywordNot => {
    self.bump_sync(); // Consume "not"
    Some((Operator::NotEquals, 0))
}

It consumes only is not and immediately returns NotEquals, so the trailing equal to is left dangling and the RHS expression parser trips on KeywordEqual — precisely your Unexpected token: KeywordEqual. Fix: after consuming not, optionally consume equal and then optional to (same shape as the is equal to and is greater than or equal to arms right around it), still yielding Operator::NotEquals. Small, additive, backward-compatible — is not alone keeps working. This one is worth implementing rather than documenting away, since is not equal to is the natural negation of the supported is equal to.

1. substring ... from ... length and 2. split ... by — confirmed: documented but never implemented in the parser. The natural-language call syntax the parser supports is NAME of ARG [and ARG …] (that's why substring of X and START and LEN and string_split of X and DELIM work — native_substring takes 3 args, src/stdlib/text.rs). There is no parser handling for a trailing from … length … on substring, nor a by-delimited split form — so substring of X from 0 length 5 stops after substring of X, then chokes on KeywordFrom (your error), and split isn't even the registered function name (string_split is). Meanwhile the docs advertise both forms in several places — Docs/05-standard-library/text-module.md (L172, L343, and many examples L191–557), Docs/05-standard-library/overview.md (L77, L183), and a live example in Docs/04-advanced-features/web-servers.md. So the docs are writing checks the parser can't cash.

Recommended split of work:

• Implement is not equal to in the parser (small; failing-test-first in src/parser/tests.rs).
• For substring … from … length and split … by: pick one direction and make them agree. Implementing the natural forms as parser sugar (lowering substring of T from S length L → the 3-arg substring, and split of T by D → string_split) is the more user-friendly fix and keeps the docs honest; the lower-risk alternative is to correct the docs (and web-servers.md) to only show substring of X and START and LENGTH and string_split of X and DELIM. Given the docs already list both spellings for substring, implementing the sugar is probably what readers expect.

Verdict: confirmed (bug + documentation). Suggested labels: parser, documentation, confirmed. Whichever direction is chosen for #1/#2, add parser tests (or a docs-validation pass via scripts/validate_docs_examples.py) so the two can't drift again.

I couldn't cargo build in the automated sandbox (no Rust toolchain here), so the above is confirmed from the parser/stdlib source and the docs, matching your repros, rather than from a local rebuild.

Posted by the WFL repo warden (automated triage pass).