@bd-js/interpreter NPM

BDJS Interpreter

This package is intended to act as interpreter of BDJS code.

Considerations

This interpreter reads from top to bottom and bottom to top.
This package can contain bugs.

Syntax Showcase

Demo

$switch: [banana;
    $case: [banana;
        $log: [CASE_BANANA]
    ]
    $default: [
        $log: [DEFAULT_CASE]
    ]
]

Usage

Basic Interpretation

import { Data, Interpreter, FunctionManager } from "@bd-js/interpreter";

const functions = new FunctionManager();
await functions.loadCoreFunctions();

const interpreter = new Interpreter({
    functionManager: functions
});

const code = "$if:[1==2;$log:[true];$log:[false]]";
interpreter.run(code).then(console.log);

Catching Function Errors

You can easily catch function errors with Interpreter#on method.

Interpreter.on("error", (e) => console.log(e));

Reading modes

You can switch between read modes. This package supports "TOP-TO-BOTTOM" and "BOTTOM-TO-TOP" readings.

Actually this parameter isn't needed and reads "TOP-TO-BOTTOM" by default.

This option is changeable in Interpreter#run parameters.

/* true for "BOTTOM-TO-TOP" reading */
interpreter.run(code, true);

/* false for "TOP-TO-BOTTOM" reading */
interpreter.run(code, false); // or Interpreter#run(code);

Function Manager

This package has a built-in function manager to add your own functions in a easy way.

Basic Setup

import { FunctionManager, Func } from "@bd-js/interpreter";

const manager = new FunctionManager();
manager.loadCoreFunctions().then(() => console.log("Core functions loaded!"));

WARNING: loadCore in FunctionManager constructor only works for the interpreter constructor.

Creating Functions

Function Sample

manager.add({
    data: new Func()
        .setName("name"),
    async code(d, PARAM_1, PARAM_2, PARAM_3) {
        /*
        * d: Interpreter Data
        * PARAM_INDEX: Function parameters
        */
        return ""; // Function return.
        /*
        Function returns must be converted to string.
        Number -> String
        Boolean -> String
        Array -> String
        null | undefined -> String
        */ 
    }
});

Example

manager.add({
    data: new Func()
        .setName("helloWorld")
        .set("description", "Hello world -> print"),
    async code(d, text) {
        console.log("$helloWorld[" + text + "]");
        return "";
    }
});

Non-executable fields

This feature is util for functions like "$if". (Already built-in)

You should set a property called "allowExecution", then for its value you must provide an array of "yes" or "no" strings depending on which fields you don't wanna execute in first function evaluation.

After function execution, you can run the split you want with the interpreter in d.interpreter.run(code).

manager.add({
    data: new Func()
        .setName("runIfYouMomGae")
        .set("allowExecution", ["yes", "no", "no"]), // This will allow the execution for the first function field, but not for the rest.
    async code(d, yourMomGae, then, _else) {
        let r;
        if (yourMomGae) r = await d.interpreter.run(then, d.__reverse, d);
        else r = await d.interpreter.run(_else, d.__reverse, d);
        // Function result.
        return r?.code.toString(); // <- IMPORTANT TO RETURN IT AS STRING.
    }
});

Getting Functions

manager.get("helloWorld");

Data

Data is the built-in class to pass some data to the interpreter, you can easily extend this class to add your own properties and build your own functions.

import { Data, Func, Interpreter } from "@bd-js/interpreter";

class CustomData extends Data {
    constructor(options) {
        super(options);
        this.ctx = "hi";
    }
}

const interpreter = new Interpreter({
    manager: {
        loadCore: true // Loading default functions.
    }
});
interpreter.functions.add({
    data: new Func()
        .setName("ctx"),
    async code(d) {
        return d.ctx;
    }
});
const code = "$ctx";
interpreter.run(code, false, new CustomData()).then(d => console.log(d.code)); // hi

Data Interface

{
    break: boolean;
    code: string;
    interpreter: Interpreter;
    start: number;
    functions: FunctionManager;
    func?: {
        name: string,
        inside: string,
        splits: string[]
    };
    _?: {
        __request: Map<string, Object>,
        __cases: Map<string, string>,
        __vars: Map<string, unknown>,
        __arrays: Map<string, Array<string | number>>,
        __objects: Map<string, Object>,
        __functions: Map<string, string>
    };
    __reverse: boolean
}