HipHop ====== The `"hiphop"` JavaScript module contains utilities for creating and running HipHop reactive machines. Use `import * as hiphop from "@hop/hiphop"` to use it. Once defined, a HipHop program must be _loaded_ into a HipHop *reactive machine* that execute this program by running _reactions_. A reactive machine is an instance of the JavaScript `ReactiveMachine` class which is exported by the `@hop/hiphop` module. Creating HipHop Reactive Machines --------------------------------- ### new hiphop.ReactiveMachine(hhprgm [, opts]) ### ```javascript import { ReactiveMachine } from "@hop/hiphop"; import { mod } from "./prgm.hh.js"; const m = new ReactiveMachine(mod); ``` The optional `opts` argument can be: * a string, in which case, it designated the machine's name, which is used only for debugging purpooses; * a object. If `opts` is an object, its optional properties are: * `name` (string), a debugging name, as if `opts` was a string; * `dumpNets` (boolean), dump the net list generated by the HipHop compiler; * `verbose` (number), show additional warning messages, defaults to `2`; * `sweep` (boolean), enable the net list optimizer, defaults to `true`; * `dynamic` (boolean), enable dynamic program modification, defaults to `false`; * `tracePropagation` (boolean), a debugging facility for tracing the execution of the net list, defaults to `false`; * `traceReactDuration` (boolean), execution time profiling, defaults to `false`; * `traceCompilationDuration` (boolean) , compilation time profiling, defaults to `false`; * `causalityErrorTrace` (`shallow` or `deep`), how to display causality errors, defaults to `deep`. Running HipHop Reactive Machines -------------------------------- ### mach.react(sigset) ### The `react` function machine reactions. If called with no argument, it proceed to one step. If called with one or several arguments, it proceeds as follows for each argument: * a `sigset` is either * a JavaScript string `signame`. The signal `signame` is emitted with no value. * a JavaScript object. For each property `pname` with value `pval` in `sigset`, the eponym signal is emitted with `pval`. * runs a reaction. The `react` function returns the machine itself. Example: ```javascript // proceed to one reaction m.react(); // proceed to 4 reactions, with first the signal O emitded with value 24, // P with value 53, then a second reaction with only o emitted with value 56, // ... m.react({ O: 24, P: 53 }); m.react({ O: 56 }); m.react({ O: 77 }); m.react({ P: 10 }); ``` After a reaction, each output signal of the main program module is bound in the machine as a JavaScript property. For instance, is a reaction emits the signal `O` with value `1` at the first reaction of the machine `m` and `O` with value `2` at the second reaction, checking `m.O` after that reaction would return: ``` { nowval: 2, preval: 1, now: true, pre: true } ``` For symmetry with the argument of the `react` method, its returned value is an object whose property names are the names of the signal emitted during the reaction and the property values the values associated to these signals. ### mach.init(values) ### Set the value of the machine's main module parameters. Can only be executed once, and before the machine first reaction. ★ Example: [trap-kill.hh.js](../test/trap-kill.hh.js) ### mach.input(sigset) ### The `input` function emits signal in the machine but does not triggers the reaction. For instance, ```javascript m.input({ O: 24 }); m.input({ P: 53 }) m.react(); ``` Is equivalent to ```javascript m.react({ O: 24, P: 53 }) m.react(); ``` ### mach.age() ### Return the number of reactions `mach` has already executed. ### mach.name() ### Return the machine name. Interfacing with HipHop Reactive Machines ----------------------------------------- ### mach.promise(ressigname = "res", rejsigname = "rej") ### Return a promise that resolves when the machine emits the signal named `ressigname` and that rejects when the machine emits the signal named `rejsigname`. The machine must define the two output signals `ressigname` and `rejsigname`. ★ Example: [promise.hh.js](../test/promise.hh.js) ### mach.addEventListener(signame, listener) ### Associate a listener to the machine event `signame`. Listeners are invoked with one object with one or two fields: * `signame`: the name of the emitted output signal; * `preval`: the value of the signal at the previous reaction; * `nowval`: the value of the signal at the end of the reaction. This field exists only for valued signals. This field is immutable; The `stopPropagation()` is a method that, if called within the listener, will inhibit the call of others callback mapped on this signal. ★ Example: [reactfun.hh.js](../test/reactfunc.hh.js) ### mach.removeEventListener(signame, listener) ### Remove the listener from the machine. ### mach.bindEvent(event, obj) ### A shortcut for: ```javascript obj.addEventListener(event, e => mach.react({ [ event ]: e.value })); ``` - - - - - - - - - - - - - - - - - - - - - - - - - - - [[main page]](../README.md) | [[documentation]](./README.md) | [[license]](./license.md)