Introducing Picocog
Picocog is a lightweight and new open-source Java library designed to assist programmatic code generation.
What is code generation?
Code generation is the process by which source code can be automatically generated based on some inputs. We describe this set of inputs as a “model”.

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.
The Model
A code generator designed to leverage Picocog typically utilises a PoJo model as a source of model data (but could also use Java Source code + annotations as a model, ala JSR-269).
For this use-case, we define a sample Pojo model — as shown below (omitting getters / setters for brevity).

This Pojo model is typically instantiated from the following types of sources:
- JSON / XML / YAML / CSV / etc.
- Via Database Query
- DSL (domain specific language)
For example:

NOTE: It is important that the when instantiation 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 core three goals:
- To generate cleanly indented code easily.
- To support out of sequence line injection.
- Be easy to debug.
Picocog in practise
Picocog can be thought of as a code-generation-centric alternative to StringBuilder. Picocog simply writes lines and the current indentation level is remembered.
The only class that is required to use is the PicoWriter class.
There is no need to manually place indents into literal string 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

Generated Classes


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.
Sometimes a small implementation is all you need.
JSR 269 — Annotation Processing
JSR 269 is a feature of Java, added in Java 6, that allows a pre-processor (or pre-compilation) step to iterate over Java source code (or other assets), then do something — typically code generate.
This can happen as part of a compile, but it can also be hooked up to an IDE, so that every time source is altered, the generated source is updated in the editor.
JSR 269 allows Java Source code, typically annotations on Java Source code, to act as a model from which to generate source code. The purpose of this is to allow boiler plate code to be automatically written rather than mandated to be manually created.
Picocog’s role is simply to make the laying out of the source code easier.
Picocog is 100% model-agnostic, but JSR-269 is especially useful in GWT use-cases.
Alternatives
The xtend language is a full features alternative and has a mountain of features. If you have extremely complex requirements, then check out xtend.
Availability
Picocog is available today on github under the Apache V2 license.
Other Articles
For a more in depth discussion of code generation “Code Generation For Dummies” by Matthew Fowler is highly recommended.
