conexp v1.0.0

conexp

Concatenative expressions, written in Javascript. An extremely simple syntax for defining embedded languages, for use with Node.

Example

const conexp = require('conexp');

// First let's define some functions for our language.
const add = (a, b) => [a + b];
const subtract = (a, b) => [a - b];
const multiply = (a, b) => [a * b];
const divide = (a, b) => [a / b];

// Then let's generate it.
const evaluate = conexp({ '+': add, '-': subtract, '*': multiply, '/': divide });

// Now to test it.
evaluate('1 2 +'); //=> [3]
evaluate('10 4 - 3 /'); //=> [3]
evaluate('10 5 4 2 / - *'); //=> [30]

Installation

With Node installed, type into the command line:

npm install conexp

The syntax

The language evaluates postfix-notation expressions. This is unlike Javascript functions, which come before (and wrap) their arguments, and unlike math operators (such as +,) which come in between their arguments. Indeed, in our case, the functions/operators come after the arguments. Like 3 2 + or "Hello world" print.

Execution order is from left to right. It is performed by keeping a stack (basically a list) into which we push and pull values. Plain values are pushed into the stack.

Let's take the previous Example section's last line's expression and start analyzing it step by step. This is the expression:

10 5 4 2 / - *

The first four tokens 10 5 4 2 push four values into the stack, namely 10, 5, 4, and 2. So our stack and remainder of the expression look like this:

[ 10 5 4 2 ] / - * (The stack is in [] brackets.)

Next we have the function /. This, by its definition in the javascript code above, takes two values and returns one. This means that it pops the last two values from the stack and operates on them, and then pushes the result, the division of 4 by 2 (that is, 2) into the stack.

[ 10 5 2 ] - *

Where 4 2 used to be now there's 2, the result of their division. Next we have -, which does a similar thing: it evaluates the subtraction of 5 and 2, namely 3.

[ 10 3 ] *

And finally, the last operation.

[ 30 ]

Thus the result of evaluating the entire expression is an array containing the single value 30.

The syntax used is an elementary example of what is known as concatenative programming. In essence, the above is all there is and all you need to know—it's quite simple. However, if you wanna delve deeper into the esoterica behind the concatenative approach, you may read John Purdy's Why concatenative programming matters, browse the concatenative.org wiki, or read Brent Kerby's The theory of concatenative combinators.

Defining functions

Functions may take any number of arguments, and must return an array containing any number of return values. The arguments it receives are popped from the stack, and the values it returns are pushed into it. In the Example section we see functions defined for several arithmetic operations. Here you have a few other types of possible functions:

const conexp = require('conexp');

// Output.
const log = a => {
    console.log(a);
    return [a];
};

// Combinators.
const dup = a => [a, a];
const swap = (a, b) => [b, a];
const drop = a => [];

const evaluate = conexp({ log, dup, swap, drop });

evaluate('"Hello world!" log'); //=> ['Hello world!']
                                // and will output the string to the console.
evaluate('1 2 swap drop dup'); //=> [2, 2]

Generating and using the language

All you need to do is pass the conexp function an object functions containing all functions your language will contain. Each key/value pair in the object indicates a name/function relationship within the language that will be generated.

conexp(functions) → function

The result of calling the conexp function is an evaluate function that takes in an expression as a string and evaluates it, returning an array of values.

evaluate(expression) → array

Current limitations

The syntax does support the following features:

• Strings enclosed in " or '.
• Positive integers and zero.
• Functions.

It does not yet support anything else, like:

• Other types of numbers, such as negative or floating point.
• Quotations (grouping tokens for later parsing, necessary for branching, etc.).
• Definitions.

I will get around to (some of) these in the future.