Extensions

EasyCoder provides a core set of features that are likely to be useful in the majority of cases, but there may be times when you need something extra - a particular kind of calculation, maybe - and need to integrate it with your page. In such cases you probably know what JavaScript to write but need access to some of the EasyCoder variables. So we have a simple mechanism whereby you can add a function that has access to the inside of EasyCoder.

In your script you call an extension by using

extend {request} {data}

where {request} is a text string such as {recalculate} or {remove spaces} and {data} is any data value such as 123 or {Mike}. Both values must be provided even if you don't need one or both of them.

To create the extension, write a JavaScript function with the name EasyCoder_extension, taking 3 arguments;

program - will receive the entire EasyCoder program, an array of program commands plus some extra properties.
request - will receive the name of the request
data - will receive the extra data

You can use  a plugin such as Headers and Footers and put your script code there, to appear either on every page or on a specific page.

To test, add this to your page:

<pre id="easycoder-script" style="display: none;">!
! Extension test

  extend {something} 0
  stop

</pre>

then add the following JavaScript code to your page header:

<script>
  function EasyCoder_extension(program, request, data) {
    alert("This is the extension; request is "+request);
  }
</script>

When you load the page you should see a popup alert:

which tells you the extension has been called with "something" as the request. What you do next will require some understanding of the "program" argument, so here goes.

The Program

The program is mostly an array of commands, each one corresponding to a line of the script. The format should be fairly easy to decode; we suggest that you start off by logging it to your browser console. Here's the code to do it:

<script>
  function EasyCoder_extension(program, request, data) {
    console.log('Program: ' + JSON.stringify(program, null, 2);
  }
</script>

If you don't know how to get to your browser's console you may need to Google it. In Chrome it's in the Settings menu, at More Tools | Developer Tools.

The parts of the program you're most likely to be interested in are the variable declarations, which are usually at the top of a script. Each one describes the variable and has space for its contents, which are added and altered as the script runs. You can find the program command for any variable by asking the program itself, like this:

const pc = program.symbols[name].pc;

Here, name is the name of the variable. The value returned is the index of that variable in the program, which you can use like this:

const command = program[pc];

command will contain the full details of the variable, such as

  {
    "pc": 0,
    "domain": "basic",
    "keyword": "variable",
    "lino": 6,
    "isSymbol": true,
    "isValueHolder": true,
    "name": "N",
    "elements": 1,
    "index": 0,
    "value": [
      null
    ]
  }

Here the variable is called N. Its 'value' is an array having elements items; initially 1 as shown. The array has a single item, initially having the value null. The index property holds the current index of the array.

Let's see what happens when the script puts a value into one of its variables. For example, like this:

put 12345 into N

Now the variable looks like this:

  {
    "pc": 0,
    "domain": "basic",
    "keyword": "variable",
    "lino": 6,
    "isSymbol": true,
    "isValueHolder": true,
    "name": "N",
    "elements": 1,
    "index": 0,
    "value": [{
      "type": "constant",
      "numeric": true,
      "content: 12345
    }]
  }

The null has been replaced by a 'value' object, which can be a number, a string or a boolean. So if the assignment had been

put {the quick brown fox jumps over the lazy dog} into N

the variable would look like this:

  {
    "pc": 0,
    "domain": "basic",
    "keyword": "variable",
    "lino": 6,
    "isSymbol": true,
    "isValueHolder": true,
    "name": "N",
    "elements": 1,
    "index": 0,
    "value": [{
      "type": "constant",
      "numeric": false,
      "content: "the quick brown fox jumps over the lazy dog"
    }]
  }

though N is possibly a poor choice of name for a variable that is to hold text. Variables in EasyCoder can hold numeric, string or boolean values and change from one to another with any assignment. An array can have a different type in each of its elements.

The value pc in the data is the index of that object in the program array, so you can inspect any command to see what it does. To pass a value back to the script you simply update the content property in the appropriate item of its value array. The script will resume at the command following the extend, unaware that its data has been tampered with.