Koog Manual

1 Concept

Mixed-code generation is a form of template-based code generation where the template file is overwritten with the generated file, with the code generation directives intact. The term was (as far as we know) introduced by Jack Herrington in his book Code Generation in Action (Manning, 2003).

Koog can function as a traditional mixed-code generator for a host language that uses C language style comments. Koog also supports a restricted form of mixed-code generation where only specific regions of the source file are actually regenerated.

2 Terminology

We define related terminology as follows:

Definition. A mixed-code generator is a compiler that modifies its input based on instructions found in the input itself, and produces output which can be (repeatedly) refed to the compiler as valid input. The instructions, which are given in a (generator-dictated) generator language, are retained in the output. The input may also include some (potentially foreign) host language text, and the goal typically is for the entire generator output to be a valid host language document. Specially formatted host language comments in the input function both as: directives specifying what text to generate; and as markers identifying the regions of host language text that are allowed to be replaced. A region and its enclosing markers together constitute a section.

3 Features

• Supports PLT Scheme version 4 and Racket (PLT Scheme version 5).

• Includes a Scheme API, command-line interface, and Emacs/Vim editor integration.

• It is possible to:

  • Expand all regions in a file, or only expand a chosen region (specified by line number).

  • Remove code generation directives (for one-off operations).

  • Simulate an expansion (see what would be changed without changes to the input file).

  • Filter standard input (and print the result to standard output).

4 API

The provided APIs are fairly self-explanatory, so look at the source code.

The primary module is koog/koog, which exports the koog-expand function, and some parameters affecting its behavior.

The koog/cli module only exports a main function that parses command-line options and accordingly sets parameters for koog-expand prior to invoking it.

The koog/runtime module exports parameters that make context information available to code generation directives. It is not necessary for directives to explicitly require this module.

5 Examples

Here are some real-world examples from the ContextLogger2 codebase:

• generating code for Symbian two-phase construction;

• generating boilerplate code for Lua bindings;

• fetching a multi-line string from a file and declaring it as a CPP (preprocessor) definition.

6 Source Code Repository

Koog source code is retrievable with Git:

git clone git://github.com/contextlogger/koog.git

7 Hardly Ever Asked Questions (HEAQ)

Q: Where does the name "Koog" come from?
A: It is short for the Finnish word "koodigeneraattori" (code generator).