Security News
RubyGems.org Adds New Maintainer Role
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
asciidoctor.js
Advanced tools
A JavaScript AsciiDoc processor, cross-compiled from the Ruby-based AsciiDoc implementation, Asciidoctor, using Opal
= Asciidoctor.js: AsciiDoc in JavaScript powered by Asciidoctor Dan Allen https://github.com/mojavelinux[@mojavelinux]; Guillaume Grossetie https://github.com/mogztter[@mogztter]; Anthonny Quérouil https://github.com/anthonny[@anthonny] :idprefix: :idseparator: - :uri-nodejs: http://nodejs.org :uri-opal: http://opalrb.org :uri-asciidoctor: http://asciidoctor.org :uri-bower: http://bower.io :uri-repo: https://github.com/asciidoctor/asciidoctor.js :sources: {uri-repo} :license: {uri-repo}/blob/master/LICENSE :experimental: :endash:
ifdef::env-github[] image:http://img.shields.io/travis/asciidoctor/asciidoctor.js.svg[Build Status, link=https://travis-ci.org/asciidoctor/asciidoctor.js] image:http://img.shields.io/npm/v/asciidoctor.js.svg[npm version, link=https://www.npmjs.org/package/asciidoctor.js] endif::[]
This project uses {uri-opal}[Opal] to transcompile http://asciidoctor.org[Asciidoctor]—a modern implementation of AsciiDoc—from Ruby to JavaScript to produce [path]asciidoctor.js, bringing http://asciidoc.org[AsciiDoc] to the browser!
== Introduction
{sources}[Asciidoctor.js] is direct port of {uri-asciidoctor}[Asciidoctor] from Ruby to JavaScript using {uri-opal}[Opal], a Ruby-to-JavaScript transcompiler. It consists of a Rake build script that executes the Opal compiler on the Asciidoctor source code to produce the asciidoctor.js script. A Grunt build is used to assemble and prepare the distribution files, using the Rake build underneath.
Opal parses the Ruby code and any required libraries, then rewrites the code into JavaScript under the Opal namespace. The resulting JavaScript can be executed within any JavaScript runtime environment (such as a browser).
To interact with the generated code, you either invoke the JavaScript APIs directly, or you can invoke native JavaScript objects from within the Ruby code prior to compilation.
== Setup
To build [path]asciidoctor.js, you'll need some tools:
Start by cloning the source from GitHub:
$ git clone git://github.com/asciidoctor/asciidoctor.js
Next, switch to the asciidoctor.js directory and run npm's install
command followed by Bower's install
command:
$ cd asciidoctor.js $ npm install $ bower install
You're now ready to build asciidoctor.js.
TIP: Opal.js, The Ruby runtime in JavaScript is available in bower_components/opal/opal/current/opal.min.js
== Building asciidoctor.js
To build asciidoctor.js, simple run the Grunt dist
task from the root of the project:
$ grunt dist
NOTE: The build task will make some minor code changes on the asciidoctor submodule.
As you may know String are immutable in Javascript, so we need to replace gsub!
and sub!
methods.
These changes are made at build time to keep the Ruby code as fast as possible.
This command produces some files in the [path]dist directory:
Each file has a minified
and gz
version.
You'll see these scripts in action when you run the examples, described next.
== Building and running the examples
To build the examples, simply run the Rake examples
task from the root of the project:
$ grunt examples
This command produces another JavaScript file in the [path]build directory, [path]asciidoctor_example.js. This script includes:
All the JavaScript in that file was generated from a Ruby script by Opal.
Point your browser at [path]build/asciidoctor_example.html. You should see the AsciiDoc Syntax Quick Reference document. The content on the page was rendered from AsciiDoc by asciidoctor.js when you loaded the page!
== Using Asciidoctor in JavaScript
There are two ways to use the JavaScript version of Asciidoctor:
. Write code in Ruby that hooks into the native JavaScript environment, which Opal compiles into JavaScript . Invoke the JavaScript APIs that Opal generates directly from JavaScript
=== Using Asciidoctor and the native JavaScript environment from Ruby
First, we'll stuff some AsciiDoc content into a variable inside a Ruby script:
content = <<-EOS = asciidoctor.js, AsciiDoc in JavaScript Doc Writer docwriter@example.com
Asciidoctor and Opal come together to bring http://asciidoc.org[AsciiDoc] to the browser!
== Technologies
Next, we invoke Asciidoctor in Ruby just as we normally would:
We then use the global $window
object provided by Opal to register a listener that inserts the rendered HTML document into the page:
The final step is to compile this Ruby code into JavaScript using the Opal compiler.
When the [path]asciidoctor_example.js script is loaded by the browser, the Ruby code (compiled as JavaScript) is executed, rendering the AsciiDoc document and inserting the result into the page.
You can also invoke Asciidoctor directly from JavaScript.
== Using Asciidoctor from JavaScript
If you choose, you may use the Asciidoctor class that Opal generates directly from Ruby.
=== Front-end development
Once the package installed, you can add the following script
tag to your HTML page:
If you don't want to use extensions, you can load files separately :
IMPORTANT: To be successful with Asciidoctor.js, it's important to understand how to work with Ruby objects in the JavaScript environment. We recommend that you browse the http://opalrb.org/docs/using_ruby_from_javascript[Opal documentation] to learn how method names are mapped and what data types it expects.
Here is a simple example that converts AsciiDoc to HTML5 using the doctype: 'inline'
option and showtitle
attribute:
=== Back-end development
Once the package is installed, the first thing to do is to load the asciidoctor.js
module using require
, then you're ready to start using the API:
var asciidoctor = require('asciidoctor.js')(); // <1> var opal = asciidoctor.Opal; // <2>
var processor = null; var useExtensions = true;
if (useExtensions) { processor = asciidoctor.Asciidoctor(true); // <3> } else { processor = asciidoctor.Asciidoctor(); // <4> }
<1> Load the Asciidoctor.js library <2> Retrieve and alias the top-level Opal namespace <3> Instantiate Asciidoctor with extensions enabled <4> Instantiate Asciidoctor without extensions <5> Convert AsciiDoc content to HTML5 using Asciidoctor.js <6> Print the HTML5 output to the console
Save the file as sample.js
and run it using the node
command:
$ node sample.js
You should see the following output in your terminal:
[.output] .... Asciidoctor running on Opal brings AsciiDoc to Node.js!
....== Changes to Asciidoctor (from upstream)
Compiling Asciidoctor to JavaScript currently requires some changes in Asciidoctor. The goal is to eventually eliminate all of these differences so that Asciidoctor can be compiled to JavaScript as is.
Here's a list of some of the changes that are currently needed:
Named posix groups in regular expressions are replaced with their ASCII equivalent
[[:alpha:]]
)A shim library is needed to implement missing classes in Opal, such as File
and Dir
All mutable String operations have been replaced with assignments (this is done at build time)
$~[0]
used in place of $&
and $~[n]
in place of $n
after running a regular expression (where n is 1, 2, 3...)
Opal doesn't recognize modifiers on a regular expression (e.g., multiline)
Optional, non-matching capture groups resolve to empty string in gsub block in Firefox (see http://www.bennadel.com/blog/1916-different-browsers-use-different-non-matching-captured-regex-pattern-values.htm)
Assignments without a matching value are set to empty string instead of nil (in the following example, b
is set to empty string)
a, b = "value".split ',', 2
...
== Debugging
Compiling a Ruby application to JavaScript and getting it to run is a process of eliminating fatal errors. When the JavaScript fails, the message isn't always clear or even close to where things went wrong. The key to working through these failures is to use the browser's JavaScript console.
=== Chrome / Chromium
Chrome (and Chromium) has a very intuitive JavaScript console. To open it, press kbd:[Ctrl+Shift+J] or right-click on the page, select menu:Inspect Element[] from the context menu and click the Console tab.
When an error occurs in the JavaScript, Chrome will print the error message to the console. The error message is interactive. Click on the arrow at the start of the line to expand the call trace, as shown here:
image::error-in-chrome-console.png[]
When you identify the entry you want to inspect, click the link to the source location. If you want to inspect the state, add a breakpoint and refresh the page.
Chrome tends to cache the JavaScript files too aggressively when running local scripts. Make a habit of holding down kbd:[Ctrl] when you click refresh to force Chrome to reload the JavaScript.
Another option is to start Chrome with the application cache disabled.
$ chrome --disable-application-cache
=== Firefox
Firefox also has a JavaScript console. To open it, press kbd:[Ctrl+Shift+J] or right-click on the page, select menu:Inspect Element[] from the context menu and click the Web Console tab.
When an error occurs in the JavaScript, Firefox will print the error message to the console. Unlike Chrome, the error message is not interactive. Its power, instead, lies under the hood.
To see the call trace when an exception occurs, you need to configure the Debugger to pause on an exception. Click the Debugger tab, click the configuration gear icon in the upper right corner of that tab and click Pause on exceptions. Refresh the page and you'll notice that the debugger has paused at the location in the source where the exception is thrown.
image::error-in-javascript-debugger.png[]
The call trace is displayed as breadcrumb navigation, which you can use to jump through the stack. You can inspect the state at any location by looking through the panels on the right.
== Copyright
Copyright (C) 2014 Dan Allen, Guillaume Grossetie, Anthonny Quérouil and the Asciidoctor Project. Free use of this software is granted under the terms of the MIT License.
See the {license}[LICENSE] file for details.
FAQs
A JavaScript AsciiDoc processor, cross-compiled from the Ruby-based AsciiDoc implementation, Asciidoctor, using Opal
The npm package asciidoctor.js receives a total of 0 weekly downloads. As such, asciidoctor.js popularity was classified as not popular.
We found that asciidoctor.js demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 6 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.