Wondering what’s next for npm?Check out our public roadmap! »

    nrpl

    0.1.0 • Public • Published

    Introduction to NRPL

    Description

    NRPL is a stack-based language heavily inspired by Hewlett-Packard's RPL (from which it derives its name) and Forth. It was developed to give users the ability to do complex processing on their data server-side in a concise and secure manner.

    Typical uses of NRPL are for querying, filtering, and transforming data. The language is general purpose, making it suitable for a variety of uses. This module was developed to fulfil the need for an interpreted that could be embedded in JavaScript applications to run untrusted, user-supplied code. For a full description of the language and its various options and commands, please refer to its complete specification.

    How it works

    NRPL programs are sequences of commands, literals, and variables, which take arguments from, and return results to, a stack[PDF]. Being based on Hewlett-Packard's RPN, it uses a postfix notation.

    An example

    Assume you would like to add the numbers 3 and 5 together:

    Input

    3 5 +
    

    Output

       1:   8
    

    Where 1: refers to the bottommost stack level and 8 is the result of the operation.

    Another example (step by step)

    Let us take a slightly more involved example, and calculate the volume of a sphere of radius 7.5, using the formula 4/3 π r3:

    Input

    4 3 / PI * 7.5 3 ^ *
    

    Output

       1:   1767.1458676442585
    

    The calculation happens as follows, step by step:

    Description Input Stack
    Enter the first number 4
       1:   4
    Enter the second number 3
       2:   4
       1:   3
    Divide /
       1:   1.3333333333333333
    Enter the symbolic constant π PI
       2:   1.3333333333333333
       1:   3.141592653589793
    Multiply *
       1:   4.1887902047863905
    Enter the radius 7.5
       2:   4.1887902047863905
       1:   7.5
    Enter the exponent 3
       3:   4.1887902047863905
       2:   7.5
       1:   3
    Exponentiate ^
       2:   4.1887902047863905
       1:   421.875
    Multiply *
       1:   1767.1458676442585

    A feature of postfix notation is that parentheses are never required. As long as enough stack levels are available (NRPL has a conceptually infinite stack) calculations can be of any arbitrary complexity.

    Installation

    npm install nrpl

    Calling

     
    const NRPL = require('nrpl');
     
    async function runInterpreter (script) {
     
        const nrpl = new NRPL(/*<Global Variable Getter>,*/ /*<Global Variable Setter>,*/ /*<Allow locals?>*/);
        
        return await nrpl.exec(script);
    };
     
     
    runInterpreter("3 2 +").then( (stack) => console.log("Three plus two equals", stack) );
    // Three plus two equals [5]
     

    Getting data in and out

    Data is entered into the program via two mechanisms:

    1. Direct input into the stack, as we have seen above.
    2. Via variables, as we will see in a moment.

    Retrieved may be retrieved from the stack or via assignment to global variables.

    Variables

    There are two types of variables: “global” and “local”, both of which may be enabled or disabled independently.

    Global variables

    These variables may be used to pass data into and out of the interpreter. For example, to persist data between calls. Globals may be read only, write only, read/write, or disabled altogether.

    Local variables

    These variables are used within a single execution call, their values being lost once the script returns.

    Example instantiation with arguments

     
    let variables = {
        UID: process.getuid(),
        GID: process.getgid(),
        PID: process.pid
    }
     
    function getVariable(name) {
        return variables.hasOwnProperty(name)
            ? variables[name]
            : undefined;
    }
     
    function setVariable(name, value) {
        // For illustration, do not allow to change PID variable
        if (name && name != "PID") {
            variables[name] = value;
        }
    }
     
    // Preload the stack with some data
    let stack = [
        process.cwd(),
        "Hello"
    ];
     
    const script = '" user " $UID ++ SWAP !CURRENTDIR';
     
    const nrpl = new NRPL(getVariable, setVariable, true);
     
    nrpl.exec(script, stack).then(console.log);
     
    console.log("VARIABLES", variables);
     
    // When execution completes, the stack will contain a
    // greeting similar to "Hello user 12345" and variables.CURRENTDIR
    // will have been set to the processes' current working directory.
     

    More information

    For a full description of NRPL, please refer to the specification.

    Install

    npm i nrpl

    DownloadsWeekly Downloads

    1

    Version

    0.1.0

    License

    MIT

    Unpacked Size

    81.3 kB

    Total Files

    6

    Last publish

    Collaborators

    • avatar