README
Subscript
Subscript is a light-weight JavaScript parser and interpreter written in JavaScript; Subscript provides a completely-bendable JavaScript runtime for ambitious usecases.
Overview
You can parse()
a JavaScript expression (2 + 2) * 3
into a Subscript AST,
var subscript = Subscript.parse(expr);
then, stringify()
the Subscript AST back into its original JavaScript expression (2 + 2) * 3
,
let expr = subscript.stringify();
or even eval()
the JavaScript expression.
let result = subscript.eval();
// 12
Features
Small! Fast!
Being an implementation of a subset of JavaScript, as the name implies, Subscript supports the everyday JavaScript that's just enough for most use-cases. That gives us something small and fast that fits anywhere.
Transformable AST
Make any language transformation between Subscript.parse(expr)
and subscript.stringify()
/ subscript.eval()
. Subscript's syntax tree transformability offers a great way to do code transpiling, static code analysis, and more.
A Pseudo Runtime!
Subscript's eval()
feature is a standalone JavaScript runtime that supports user-defined contexts. This provides the level of runtime encapsulation that is not available with the native JavaScript's eval()
function. (Examples ahead.)
Runtime Traps and Hooks
Supercharge everything with runtime traps. Subscript accepts the same trap object as a Proxy trap, for intercepting runtime assignment =
, delete
, and in
operators, and object accessors. This brings a new level of depth to JavaScript code. (Examples ahead.)
Examples
Evaluate a JavaScript expression
MathExpression
:
var expr1 = '7 + 8';
var exprObj1 = Subscript.parse(expr1);
// MathExpression
var result1 = exprObj1.eval();
// (Number) 15
ArrayExpression
:
var expr2 = '[ "New York City", "Lagos", "Berlin" ]';
var exprObj2 = Subscript.parse(expr2);
// ArrayExpression
var result2 = exprObj2.eval();
// (Array) [ "New York City", "Lagos", "Berlin" ]
ObjectExpression
:
var expr3 = '{ city1: "New York City", city2: "Lagos", city3: "Berlin", city4: cityNameFromContext }';
var exprObj3 = Subscript.parse(expr3);
// ObjectExpression
var result3 = exprObj3.eval();
// (Object) { city1: "New York City", city2: "Lagos", city3: "Berlin", city4: undefined }
var context = { cityNameFromContext: 'London' };
var result3 = exprObj3.eval(context);
// (Object) { city1: "New York City", city2: "Lagos", city3: "Berlin", city4: "London" }
FunctionExpression
:
var expr4 = '( arg1, arg2 ) => { return arg1 + arg2 + (argFromContext ? argFromContext : 0); }';
var exprObj4 = Subscript.parse(expr4);
// FunctionExpression
var result4 = exprObj4.eval();
// (Function) ( arg1, arg2 ) => { return arg1 + arg2 + (argFromContext ? argFromContext : 0); }
result4(10, 3);
// (Number) 13
var context = { argFromContext: 20 };
var result4 = exprObj4.eval(context);
// (Function) ( arg1, arg2 ) => { return arg1 + arg2 + (argFromContext ? argFromContext : 0); }
result4(10, 3);
// (Number) 33
.stringify()
:
var expr1 = exprObj1.stringify();
// 7 + 8
Use conditionals, call a function in scope
ConditionalExpression
:
var expr1 = 'age < 18 ? fname + " " + lname + " does not meet the age requirement!" : fname + " " + lname + " is old enough!"';
var exprObj1 = Subscript.parse(expr1);
// ConditionalExpression
var context = { fname: "John", lname: "Doe", age: 24 };
var result1 = exprObj1.eval();
// (String) John Doe is old enough!
var context = { fname: "John2", lname: "Doe2", age: 10 };
var result1 = exprObj1.eval(context);
// (String) John Doe does not meet the age requirement!
StringExpression
:
var expr2 = '"Today is: " + date().stringify()';
var exprObj2 = Subscript.parse(expr2);
// StringExpression
var context = { date:() => (new Date) };
var result2 = exprObj2.eval(context);
// (String) Today is: <current date>
.stringify()
:
var expr2 = exprObj2.stringify();
// "Today is: " + date().stringify()
Write multiple expressions and Comments, plus a top-level return
BlockExpression
:
var expr = `
/**
* Block comments
*/
// Single line comments
delete obj1.prop1;
delete /*comment anywhere*/obj2.prop1;
return;
delete obj2.prop2;
`;
var exprObj = Subscript.parse(expr);
// BlockExpression
var context = { obj1: { prop1: "John" }, obj2: { prop1: "Doe", prop2: "Bar" } };
var result = exprObj.eval();
context;
// (Object) { obj1: { }, obj2: { prop2: "Bar" } }
Use traps
IfExpression
:
var expr = `if ("prop1" in obj1) {
console.log('prop1 exists.');
} else {
console.log('prop1 does not exist. Creating it now.');
obj1.prop1 = 'John';
}
`;
var exprObj = Subscript.parse(expr);
// IfExpression
var pseudoContext = { obj1: { prop1: "John" }, obj2: { prop1: "Doe", prop2: "Bar" } };
var context = {};
var result = exprObj.eval(context, {
has: (target, property) => {
return property in pseudoContext;
},
set: (target, property, value) => {
pseudoContext[property] = value;
return true;
},
});
// (String) prop1 exists.
Documentation
- See project homepage for download options and full documentation.
Issues
To report bugs or request features, please submit an issue.
License
MIT.