Spoon: Java source analysis and transformation with an AST

Spoon's source-level problem for Java tool authors

Spoon addresses the problem of writing Java tools that need meaningful access to source structure. Text matching becomes unreliable when a tool must recognize types, methods, statements, expressions, or inheritance-related constructs across varied formatting conventions. Spoon instead parses Java source and represents it as an abstract syntax tree that follows Java language concepts more closely.

The intended users are developers of compile-time analysis tools, source transformers, code generators, transpilers, and other Java metaprogramming systems. A caller can ask the library to parse source into a model, inspect that model through typed APIs, modify it, and print source derived from the resulting tree. This differs from a regular expression collection or a lightweight source-code search utility because the object being queried is the parsed program model.

Spoon does not present itself as a general Java compiler front end replacement. Its stated capabilities concern analyzing, rewriting, transforming, and transpiling Java source code. The repository also contains separate modules for areas such as control flow, dataflow, decompilation, documentation, visualization, and program manipulation. Those module names indicate a larger tool ecosystem, although the README does not document their setup or APIs.

Inside Spoon's parse, inspect, and print pipeline

The central mechanism is a source parser followed by an AST-backed metamodel. `Launcher.parseClass` accepts Java source expressed as a string and returns a `CtClass`, which is Spoon's model element for a class. The minimal README example passes a complete class declaration containing a method and a call to `System.out.println`.

This API shape matters because callers do not have to write their own lexical scanner and parser merely to begin examining source. They can parse a class, query the returned model, create or replace model elements, and request a textual representation. Spoon's stated design principles add constraints to this pipeline. The metamodel should remain close to Java language concepts, the model should be complete and sound, and printed text should be well formed and semantically equivalent to the original program. Transformation operators are intended to identify invalid programs through static type checking or dynamic checks.

The final design principle recognizes an important compromise: where practical, printed output should resemble the original source. This is a source-to-source transformation model, not merely an arbitrary AST printer. Even so, the README does not claim that formatting or comments will always be preserved. A project whose core requirement is byte-for-byte preservation would need to establish that behavior separately.

Installing Spoon 11.x and parsing a first Java class

Spoon is distributed to users as the Maven artifact `fr.inria.gforge.spoon:spoon-core`. Spoon 11.x requires JDK 17 or later. The host JDK requirement is separate from the Java language level of the source being parsed, so Spoon can consume older source syntax while still requiring JDK 17 to run.

Developers working on Spoon itself can clone the repository, compile it with Maven, and run its test suite. These are the exact commands documented in the README:

git clone https://github.com/INRIA/spoon
cd spoon
mvn compile

A successful compilation leaves the project compiled in the local Maven workspace. The README does not define a wrapper script or a particular artifact path to inspect.

To execute the repository test suite, use:

mvn test

For an application that depends on Spoon, add the Maven Central artifact `fr.inria.gforge.spoon:spoon-core` to the project's Maven configuration. The README links to Maven Central for the latest stable version but does not include a complete `pom.xml` dependency block, so this article does not invent one. The first source-model operation shown by the project is:

CtClass l = Launcher.parseClass("class A { void m() { System.out.println(\"yeah\");} }");

Call this from Java code with the relevant Spoon types available through the application dependency. The returned `CtClass` is the starting point for model inspection or transformation. The README does not document the exact output expected from printing this class.

Version compatibility, modules, and upgrade boundaries

The README maps runtime compatibility to major Spoon lines. Spoon 11.x needs JDK 17 or later, Spoon 10.x needs JDK 11 or later, and Spoon 9.x runs on Java 8. It also states that Spoon supports modern Java versions up to Java 25. A team adopting an older line therefore has two separate compatibility questions: which JDK launches Spoon, and which source language versions its parser and metamodel support.

The repository is not archived, and its last push was on 2026-10-16. Recent releases include `v11.5.1-beta-13` on 2026-10-11, `v11.5.1-beta-12` on 2026-10-04, and `v11.5.1-beta-11` on 2026-09-27. The visible release naming identifies these as beta releases rather than stable releases, while the README directs users who want the latest stable version to Maven Central. That distinction matters for production adoption because a beta line may carry a different compatibility or support profile from the stable artifact.

