Introducing Picocog: A Lightweight Code Generation Library

Picocog is a lightweight and new open-source Java library created to make programmatic code generation quite easy.

Code generation is the process by which source code can be automatically generated based on inputs.

Code generation typically works as follows:

• Define a model/use an existing model.
• Interrogate model and generate source-code
• Upon changes to the model, regenerate source-code.

Plain Old Java Objects

A code generator designed to leverage Picocog typically utilizes a POJO model as a source of model data.

A sample POJO model is shown below (omitting getters/setters for brevity).

A sample POJO model

This POJO model is typically instantiated from the following types of sources:

• JSON/XML/YAML/CSV
• Via database query
• DSL (domain specific languages)

For example:

XML representation of the model

NOTE: It is important that the when instantiating the POJO model that a full set of validations are performed and assumptions tested. XML schema or a bespoke DSL implementation can ensure referential integrity and other validations.

Code Generation

Picocog emits text via Java code. No templates, no reflection, no tag processing. It has three core goals:

• Generate cleanly indented code easily.
• Support out-of-sequence line injection.
• Be easy to debug.

Picocog in Practice

Picocog can be thought of as a code-generation-centric alternative to StringBuilder. Picocog simply writes lines — the current indentation level is remembered.

The only class that is required is the PicoWriter class.

There is no need to manually place indents into string literals, but there is a need to flag the indent left and write lines of code via the writeln_r(), writeln_l() and writeln_lr() methods.

Sometimes it is handy to want to write to two or more locations in a document simultaneously — and have those locations have their own indentation stack. To do this, you add a placeholder via the createDeferredWriter() method. The returned writer can be thought of as a pointer to the line on which it was created.

Sample Usage of Picocog

The code generation source code:

Generated Classes

Customer.java (generated by Picocog):

Order.java (generated by Picocog):

Escaping

The initial release of Picocog does not support any kind of textual escaping. Either write your own escaping code (quite easy) or leverage a library such Commons Lang for your text escaping needs.

Language Support

Picocog is written in Java, but it can emit code in any language. A code generator can be created such that C#, Java, JavaScript, and more may be emitted from a single model, including annotations attached to Java code (via JSR 269).

Sometimes a small implementation is all you need.

Another non-template based approach for code generation is the excellent xtend language.

For a more in depth discussion of code generation, see the excellent article “Code Generation For Dummies” by Matthew Fowler.

Availability

Picocog is available today on GitHub.

Picocog is available on Maven Central at the following coordinates (jarfile can be downloaded here too):

   <dependency>

      <groupId>org.ainslec</groupId>

      <artifactId>picocog</artifactId>

      <version>1.0.2</version>

   </dependency>