Introducing Objectos AsciiDoc. Objectos 0.6.0 released

Marcio Endo

@marcioendo

April 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.