This is a reverse polish notation stack based concatenative interpreter written in js.

The main goal is to be able to write web applications with it, giving an alternative for javascript while being just a layer on top of it.

The goal is therefore to inherit everything from javascript and the browser APIs and add abstractions over them.

The language should run both in node and in the browser and run a repl in node while loading <oh> tags from the document when it loads.

The core of the language is very simple.

The reader reads a word delimited by spaces or newlines and returns it.

The interpreter looks this word in the dictionary and evaluates it if exists.

If not it looks if it's a number or a quoted string and pushes them on the stack.

If not it triggers an error saying that the word does not exist.

That's all the interpreter does.

function interpret_element (element)
{
  if (temporary[element])
  {
    temporary[element]();
  }
  else if (dictionary[element])
  {
    dictionary[element]();
  }
  else if (element.match(/^-?\d+\.?\d*$/))
  {
    put(parseFloat(element));
  }
  else if (element.startsWith("'"))
  {
    put(element.substr(1));
  }
  else
  {
    error('word does not exist', element);
  }
}

where element is the word returned by the reader.

There is some sort of compilation procedure that mirrors the interpret_element function, but instead of evaluating it returns the function that will perform the action, be it the word found or a closure capturing a value.

The compilation procedure allows some words to evaluate at compile time and other words that evaluate at compile time and return code.

Those words are known as immediate words.

This provides ways for extension since a word can read from the source code, implement new syntax and optionally return a javascript function that will get appended to what was being compiled.

function compile_element (element)
{
  if (temporary[element])
  {
    return temporary[element];
  }
  else if (dictionary[element])
  {
    if (element in immediate)
    {
      dictionary[element](1);
      if (immediate[element])
      {
        return get();
      }
    }
    else
    {
      return dictionary[element];
    }
  }
  else if (element.match(/^-?\d+\.?\d*$/))
  {
    let num = parseFloat(element);
    return () => { put(num) };
  }
  else if (element.startsWith("'"))
  {
    let str = element.substr(1);
    return () => { put(str) };
  }
  else
  {
    error('word cannot be compiled', element);
  }
}

If a word is immediate it gets evaluated instead of returned. The word can do whatever it wants.
since words are just js functions it calls that function, like interpreter_element does, but it gives it a 1 argument as a true flag to know that is being called at compilation time.
If the immediate word returns a result it will be expected to be a js function and compile_element just returns it,

The compile element function is usually called in a loop that reads words and compiles them.

function compile_words (delimiter)
{
  let words = [];
  let word;
  while ((word = read_word()) != delimiter)
  {
    if (word === undefined)
    {
      error('did not find a terminating', delimiter);
    }
    let element = compile_element(word);
    if (element)
    {
      words.push(element);
    }
  }
  return words;
}

This function reads words until it finds a delimiter and compiles them, appending them into an array, then it returns that array.

Then we can create a closure that retains this array and calls all the js functions in it.

function block (delimiter)
{
  let words = compile_words(delimiter);
  return () => { words.forEach((x)=>x()) }
}


The block function is the procedure the ':' defining word in the language uses to create new word definitions.

dictionary[':'] = (x) =>
{ 
  let name = read_name(': did not read a name'); 
  if (x)
  {
    temporary[name] = block(';');
  }
  else
  {
    last_defined = name;
    dictionary[name] = block(';');
    temporary = {};
  }
};


The x argument is the compiling true flag compile_element gives to the word when evaluates an immediate word.
The ':' word is an immediate word that does not return a result.

If it's compiling it will create a temporary word definition.

If not, it will create a definition in the dictionary

':' reads a name and compiles words until a terminating ';' character.

An example usage:

: oh 1 2 3 ;

This will be converted to a closure that retains a words array which are themselves functions and it just iterates them when is evaluated. To evaluate or compile a word we just type it and interpret_element or compile_element will receive it as argument.

In this case the 1 2 and 3 were converted to closures and appended to the words array.


In the code of ':' we can see that if (x) is true (it means we are compiling) it creates the definition in the temporary js object instead of the dictionary one.

We can also see that if we are not compiling (in the else part) the word is created in the dictionary and after that the temporary js object gets set to an empty object.

It means that after every colon ':' definition at the top level, the temporary words will be reset.

Temporary words are meant for helping at composition of words.

They are meant to be used to name behavior and help at writing small blocks that we can later compose.

An example of a temporary word:

: oh
  : meh 1 2 ;
  meh +
;

The function interpret_element receives ':' from the reader and performs dictionary[':']();

The ':' word executes and the x argument is false because interpret_element calls words without arguments, so the else code part of ':' executes.

In the execution of the ':' word name = 'oh' and then performs: dictionary[name] = block(';'); 

This starts compiling words with compile_element.

The compile_element function receives ':' as argument which evaluates since it's immediate.

Note that ':' is an immediate word that does not return results so nothing gets appended to the definition of 'oh'.

Then the ':' code of the if (x) is true part evaluates.

  if (x)
  {
    temporary[name] = block(';');
  }

It creates a temporary word named 'meh' that will push 1 and 2 when evaluated.

Both compile_element and interpret_element check for temporary words first so temporary words can shadow the ones in the dictionary.

When the definition of the meh temporary word ends, we are back to the compilation process of the word 'oh' which finds the word 'meh' and compiles it into the definition of 'oh'.