Revision adf99ae03f070f11f40352ec9dbd26cb702f5605 authored by Andreas Stuhlmüller on 24 May 2017, 17:06:49 UTC, committed by GitHub on 24 May 2017, 17:06:49 UTC
Use latest version of uglify.
packages.rst
Packages
========
WebPPL packages are regular Node.js packages optionally extended to
include WebPPL code and headers.
To make a package available in your program use the ``--require``
argument:
.. code-block:: none
webppl myFile.wppl --require myPackage
WebPPL will search the following locations for packages:
1. The ``node_modules`` directory within the directory in which your
program is stored.
2. The ``.webppl/node_modules`` directory within your home directory.
Packages can be installed into this directory with
``npm install --prefix ~/.webppl myPackage``.
Packages can be loaded from other locations by passing a path:
.. code-block:: none
webppl myFile.wppl --require ../myPackage
Packages can extend WebPPL in several ways:
WebPPL code
-----------
You can automatically prepend WebPPL files to your code by added a
``wppl`` entry to ``package.json``. For example:
.. code-block:: json
{
"name": "my-package",
"webppl": {
"wppl": ["myLibrary.wppl"]
}
}
The use of some inference algorithms causes a caching transform to be
applied to each ``wppl`` file. It is possible to skip the application
of this transform on a per-file basis by placing the ``no caching``
directive at the beginning of the file. For example::
'no caching';
// Rest of WebPPL program
This is expected to be useful in only a limited number of cases and
shouldn't be applied routinely.
JavaScript functions and libraries
----------------------------------
Any regular JavaScript code within a package is made available in WebPPL
as a global variable. The global variable takes the same name as the
package except when the package name includes one or more ``-``
characters. In such cases the name of the global variable is obtained by
converting the package name to camelCase.
For example, if the package ``my-package`` contains this file::
// index.js
module.exports = {
myAdd: function(x, y) { return x + y; }
};
Then the function ``myAdd`` will be available in WebPPL as
``myPackage.myAdd``.
If your JavaScript isn’t in an ``index.js`` file in the root of the
package, you should indicate the entry point to your package by adding a
``main`` entry to ``package.json``. For example:
.. code-block:: json
{
"name": "my-package",
"main": "src/main.js"
}
Note that packages must export functions as properties of an object.
Exporting functions directly will not work as expected.
Additional header files
-----------------------
Sometimes, it is useful to define external functions that are able to
access WebPPL internals. Header files have access to the following:
- The store, continuation, and address arguments that are present at
any point in a WebPPL program.
- The ``env`` container which allows access to ``env.coroutine`` among
other things.
Let’s use the example of a function that makes the current address
available in WebPPL:
1. Write a JavaScript file that exports a function. The function will be
called with the ``env`` container and should return an object
containing the functions you want to use::
// addressHeader.js
module.exports = function(env) {
function myGetAddress(store, k, address) {
return k(store, address);
};
return { myGetAddress: myGetAddress };
};
2. Add a ``headers`` entry to ``package.json``:
.. code-block:: json
{
"name": "my-package",
"webppl": {
"headers": ["addressHeader.js"]
}
}
3. Write a WebPPL file that uses your new functions (without module qualifier)::
// addressTest.wppl
var foo = function() {
var bar = function() {
console.log(myGetAddress());
}
bar();
};
foo();
Package template
----------------
The `WebPPL package template`_ provides a scaffold that you can extend to create your own packages.
Useful packages
---------------
- `json`_: read/write json files
- `csv`_: read/write csv files
- `fs`_: read/write files in general
- `dp`_: dynamic programming (caching for mutually recursive functions)
- `editor`_: browser based editor
- `viz`_: visualization utilities
- `bda`_: data analysis utilities
- `agents`_: agent simulations
- `timeit`_: timing utilities
- `intercache`_: interpolating cache
- `oed`_: optimal experimental design
These packages are no longer maintained, but may be worth a look:
- `caches`_: cache inference results to disk
- `formal`_: static analysis in Racket for WebPPL
- `isosmc`_: utils for defining sequences of distributions for smc
.. _sweet.js: http://sweetjs.org
.. _sweet.js module documentation: http://sweetjs.org/doc/main/sweet.html#using-modules
.. _WebPPL package template: https://github.com/probmods/webppl-package-template
.. _json: https://github.com/stuhlmueller/webppl-json
.. _csv: https://github.com/mhtess/webppl-csv
.. _fs: https://github.com/null-a/webppl-fs
.. _dp: https://github.com/stuhlmueller/webppl-dp
.. _editor: https://github.com/probmods/webppl-editor
.. _viz: https://github.com/probmods/webppl-viz
.. _bda: https://github.com/mhtess/webppl-bda
.. _agents: https://github.com/agentmodels/webppl-agents
.. _timeit: https://github.com/stuhlmueller/webppl-timeit
.. _intercache: https://github.com/stuhlmueller/webppl-intercache
.. _oed: https://github.com/lydaniel/oed
.. _caches: https://github.com/iffsid/webppl-caches
.. _formal: https://github.com/kimmyg/webppl-formal
.. _isosmc: https://github.com/stuhlmueller/isosmc
![swh spinner](/static/img/swh-spinner.gif)
Computing file changes ...