es-vm/README.md

A visual machine run in ES env like Node/Browser

# Installation
    npm install esvm
# What to do

**ESVM** is a virtual machine used to run async/sync program by ECMAScript engine. 
It provides RPC, Statement and Scope to help to design a execution tree.
With ESVM you can easily define statement using the provided template and
fetch response from remote with RPC module.

# How to use
## ESVM

**Life Cycle of ESVM**

* `bootstrap` - vm start.
* `load program` - load the defined statement into vm.
* `program run` - run the statement.
* `halt` - vm stops if program end or meets error.

ESVM will be blocked and stop running in several circumstances. The block status can be resumed and 
make the vm continue to run from the last stop position.  

**Quick Example**

```Javascript
const {ESVM} = require('esvm')

// Get vm instance.
const vk = new ESVM();

// Define a simple statement.
const program = new Statement();
program.execute = function* (vm) {
    yield 'hello';
};

// Load the statement into vm.
vk.$loadProgram(program);

// Run the statement.
// VM will halt when execution completed.
vk.$launch();
```

## statement

In ESVM, we define a statement template and it can be easily used to implement more complicated statement.
User can define their own statement class by inheriting from `Statement` class and then override the `constructor`、`execute` function.

**Example**

```Javascript
const {Statement} = require('esvm');

// Define a simple statement.
const program = new Statement();

// Implement execute function.
program.execute = function* (vm) {
    yield [statement_1];
    yield [statement_2];
    ...
    yield [statement_n];
};
```

## rpc

ESVM can send message to remote and get response synchronouslys or asynchronously.
`fetch()` is called to start a RPC request, then an event named `fetch` will be emmited,
vm will be blocked and wait for response from remote.
Response is in a format like {ret, err} and we can simplely set the value through `rpc.setRet(val)` & `rpc.setDate(val)`

**Default Response**

{ret: null, err: null}

**Async Call**

Pass a `process` function to async(), and the function will be wrapped with a promise
by async() implementation. Promise can be returned from `process` function, and it will
be executed after the previous promise.

```Javascript
rpc.async(vm => {
    // Can rpc.setRet & setError in async().
    // Use vm to access vm-instance of the rpc anywhere.

    // Some code here
    ... 

    return new Promise((resolve,reject) => {
        // Some code ...
    });
});
```
# License
[MIT](LICENSE)