Phrasing-engine NPM

Phrasing Engine

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

Phrasing Engine 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/phrasing-engine"></script>

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

npm

$ npm i -g npm
$ npm i --save phrasing-engine

Import

// Require.
var PhrEng = require('phrasing-engine');
var Expr = PhrEng.Expr;

// Or import
import Expr from 'phrasing-engine';

// Cherry-pick parser components / utils.
import {Arr, Obj} from 'phrasing-engine';

Examples - parse() + eval() + stringify()

Math expression

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

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

// stringify to string anytime
console.log(ExprParse.stringify());

Primitives and object notations

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

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

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

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

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

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

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

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

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

// stringify to string anytime
console.log(ExprParse.stringify());

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 ExprParse = Expr.parse(expr);

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

// stringify to string anytime
console.log(ExprParse.stringify());

Call a method

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

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

// stringify to string anytime
console.log(ExprParse.stringify());

ES6 function definition supported

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

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

// stringify to string anytime
console.log(ExprParse.stringify());

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 ExprParse = Expr.parse(expr, {mutates: true});

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

// stringify to string anytime
console.log(ExprParse.stringify());

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 ExprParse = Expr.parse(expr, {mutates: true});

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

// stringify to string anytime
console.log(ExprParse.stringify());

Examples - Utilities

// import some utils
import {Arr, Obj, Lexer} from 'phrasing-engine';

// Arr.flatten
var cities = ['New York City', 'Lagos', 'Berlin', ['two', 'more', 'cities'],];
console.log(Arr.flatten(cities));

// Obj.each
var cities = {city1: 'New York City', city2: 'Lagos', city3: 'Berlin'};
Obj.each(cities, (key, val) => {
	console.log(key, val);
	// Returning false stops further iteration
	return false;
});

Examples - Employing utility functions in DSL

// 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 ExprParse = Expr.parse(expr);

// get result with eval()
console.log(ExprParse.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 ExprParse = Expr.parse(expr);

// get result with eval()
console.log(ExprParse.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