Jamal

Jamal is a text macro and preprocessing language created by Hungarian software engineer Peter Verhás. Its single guiding idea is captured in the project’s own motto: when a piece of information already exists somewhere in a system or its documentation, it should never be copied by hand — the copy and any transformation should be automated. To that end, Jamal lets you mix ordinary text and markup with embedded macros; a processor reads the input, executes every macro, and emits a final document with all the macros expanded. The name originally stood for “Just Another Macro Language,” a wink at the Perl culture it was born in.

History & Origins

Verhás wrote the first version of Jamal in Perl in 1996, well before CSS, XML, and most modern markup tooling existed. He built it to solve a concrete, recurring annoyance: keeping technical documentation accurate. While maintaining the documentation for the ScriptBasic interpreter, he wanted code snippets and their output to appear in the docs without being manually pasted and re-pasted every time the code changed, and he wanted to generate consistent build files from a single source of truth. Jamal was the answer — a small command-line tool that processed .jam files into finished text.

The Perl edition was developed and used for many years, eventually reaching version 3.02, whose source is dated September 2010. It remained a personal but genuinely useful utility throughout that period, applied to HTML pages, configuration files, templates, and Makefiles.

Around 2018, after writing his first technical book and experimenting with related tooling, Verhás undertook a complete rewrite in Java. The new verhas/jamal repository was created in August 2018, and version 1.0.0 of the Java edition was published on 1 November 2018. The Java rewrite started deliberately small — reimplementing the exact macros that had served the Perl version for over a decade — and then grew far beyond the original, taking advantage of the JVM ecosystem.

Design Philosophy

Jamal is built around a deceptively simple model and a strong opinion about documentation.

• Text in, text out. The input is free text interleaved with macros; the output is the same text with every macro evaluated. Everything Jamal manipulates is ultimately a string — there is no separate type system to learn.
• Single source of truth. Rather than duplicating facts (a version number, a code example, a command’s output) across many documents, you keep the canonical value in one place and let Jamal pull it in wherever it is needed.
• Transparent meta-markup. Jamal is designed to layer on top of existing markup languages without getting in their way, so the same approach works for AsciiDoc, Markdown, XML, JSON, YAML, Javadoc, and plain text.

Key Features

Macros are written between delimiters that default to { and } (configurable, which is essential when the host markup itself uses braces). Jamal distinguishes two kinds of macros:

1. Built-in macros — implemented in Java (or other JVM languages such as Kotlin) and shipped with the tool. They cover control flow (if, for), definitions (define), file handling (include), evaluation (eval, script), and much more. Built-in macros are conventionally written with a # or @ prefix, which controls the order in which their content is evaluated relative to the macro itself.
2. User-defined macros — written in Jamal itself using the define macro, so authors can build reusable abstractions without writing any Java.

A minimal example defines a macro and then uses it:

{@define greeting(name)=Hello, name!}
{greeting/World}

which expands to:

Hello, World!

Beyond simple substitution, Jamal can include whole files or fragments of files, number and filter included lines, perform replacements and reordering, evaluate arithmetic, loop over values or directory contents, and run embedded scripts. By the 2.8.x releases the Java edition ships more than 200 built-in macros organized into modules, and it can be driven from a standalone CLI, Maven (as a plugin or extension), Javadoc (via a doclet), JBang, the JSR-223 scripting API, and editors such as IntelliJ and AsciidocFX.

Evolution

The Java edition advanced quickly. The 1.x line (2018–2022) re-established the classic feature set and added ecosystem integrations like the Maven plugin. Version 2.0.0 arrived in March 2023, restructuring the project’s modules, and development continued through to 2.8.2 in December 2024. Throughout, the project documented its own growth using Jamal — the repository’s README and reference docs are themselves .jam files.

According to the project’s distribution kits, the Java edition is packaged for Linux (Intel 64-bit), macOS (Intel and ARM), and Windows (Intel 64-bit). Jamal runs on the JVM, but the standalone installer kits reportedly bundle a Java runtime, so a separate Java installation is not strictly required to run them.

Current Relevance

In a February 2026 article reflecting on what he described as a roughly 30-year-old open-source project, Verhás announced that he was partially stepping back from active development of the Jamal software. He was careful to distinguish the tool from the idea behind it: he continues to advocate the philosophy that documents should be maintained by automation rather than manual copying. Jamal therefore remains available and usable — its source is on GitHub under the Apache 2.0 license — even as its original author shifts focus.

Jamal has always occupied a niche. It is not a general-purpose programming language and was never aimed at mass adoption; it is a specialist’s tool for people who care intensely about keeping documentation correct. Within that niche, its longevity is notable: few personal tools survive a complete language migration and remain in use across three decades.

Why It Matters

Jamal is a clear, long-running example of a domain-specific macro language built to scratch a real, persistent itch. Its story — born in Perl in 1996, reborn in Java in 2018, and maintained for nearly thirty years by a single dedicated author — illustrates how a focused tool can outlast the technologies it was first written in. More broadly, the principle it embodies, that information should live in exactly one place and be propagated automatically, anticipates the “docs-as-code” and literate-documentation movements that later became mainstream. For students of programming-language history, Jamal is a reminder that some of the most enduring languages are the small, opinionated ones designed to solve one problem well.