@onephrase/phrase v0.5.12

Phrase

Phrase is a feather-weight Parser Combinator that makes it damn easy to build a Domain-Specific Language (DSL) parser+evaluator.

Phrase features a lexer – for splitting and matching structured strings; and a collection of parser components – little classes that can be used alone or combined to make larger parsers.

Installation

Embed as script

<script src="https://unpkg.com/@onephrase/phrase"></script>

<script>
// The above tag imports modules as "phrase" into a global "onephr" variable
let Expr = window.onephr.phrase.Expr;
Expr.parse(str);
</script>

npm

$ npm i -g npm
$ npm i --save @onephrase/phrase

Import

// Require.
var phrase = require('@onephrase/phrase');
var Expr = phrase.Expr;

// Or import
import Expr from '@onephrase/phrase';

Examples - parse() + eval() + toString()

Math expression

// parse() a Math expression
var expr = '"10" $= "0" ? 7 + 8 : 2';
var exprObj = Expr.parse(expr);

// get result with eval()
console.log(exprObj.eval());

// toString to string anytime
console.log(exprObj.toString());

Primitives and object notations

// parse() a value
var expr = '10';
var exprObj = Expr.parse(expr);

// get result with eval()
console.log(exprObj.eval());

// ------------

// parse() an array notation
var expr = '["New York City", "Lagos", "Berlin"]';
var exprObj = Expr.parse(expr);

// get result with eval()
console.log(exprObj.eval());

// ------------

// parse() an object notation
var expr = '{city1: "New York City", city2: "Lagos", city3: "Berlin"}';
var exprObj = Expr.parse(expr);

// get result with eval()
console.log(exprObj.eval());

// ------------

// toString to string anytime
console.log(exprObj.toString());

Query an object

// parse() a logical expression with references
var expr = 'age < 18 ? fname + " " + lname + " does not meet the age requirement!" : fname + " " + lname + " is old enough!"';
var exprObj = Expr.parse(expr);

// get result with eval() with the given context
var context = {fname: "John", lname: "lname", age: 24};
console.log(exprObj.eval(context));

// toString to string anytime
console.log(exprObj.toString());

Call a method

// parse() a logical expression with embedded calls
var expr = '"Today is: " + date().toString()';
var exprObj = Expr.parse(expr);

// get result with eval() with the given context
var context = {date:() => (new Date)};
console.log(exprObj.eval(context));

// toString to string anytime
console.log(exprObj.toString());

ES6-style function declaration supported

// parse() a logical expression with embedded calls
var expr = '(arg1, arg2) => {return arg1 + arg2 + argFromContext}';
var exprObj = Expr.parse(expr);

// get result with eval() with the given context
var context = {argFromContext: 10};
var sumFunction = exprObj.eval(context);
// Sum now
console.log(sumFunction(30, 20));

// toString to string anytime
console.log(exprObj.toString());

Assignment operation supported with the "mutates" flag set to true

// parse() a logical expression with value assignment. Multiple expressions supported
var expr = 'prop2 = "val2"; prop3: "val3"';
var exprObj = Expr.parse(expr, {mutates: true});

// get result with eval() with the given context
var context = {prop1: "val1"};
console.log(exprObj.eval(context));
// Confirm the new properties have been set
console.log(context);

// toString to string anytime
console.log(exprObj.toString());

Delete operation supported with the "mutates" flag set to true

// parse() a logical expression with a delete expression. Multiple expressions supported
var expr = 'delete prop1; delete prop3';
var exprObj = Expr.parse(expr, {mutates: true});

// get result with eval() with the given context
var context = {prop1: "val1", prop2: "val2", prop3: "val3"};
console.log(exprObj.eval(context));
// Confirm the new properties have been deleted
console.log(context);

// toString to string anytime
console.log(exprObj.toString());

Examples - Employing utility functions

// Arr.flatten
// parse() a nested array notation and flatten.
var cities = {cities: ['New York City', 'Lagos', 'Berlin', ['two', 'more', 'cities'],]};
var expr = 'cities.flatten()';
var exprObj = Expr.parse(expr);

// get result with eval()
console.log(exprObj.eval());

// ----------------------

// Obj.each
// parse() an object expression and log each entry to the console.
var cities = {cities: {city1: 'New York City', city2: 'Lagos', city3: 'Berlin'}, console: console};
var expr = 'cities.each((key, val) => {console.log(key, val)})';
var exprObj = Expr.parse(expr);

// get result with eval()
console.log(exprObj.eval());

Examples - Lexer

// Lexer.split, Lexer.match, Lexer.regSplit, Lexer.regMatch, Lexer.parse
var str = 'month === "July" ? "Yes, past midyear" : (month === "Dec" ? "Oh, end of year!" : "No problem")';

// Split on all outer occurrencies of "?" and ":"
console.log(Lexer.split(str, ['?', ':']));				// array: 3 items

// Match all outer occurrencies of "?", "*", "+" and ":"
console.log(Lexer.match(str, ['?', '*', '+', ':']));	// array: 2 matches

// Split on the following regex expression
console.log(Lexer.regSplit(str, ['(o|t)']));			// array: 3 items

// Match all outer occurrencies of the following regex expression
console.log(Lexer.regMatch(str, ['(o|t)']));			// array: 2 matches

// Split the following string and return both the splits, and the matches
console.log(Lexer.parse(str, ['?']));					// object: splits, matches

Documentation

(In progress)