Based on the repository layout, Spoon is a multi-module Maven project. Top-level entries include `spoon-control-flow`, `spoon-dataflow`, `spoon-decompiler`, `spoon-javadoc`, `spoon-pom`, `spoon-smpl`, and `spoon-visualisation`. The README does not document whether all modules share the same version cadence or which are needed for a basic parse and transformation task. Upgrading therefore requires checking the selected modules' dependencies and supported APIs rather than assuming that the central artifact represents the entire repository.

Where Spoon's transformation model can fall short

Spoon is the wrong tool when the requested operation targets compiled JVM bytecode and source structure is irrelevant. The documented interface begins with Java source text and produces a source-oriented model. The README does not claim bytecode analysis, so selecting Spoon for a binary-only inspection task would impose an unsupported premise.

Source rewriting also has constraints that are easy to overlook. The AST models language concepts, but the actual quality of a transformation depends on the program passed into `Launcher.parseClass`, the APIs used to alter it, and the checks available in Spoon's current release. The design states that invalid transformations should be detected early through static type checking or dynamic checks, but that is a design objective rather than a guarantee that every transformation will compile or behave correctly. The transformation must still be tested against representative inputs.

There is another boundary around compatibility. A parser that supports source through Java 25 does not automatically mean that every transformation pattern is equally complete across those versions. The README does not publish a transformation-by-transformation compatibility matrix. It also does not document rollback, formatting preservation, comment retention, or a stable command for reversing a generated change. Those are not safe assumptions for a production refactoring tool.

CeCILL-C and MIT licensing choices for Spoon integrations

Spoon is described as free and open source and double-licensed under CeCILL-C and MIT. The repository contains `LICENSE-CECILL-C.txt`, `LICENSE-MIT.txt`, and `LICENSE-short.txt`, while GitHub classifies the top-level license as a custom type. The project's own README identifies CeCILL-C as the French equivalent to LGPL, but that description is not legal advice.

For an engineering adoption review, the double licensing means the actual distribution model matters. A team embedding Spoon in an internal analysis service, a developer tool, or a transformed-source product should inspect the repository license files and select the applicable option with its own compliance process. The README does not provide legal guidance about obligations for a particular deployment, nor does it promise one license applies automatically to every derived artifact.

Academic use has a separate documentation requirement rather than a separate stated license. The README asks academic users to cite the listed Software: Practice and Experience paper by Pawlak, Monperrus, Petitprez, Noguera, and Seinturier. Professional support is handled through a comment on GitHub issue 3251, while contribution documentation points new pull requests toward `doc`.

Spoon versus compiler APIs and ad hoc source parsers

The closest documented alternative is to use JDK compiler APIs and write source analysis around those APIs. That approach connects a tool to compiler-level structures and the platform's own compilation model, but it does not remove the need to interpret source constructs, assemble query logic, and define transformation behavior. Spoon instead packages source parsing and a Java-oriented metamodel into a dedicated `spoon-core` library.

Another alternative is a collection of regular expressions or a hand-written text parser. This can be adequate for a narrow, syntax-stable edit, but it has no shared program model and can become sensitive to formatting or source constructs outside its pattern. Spoon's paid cost is a library dependency plus the learning required for its model and transformation API. Its advantage is that parsing, inspection, and source rewriting operate around a shared AST rather than separate text-matching rules.

The distinction is not that Spoon removes all implementation work. Teams still define which classes, methods, and expressions matter, how they detect a transformation, and how they validate the result. Spoon supplies the source-model foundation; it does not decide which refactoring or analysis policy a tool should enforce.

Editorial conclusion

Spoon is appropriate for Java tool authors that need programmatic access to a source-level AST for analysis, rewriting, transformation, or transpilation. It is a poor fit for developers seeking a command-line utility or for tasks that operate only on compiled JVM bytecode. Before adoption, verify that the selected Spoon release supports the source language level, confirm that JDK 17 or later is available for Spoon 11.x, and decide whether double licensing under CeCILL-C and MIT meets the project's distribution requirements.

Frequently asked questions

Official sources

1. INRIA/spoon on GitHub
2. Issues
3. Project website
4. README
5. Releases