Introducing Objectos AsciiDoc. Objectos 0.6.0 released

Marcio EndoMarcio EndoApr 9, 2023

Welcome to Objectos Weekly issue #021.

I have released Objectos 0.6.0! It introduces Objectos AsciiDoc, an AsciiDoc processor written in pure Java.

In this issue I will give a very short introduction to Objectos AsciiDoc. Just know that it is not ready for general use. At all.

Let's begin.

Objectos AsciiDoc

The following Java program illustrates a use of Objectos AsciiDoc:

import objectos.asciidoc.AsciiDoc;public class Example {  public static void main(String[] args) {    var asciiDoc = AsciiDoc.create();    var source = """    = Hello Objectos AsciiDoc    Let's see some of the implemented    AsciiDoc language features    == Section title    A paragraph followed by a list.    * item 1    * item 2    [,java]    ----    class Foo {}    ----    """;    var processor = new MyProcessor();    asciiDoc.process(source, processor);  }  private static class MyProcessor extends AbstractAsciiDocProcessor {    ...  }}

So you need three things:

  • an instance of objectos.asciidoc.AsciiDoc. This is the class responsible for parsing the AsciiDoc document;

  • a String instance with your AsciiDoc document source code; and

  • an instance of objectos.asciidoc.AsciiDoc.Processor. This class will be responsible for generating our output. We will see its code in a bit.

Then you invoke the process method of the first passing along the last two:

asciiDoc.process(source, processor);

Let's take a look at the MyProcessor class

The MyProcessor class

Objectos AsciiDoc currently offers a visitor-style API for processing the parsed AsciiDoc document.

In the MyProcessor class we use this API to generate a "hand-written" HTML of the processed AsciiDoc:

import static java.lang.System.out;private static class MyProcessor extends AbstractAsciiDocProcessor {  @Override  public void headingEnd(int level) {    out.print("</h");    out.print(level);    out.println(">");    out.println();  }  @Override  public void headingStart(int level) {    out.print("<h");    out.print(level);    out.print(">");  }  @Override  public void unorderedListEnd() { out.println("</ul>"); out.println(); }  @Override  public void unorderedListStart() { out.println("<ul>"); }  @Override  public void listItemEnd() { out.println("</li>"); }  @Override  public void listItemStart() { out.print("<li>"); }  @Override  public void paragraphEnd() { out.println("</p>"); out.println(); }  @Override  public void paragraphStart() { out.print("<p>"); }  @Override  public void sourceCodeBlockEnd() { out.println(); out.println("</code></pre>"); }  @Override  public void sourceCodeBlockStart(String language) {    out.print("<pre><code style=\"");    out.print(language);    out.println("\">");  }  @Override  public void text(String s) { out.print(s); }}

Notice at the very top that we are static importing java.lang.System.out. In other words, we are writing the output straight to it.

Running our example

Let's run our program. When executed it prints:

<h1>Hello Objectos AsciiDoc</h1>

<p>Let’s see some of the implemented
AsciiDoc language features</p>

<h2>Section title</h2>

<p>A paragraph followed by a list.</p>

<ul>
<li>item 1</li>
<li>item 2</li>
</ul>

<pre><code style="java">
class Foo {}
</code></pre>

Objectos AsciiDoc also supports inline elements such as:

  • italic

  • bold

  • monospace

  • inline macros

On the other hand it does not support many elements. For example:

  • tables

  • comments

  • includes

  • conditionals

  • and others

The AbstractAsciiDocProcessor class

For completeness, let's take a look at the AbstractAsciiDocProcessor code.

The AbstractAsciiDocProcessor class:

  • implements the objectos.asciidoc.AsciiDoc.Processor interface; and

  • provides an "empty" implementation for all of the methods.

Like so:

import objectos.asciidoc.AsciiDoc;import objectos.asciidoc.DocumentAttributes;import objectos.asciidoc.InlineMacroAttributes;import objectos.asciidoc.LinkText;public abstract class AbstractAsciiDocProcessor implements AsciiDoc.Processor {  @Override  public void boldEnd() {}  @Override  public void boldStart() {}  @Override  public void documentEnd() {}  @Override  public void documentStart(DocumentAttributes attributes) {}  ...}

I did not list all of the methods.

Objectos 0.6.0 is an alpha release

I use Objectos in production and the Objectos documentation is generated using Objectos AsciiDoc.

However, please know that Objectos 0.6.0 is an alpha release. In particular:

  • it is not stable. I expect it to fail if you deviate slightly from the use-case shown here;

  • there may be breaking API changes between releases; and

  • documentation is a work in progress.

Until the next issue of Objectos Weekly

So that's it for today. I hope you enjoyed reading.

The source code of all of the examples are in this GitHub repository.

Please send me an e-mail if you have comments, questions or corrections regarding this post.