improve documentation for compiling scxml about scion

[jbeard4]

Regarding console.log, the code executed inside of a script tag executes inside of a node.js vm environment. By default, this environment does not have any globals, including the node.js globals like process, require, or the built-in console. For this reason, model.prepare accepts an argument executionContext, which allows you to easily set up globals in the script environment.

For example, here's how you set up console.log:

    model.prepare(function(err, fnModel) {
      //...
    }, {console : console})

The executionContext argument is used to set up the sandbox passed to vm. For more information about this, see the vm module here: https://nodejs.org/api/vm.html#vm_script_runinnewcontext_sandbox_options

This is one of those features that should probably be better document.

[jbeard4]

I see several problems with the documentation:
What's the difference between the several functions mentioned under the instantiation section here:
https://github.com/jbeard4/SCION/blob/master/README.md
to compile SCXML to model? I can't get any of them to work.
In scxml.documentStringToModel(url,scxmlDocString,function(err, model){} [, context]), what's supposed to go into the 'url' parameter?

That param is optional and can be null. It's used when evaluating the document string using the vm module, and can give you a more sensible stack trace.

And how are these functions related to the json2model function? How can I access the latter one? It is mentioned here:
https://github.com/jbeard4/SCION/wiki/nodejs-api#json2model

That API is deprecated. A lot of the wiki pages are stale and refer to previous versions of SCION. I should go back and clean those up.

Also there were cli commands mentioned here:
https://github.com/jbeard4/SCION/wiki/test#Usage
Where are they supposed to be executed? Don't work on the linux bash, nor on the node cli.

Also deprecated. The next version of SCION will include an improved CLI.

So, all together, how do I get the 'scxml to model' process done in nodejs (or at least in any cli)? Is there a simple, working implementation example for nodejs available?
(A self written model in scions Statecharts Model Schema runs fine with scion-core. But I want to pass scxml from a visual editor.)
Thank you very much.

Follow the quickstart:

scxml.urlToModel("drag-and-drop.xml",function(err,model){

  if(err) throw err;

  model.prepare(function(err, fnModel) {

    if(err) throw err;

    //instantiate the interpreter
    var sc = new scxml.scion.Statechart(fnModel);

    //start the interpreter
    sc.start();

    //send the init event
    sc.gen({name:"init",data:rect});

  });
})

[jbeard4]

You could also try the repl in bin/repl.js. It just takes a path to an SCXML file as a single parameter.

[pkoevesdi]

Hey,
thanks for Your reply. I had hard times to make the quickstart example work. In the end, I think it were several hitches:

1. I mixed the syntax from https://github.com/jbeard4/SCION-CORE#api with the one from here: https://github.com/jbeard4/SCION#quickstart . it's a difference in the Class name: scxml.scion.Statechart vs. scion.Statechart
2. I variantly installed and required scion-core, scion and scxml. scxml is the only one needed and includes scion-core. (Can You confirm?)
3. Maybe I had a permission problem while installing scxml, it wasn't able to install eslint dependency, and I didn't see that early.

So, I'd say, it was a mix of my stupidity and lack of clear distinction between the packages scion, scxml, scion-core, also in the documentation.

I wasn't aware of the repl.js. Is that mentioned somewhere in the docs?
Inside that I find the parameter interpOpts passed to the class instantiation
var interpreter = new scxml.scion.Statechart(fnModel, interpOpts);
Also, the
repl.start('#', process.stdin, processEvent);
has more parameters than in the quickstart example.
Is there an explanation for these parameters somewhere?

One question concernig the quick start is left to me: How can I access the sc object outside the urlToModel function?

[jbeard4]

Hey,
thanks for Your reply. I had hard times to make the quickstart example work. In the end, I think it were several hitches:

I mixed the syntax from https://github.com/jbeard4/SCION-CORE#api with the one from here: https://github.com/jbeard4/SCION#quickstart . it's a difference in the Class name: scxml.scion.Statechart vs. scion.Statechart
I variantly installed and required scion-core, scion and scxml. scxml is the only one needed and includes scion-core. (Can You confirm?)

Yes, SCION bundles SCION-CORE. This is primarily to support the SCION build published to CDNJS. I would publish SCION-CORE separately to CDNJS, but projects published to CDNJS need at a mimumum 100 stars on github, so for now, I have to bundle SCION-CORE with SCION.

Also, there's a strong dependency between the SCJSON object compiled by SCION, and the interpreter in SCION-CORE, so it makes sense to publish them together.

Maybe I had a permission problem while installing scxml, it wasn't able to install eslint dependency, and I didn't see that early.

