Hiphop.js is JavaScript DSL for programming asynchronous applications. It executes on unmodified JavaScript engines, let them run on server-side or client-side.
The documentation is available in two formats:
| HTML generic documentation | Markdown commit documentation |
|---|---|
| HTML | markdown |
The HipHop.js installation depends on the JavaScript host
(see Installation chapter). The easiest way to install it is when using
npm. For that system, the installation is:
Until HipHop is released as an "official" npm package, use the following to install it.
npm install https://www-sop.inria.fr/members/Manuel.Serrano/software/npmx/hiphop.tgzWhen HipHop is officially released, the installation procedure is:
npm install @hop/hiphopCaution
npm install pkg searches recursively in the parent directories for a
directory named node_modules or a file named package.json. If it
finds any of the two, it installs pkg in that directory instead of
the current directory. Hence, if after issuing npm install hiphop you
don't see a node_modules created in the local directory, it's because
it has been installed in a parent directory.
Caution
To update HipHop with a new npm package, it might be needed to
flush its cache first. For that, run npm cache clean --force.
To test
npm test
In this introduction we merely show how to write and execute the "hello world" HipHop.js program, assuming a Node.js/NPM installation.
We consider a program stored in a file named hello.hh.js, .hh.js
being the suffix of HipHop source files. This program waits for two
events A and B to be received. It then emits itself the event
O. Each time the R event is received, the program returns to its
initial state.
// hello.hh.js
import { ReactiveMachine } from "@hop/hiphop";
const HelloWorld = hiphop module() {
in A; in B; in R;
out O;
do {
fork {
await (A.now);
} par {
await (B.now);
}
emit O();
} every (R.now)
}
The helloworld.hh.js program uses the HipHop.js syntactic extension
hiphop. This tag has to be compiled down to plain JavaScript before
being executed. This compilation can be executed in two ways.
- The standard way: the file
hello.hh.jsis compiled in advance withhhc, the HipHop compiler, and Node.js uses the result of this compilation.
./node_module/@hop/hiphop/bin/hhc.mjs hello.hh.js -o hello.mjs
nodejs --enable-source-maps hello.mjsUsing the Nodejs option --enable-source-maps ensures that if an error occurs
while executing the program, Nodejs will prompt the error in the original
HipHop source file instead of the file generated by hhc.
- **The easiest (but unportable) way **: just asks Nodejs to compile the file on the fly for you. For that, simply invokes Node.js as follows:
nodejs --enable-source-maps --no-warnings --loader ./node_modules/@hop/hiphop/lib/hiphop-loader.mjs hello.hh.jsAlternatively, this can be decomposed using the shell variable environment
NODE_OPTIONS:
export NODE_OPTIONS="--enable-source-maps --no-warnings --loader ./node_modules/@hop/hiphop/lib/hiphop-loader.mjs"
nodejs hello.hh.jsNote
In the future, the Nodejs' option --loader might be renamed.
Please check your setting for accomodating the future new name.
With this method, the program hello.hh.js will be silently compiled
into a ._hello.mjs and ._hello.mjs.map files. These are the files
that Nodejs will use for executinon.
Once compiled, in order to be executed, a HipHop program has be loaded into a reactive machine and executed from within JavaScript. Actually the HipHop execution is interleaved with the JavaScript execution.
flowchart LR
A[javascript] --> B{{mach.react}}
B --> C[javascript]
C -.-> A
Finally, to execute helloworld.hh.js from within a regular
JavaScript program, we create a machine and we proceed to reactions
(here 4 reactions are triggered).
const m = new ReactiveMachine(HelloWorld);
m.addEventListener("O", e => console.log("got: ", e));
m.react({ A: 1 });
m.react({ B: 2 });
m.react({ R: true });
m.react({ A: 3, B: 4 });Important
HipHop requires programs to use ECMAScript modules. They cannot be used with CommonJS modules.