@witchcraft/expressit
v0.2.1
Published
A blazing fast, customizable, error-tolerant expression parser that creates safe to eval expressions + a few other goodies like autocomplete.
Downloads
75
Maintainers
Readme
🚧 WORK IN PROGRESS 🚧
Expressit is a blazing fast, customizable, error-tolerant expression parser that creates safe to eval expressions + a few other goodies.
Docs
Demo
Install
pnpm install @witchcraft/expressit
Features
- Error Recovery
- The parser is designed to recover from ALL errors, even multiple errors, making it easy to provide things like syntax highlighting.
- Custom Operator Keywords
- You can use whatever keywords you want for the operators and their strictness (whether something like
oregano
will parse toor egano
ororegano
can be adjusted to allow the use of keywords (usually symbols) without whitespace).
- You can use whatever keywords you want for the operators and their strictness (whether something like
- Prefixed Group Parsing (optional)
- Adds the ability do
prefix(variable)
which gets expanded intoprefixvariable
. You can also customize how they get prefixed (e.g. you can makeprefix(variable)
expand toprefix.variable
instead).
- Adds the ability do
- Custom Property Operator
- Extended with custom separator (e.g.
:
):property:OP:value
. - Custom set (e.g.
=
,>
,<
, etc):property=value
. - Array(optional), Regex(optional), and Group Values
- Can be parsed alone, but intended for use with custom property operators:
prop=[val1, val2]
,prop=/regex/flags
,prop=(a || b)
.
- Can be parsed alone, but intended for use with custom property operators:
- Extended with custom separator (e.g.
- Batteries Included
- Can
validate
(for syntax highlighting) andevaluate
ASTs according to custom rules.
- Can
- Autosuggest/complete/replace Helpers
- Never think about autocompletion ever again!
- Other Useful Utility Functions:
extractTokens
,getCursorInfo
,getOppositeDelimiter
,getSurroundingErrors
- useful for adding custom syntax highlighting.prettyAst
- pretty prints a compact version of the ast for debugging- other minor utilities -
isDelimiter
,isQuote
, etc.
- Pre-Configured Parsers - Includes a pre-configured boolean parser (intended for parsing shortcut contexts in a similar way to VS Code).
- Lots of Docs and Tests
Usage
// while you can import from "@witchcraft/expressit", if using something like vite, it's recommended you do not use barrel imports.
import { Parser } from "@witchcraft/expressit/Parser.js"
const parser = new Parser({/* opts */})
const context = {
a: false,
b: true
}
// USER INPUT
const input = "a || b"
const cursor = 1 // a| || b
const ast = parser.parse(input)
if (!ast.valid) {
// ...show regular errors (no input, missing tokens, etc)
if (ast.isToken) {
// empty input
}
} else {
// validation can be controlled by parser options
const errors = parser.validate(ast)
// ...show more complex errors, e.g. unknown variables, etc
}
// ON AUTOCOMPLETE
const suggestions = parser.autosuggest(input, ast, cursor)
const completions = parser.autocomplete(ast,suggestions, {
// known possible suggestions
variables: ["c", "d", "e"],
// can also be values, prefixes, keywords, properties, etc
})
// ...show completions
// ON ENTER/SUBMIT
const res = parser.evaluate(ast, context)
Many more examples can be found in the tests, and there's also some WIP pre-configured parsers in src/examples whose usage can be seen in ./test/examples.spec.ts.