I'm not aware of an eslint dependency in SCION or SCION-CORE.

So, I'd say, it was a mix of my stupidity and lack of clear distinction between the packages scion, scxml, scion-core, also in the documentation.

I wasn't aware of the repl.js. Is that mentioned somewhere in the docs?

Not mentioned in the docs. More of a proof-of-concept/development tool at this point, and something which will change in the next version of SCION. You run it with node bin/repl.js path/to/statechart.scxml.

Inside that I find the parameter interpOpts passed to the class instantiation
var interpreter = new scxml.scion.Statechart(fnModel, interpOpts);
Also, the
repl.start('#', process.stdin, processEvent);
has more parameters than in the quickstart example.
Is there an explanation for these parameters somewhere?

I have prepared some jsdocs for the next version of SCION which document all the interpreter options, but have not published yet.

One question concernig the quick start is left to me: How can I access the sc object outside the urlToModel function?

Declare a variable outside the scope of urlToModel closure, and assign variable sc to that variable.

[pkoevesdi]

Hallo,
thanks again for You help!

So, I tried to run any java defined in the scxml file - no luck.
Maybe You could help me with this.
This is my scxml for test purposes:

<scxml initial="state1" version="1.0" xmlns="http://www.w3.org/2005/07/scxml">
	<state id="state1">
		<onentry>
			<script>console.log('entering state1, console log');</script>
			<log expr="'state1, scxml log'" label="entering"/>
		</onentry>
		<transition event="event1" target="state2">
		</transition>
	</state>
	<state id="state2">
		<onentry>
			<script>console.log('entering state2, console log');</script>
			<log expr="'state2, scxml log'" label="entering"/>
		</onentry>
		<transition event="event2" target="state1">
		</transition>
	</state>
</scxml>

the machine throws out:

entering state1, scxml log
entering state2, scxml log
entering state1, scxml log

So, the <script>console.log('entering state1, console log');</script> are simply ignored. Can You confirm, that it should throw out:

entering state1, console log
entering state1, scxml log
entering state2, console log
entering state2, scxml log
entering state1, console log
entering state1, scxml log

What can I do to achieve this? Maybe pass a command as a string out of the state model and execute that string outside?

Declare a variable outside the scope of urlToModel closure, and assign variable sc to that variable.

Doesn't work either. It must be something with sc being set inside the callback function of pathToModel or of model.prepare. However, I can access sc from outside after waiting some time (1s). So, after and outside the quickstart part, i do
setTimeout(function(){console.log('sc:',sc)},1000);
and I get the sc content.
Maybe, there is a smart way of having an event when sc is ready?

A different approach: a friend of mine just wrote a wrapper:

/*
 *  Async wrapper around scxml
 *  Note: not tested in depth!
 */

async function main() {
var fnModel;
try {
const pathToModel = util.promisify(scxml.pathToModel);
const model = await pathToModel("testmodel.scxml");
const prepare = util.promisify(model.prepare.bind(model));

fnModel = await prepare();

} catch (e) {
console.error(e);
}
async_sc = new scxml.scion.Statechart(fnModel());
async_sc.start();

async_sc.gen({
name: 'event1'
});
async_sc.gen({
name: 'event2'
});

}

/**
* The fraud main function
*/
main()

With that I can use async inside the main function. Do you consider this a good approach?

Btw.:
repl.js throws:

{ Error: write EPIPE
    at _errnoException (util.js:1022:11)
    at ReadStream.Socket._writeGeneric (net.js:780:25)
    at ReadStream.Socket._write (net.js:799:8)
    at doWrite (_stream_writable.js:397:12)
    at writeOrBuffer (_stream_writable.js:383:5)
    at ReadStream.Writable.write (_stream_writable.js:290:11)
    at ReadStream.Socket.write (net.js:717:40)
    at cursorTo (readline.js:1065:12)
    at REPLServer.Interface._refreshLine (readline.js:339:3)
    at REPLServer.Interface.prompt (readline.js:254:10) code: 'EPIPE', errno: 'EPIPE', syscall: 'write' }

(On windows 10 cmd).

[jbeard4]

Regarding sc being available outside of pathToModel, pathToModel is asynchronous, so you need to deal with that asynchronous behavior. It looks like the code snippet you posted is one way to do that, using promises.

[jbeard4]

Regarding repl.js, I have only tested it on Linux and OS X. Windows 10 might work, but should be considered unsupported.

[pkoevesdi]

Oh, great!!!! Now I got the Javascript from scxml up and running. Very nice! Thank You very much for Your help!

[jbeard4]

You are welcome