<commit_before>= Install guide

Assumptions:

* [x] You've installed Node 8.11+ on your machine.

On this page, you'll learn:

* [x] How to install Asciidoctor.js.
* [x] How to setup Asciidoctor.js in your JavaScript environment.

== Install Asciidoctor.js

Open a terminal and type:

[source]
$ npm i asciidoctor.js

NOTE: If you prefer Yarn over npm, you can install Asciidoctor.js using `yarn add asciidoctor.js`

Asciidoctor.js provides different builds for different JavaScript environments.
See below for a link to the right one and instructions on how to use it.

== Basic browser setup

Just include Asciidoctor.js in a script tag.
You can instantiate a processor using the `Asciidoctor` global.

```html
<script src="node_modules/asciidoctor.js/dist/browser/asciidoctor.js"></script>
```
```js
var asciidoctor = Asciidoctor();
```

== Node

```js
const Asciidoctor = require('asciidoctor.js');

const asciidoctor = Asciidoctor();
```

== AMD (System.js, RequireJS, etc)

```js
requirejs(['asciidoctor'], function (asciidoctor) {
  //...
});
```

== Webpack

```js
import Asciidoctor from 'asciidoctor.js';

const asciidoctor = Asciidoctor();
```

== Nashorn

```js
load('./node_modules/asciidoctor.js/dist/nashorn/asciidoctor.js');

var asciidoctor = Asciidoctor();
```

== What's next?

Now that Asciidoctor.js is installed, you are ready to take a xref:quick-tour.adoc[quick tour].<commit_msg>📝 Resolves #561, Document how to use Asciidoctor.js with GraalVM (#566)<commit_after>= Install guide

Assumptions:

* [x] You've installed Node 8.11+ on your machine.

On this page, you'll learn:

* [x] How to install Asciidoctor.js.
* [x] How to setup Asciidoctor.js in your JavaScript environment.

== Install Asciidoctor.js

Open a terminal and type:

[source]
$ npm i asciidoctor.js

NOTE: If you prefer Yarn over npm, you can install Asciidoctor.js using `yarn add asciidoctor.js`

Asciidoctor.js provides different builds for different JavaScript environments.
See below for a link to the right one and instructions on how to use it.

== Basic browser setup

Just include Asciidoctor.js in a script tag.
You can instantiate the processor using the `Asciidoctor` global variable.

```html
<script src="node_modules/asciidoctor.js/dist/browser/asciidoctor.js"></script>
```
```js
var asciidoctor = Asciidoctor();
```

== Node

```js
const Asciidoctor = require('asciidoctor.js');

const asciidoctor = Asciidoctor();
```

== AMD (System.js, RequireJS, etc)

```js
requirejs(['asciidoctor'], function (asciidoctor) {
  //...
});
```

== Webpack

```js
import Asciidoctor from 'asciidoctor.js';

const asciidoctor = Asciidoctor();
```

== Nashorn

.app.js
```js
load('./node_modules/asciidoctor.js/dist/nashorn/asciidoctor.js');

var asciidoctor = Asciidoctor();
```

.AsciidoctorNashorn.java
```java
import javax.script.ScriptEngine;
import javax.script.ScriptEngineManager;
import java.io.FileReader;
import java.io.File;

public class AsciidoctorNashorn {

  public static void main(String... args) throws Throwable {
    ScriptEngineManager engineManager = new ScriptEngineManager();
    ScriptEngine engine = engineManager.getEngineByName("nashorn");
    engine.eval(new FileReader("./app.js"));
  }
}
```

== GraalVM

=== Node.js application

https://www.graalvm.org/docs/reference-manual/languages/js/[GraalVM can run Node.js applications]. +
To install `asciidoctor.js` module, use the `npm` executable in the [.path]_/bin_ folder of the GraalVM package.

Create the following code snippet to a file named `app.js` and save it in the same directory where you installed the Node.js modules:

.app.js
```js
const Asciidoctor = require('asciidoctor.js');

const asciidoctor = Asciidoctor();
```

Then execute it on GraalVM using the `node` command (available in the [.path]_/bin_ folder of the GraalVM package):

 $ node app.js

=== Embed in a JVM-based application

https://www.graalvm.org/docs/graalvm-as-a-platform/embed/[With the Graal Polyglot API, you can embed JavaScript code in a JVM-based application].

IMPORTANT: The Graal Polyglot feature gives you a "pure" JavaScript (ECMAScript) engine, not a Node.js engine.
In other words, Node.js features such as `require` or core module such as `fs` won't be available.

To embed Asciidoctor.js in a Java application, create the following code snippet to a file named `app.js`:

.app.js
```js
var asciidoctor = Asciidoctor();
```

Copy the file `node_modules/asciidoctor.js/dist/graalvm/asciidoctor.js` in the resources of your application.
Then create a Java file named `AsciidoctorGraalVM.java` with the following content:

.AsciidoctorGraalVM.java
```java
import org.graalvm.polyglot.Context;
import java.io.IOException;
import java.net.URISyntaxException;
import java.nio.charset.StandardCharsets;
import java.net.URL;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.List;

public class AsciidoctorGraalVM {

  public static void main(String... args) {
    Context context = Context.newBuilder("js").allowIO(true).build();
    context.getPolyglotBindings().putMember("IncludeResolver", new IncludeResolver()); // <1>
    context.eval("js", "var IncludeResolver = Polyglot.import('IncludeResolver');");
    ClassLoader classLoader = AsciidoctorGraalVM.class.getClassLoader();
    context.eval("js", "load('" + classLoader.getResource("asciidoctor.js") + "')"); // <2>
    context.eval("js", "load('" + classLoader.getResource("app.js") +"')"); // <2>
  }

  public static class IncludeResolver {
    public String read(String path) throws IOException, URISyntaxException {
      Path filePath = Paths.get(path);
      List<String> lines;
      File file = filePath.toFile();
      if (file.exists()) {
        lines = Files.readAllLines(filePath, StandardCharsets.UTF_8);
      } else {
        Path fileName = filePath.getFileName();
        URL url = this.getClass().getClassLoader().getResource(fileName.toString());
        if (url != null) {
          lines = Files.readAllLines(Paths.get(url.toURI()), StandardCharsets.UTF_8);
        } else {
          lines = new ArrayList<>();
        }
      }
      return String.join("\n", lines);
    }

    public String pwd() {
      return Paths.get("").toAbsolutePath().toString();
    }
  }
}
```
<1> The `IncludeResolver` class will be used to read the content of a file when using the `include::` directive
<2> Make sure that `asciidoctor.js` and `app.js` are available in the classpath of the application

[TIP]
====
The source attribute of the https://github.com/graalvm/graaljs/blob/master/docs/user/JavaScriptCompatibility.md#loadsource[global `load` method] provided by GraalVM can be of type:

- a `String`: the path of the source file or a URL to execute.
- `java.lang.URL`: the URL is queried for the source code to execute.
- `java.io.File`: the File is read for the source code to execute.
====

== What's next?

Now that Asciidoctor.js is installed, you are ready to take a xref:quick-tour.adoc[quick tour].
{'fraction_non_alphanumeric': 0.12593337162550258, 'fraction_numerical': 0.0027283170591614015, 'mean_word_length': 4.288534548215641, 'pattern_counts': {'":': 0, '<': 14, '<?xml version=': 0, '>': 14, 'https://': 3, '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': '2748569', 'n_tokens_mistral': 2306, 'n_tokens_neox': 2234, 'n_words': 698}