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 one of the supported code styles (currently C and Racket block comments, or Lisp, Ruby, or TeX line comments). Koog also supports a restricted form of mixed-code generation where only specific regions of the source file are actually regenerated.
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) re-fed to the compiler as valid input.
Definition. The instructions, which are given in a (generator-dictated) generator language, are retained in the output.
Definition. 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.
Definition. 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.
Definition. A region and its enclosing markers together constitute a section.
Supports Racket version 6.
Includes a Racket 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).
The provided APIs are fairly self-explanatory, so look at the source code for the details of the provided functionality.
|(require koog/koog)||package: koog|
input : (or/c input-port? #f) output : (or/c output-port #f) filename : path-string?
|(require koog/runtime)||package: koog|
The koog/runtime module exports parameters that make context information available to code generation directives. It is not necessary to explicitly require this module, as its variables get set and bound for directives automatically by Koog.
|(require koog/cli)||package: koog|
The command-line interface is provided by the koog program, and it has various options whose combinations can cater for a number of use cases.
Here are some real-world Koog-based code generation examples from the ContextLogger2 codebase:
(require racket/list koog/koog)
(write (format "~a (default: ~a)"
(map symbol->string (comment-style-names))
***|# "c, lisp, racket, sh, tex (default: c)" #|***end***|
Racket. Version 6.0 (or higher) of Racket is required; a known-compatible version is 6.10.1.
The above commands should install the library, the koog command-line program, and a HTML version of the manual.
For information about configuring Emacs and Vim to use Koog, see the readme files in the "emacs" and "vim" directories of the source distribution.
Q: Where does the name "Koog" come from?
A: It is short for the Finnish word "koodigeneraattori" (code generator).
Except where otherwise noted, the following license applies:
Copyright 2008 Helsinki Institute for Information Technology HIIT and the authors. All rights reserved.
Authors: Tero Hasu
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.