<commit_before>ECTOPLASM
====

This is yet another bridge between NodeJS and PhantomJS.

[![Build Status](https://travis-ci.org/andrey-p/ectoplasm-js.svg?branch=master)](https://travis-ci.org/andrey-p/ectoplasm-js)

Why is this needed?
---

[node-phantom](https://github.com/alexscheelmeyer/node-phantom) is all nice and good but the callback system does get a bit clunky, e.g. if you're setting a bunch of properties at the same time.
Plus, it lacks the flexibility you'd get from using PhantomJS direct.

Using PhantomJS on its own is all good and nice but calling `exec` all the time and dealing with `stdout` and `stderr` is a faff, plus there's a noticeable delay every time you fire up PhantomJS.
This is annoying if you need to run your scripts multiple times in a row.

**Ectoplasm** tries to hit a happy middle, using node-phantom's sockets method to manage a continuous Phantom process but allowing you to run your own scripts.

Installing
---

`npm install --save ectoplasm`

API
---

### initialise(scripts, [options], callback) or initialize(scripts, [options], callback)

Pass your script names as an object, for instance:

```javascript
var ecto = require("ectoplasm"),
  scripts = {
    doThings: "/absolute/path/to/doThings.js"
  };

ecto.initialise(scripts, function (err) {
  // err is populated if it can't find the scripts
});
```

`options` is an object. The only supported option for the moment is `phantomPath`. Set this if your PhantomJS binary is not in your `$PATH`:

For instance, if you're using the excellent [phantomjs](https://www.npmjs.org/package/phantomjs) module, you'd do:

```javascript
var ecto = require("ectoplasm"),
  phantomjs = require("phantomjs"),
  scripts = {
    doThings: "/absolute/path/to/doThings.js"
  };

ecto.initialise(scripts, { phantomPath: phantomjs.path }, function (err) {
  // ...
});
```

### cleanup(callback)

Kills the Phantom process and stops the internal servers.

### run(scriptName, [args ...], callback)

Runs a script that you've previously loaded, for example:

```javascript
var ecto = require("ectoplasm"),
  scripts = {
    "doThings": "/absolute/path/to/doThings.js"
  };

ecto.initialise(scripts, function (err) {
  ecto.run("doThings", { foo: "bar" }, function (err, result) {
    // things have been done
  });
});
```

`args` is optional, and you can have as many of them as you want (or none at all) between your script name and callback.

Scripts
---

Your script must expose a single method called `run`, for example:<commit_msg>added note about serialisable properties in readme, closes #4<commit_after>ECTOPLASM
====

This is yet another bridge between NodeJS and PhantomJS.

[![Build Status](https://travis-ci.org/andrey-p/ectoplasm-js.svg?branch=master)](https://travis-ci.org/andrey-p/ectoplasm-js)

Why is this needed?
---

[node-phantom](https://github.com/alexscheelmeyer/node-phantom) is all nice and good but the callback system does get a bit clunky, e.g. if you're setting a bunch of properties at the same time.
Plus, it lacks the flexibility you'd get from using PhantomJS direct.

Using PhantomJS on its own is all good and nice but calling `exec` all the time and dealing with `stdout` and `stderr` is a faff, plus there's a noticeable delay every time you fire up PhantomJS.
This is annoying if you need to run your scripts multiple times in a row.

**Ectoplasm** tries to hit a happy middle, using node-phantom's sockets method to manage a continuous Phantom process but allowing you to run your own scripts.

Installing
---

`npm install --save ectoplasm`

API
---

### initialise(scripts, [options], callback) or initialize(scripts, [options], callback)

Pass your script names as an object, for instance:

```javascript
var ecto = require("ectoplasm"),
  scripts = {
    doThings: "/absolute/path/to/doThings.js"
  };

ecto.initialise(scripts, function (err) {
  // err is populated if it can't find the scripts
});
```

`options` is an object. The only supported option for the moment is `phantomPath`. Set this if your PhantomJS binary is not in your `$PATH`:

For instance, if you're using the excellent [phantomjs](https://www.npmjs.org/package/phantomjs) module, you'd do:

```javascript
var ecto = require("ectoplasm"),
  phantomjs = require("phantomjs"),
  scripts = {
    doThings: "/absolute/path/to/doThings.js"
  };

ecto.initialise(scripts, { phantomPath: phantomjs.path }, function (err) {
  // ...
});
```

### cleanup(callback)

Kills the Phantom process and stops the internal servers.

### run(scriptName, [args ...], callback)

Runs a script that you've previously loaded, for example:

```javascript
var ecto = require("ectoplasm"),
  scripts = {
    "doThings": "/absolute/path/to/doThings.js"
  };

ecto.initialise(scripts, function (err) {
  ecto.run("doThings", { foo: "bar" }, function (err, result) {
    // things have been done
  });
});
```

`args` is optional, and you can have as many of them as you want (or none at all) between your script name and callback.

**NOTE**: `args` is serialized to JSON as it's passed to the Phantom side. Be wary of trying to pass values that can't be serialized. For example:

```javascript
var args = {
  foo: "bar",
  baz: function () { return "Hello!"; }
};

// the frontend will only receive { foo: "bar" }
```

Scripts
---

Your script must expose a single method called `run`, for example:
{'fraction_non_alphanumeric': 0.12264678471575023, 'fraction_numerical': 0.0001863932898415657, 'mean_word_length': 4.0910815939278935, 'pattern_counts': {'":': 2, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 8, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2907046', 'n_tokens_mistral': 1730, 'n_tokens_neox': 1596, 'n_words': 645}