https://github.com/forge/roaster
A Java Parser library that allows easy parsing and formatting of Java source files
https://github.com/forge/roaster
Last synced: 4 months ago
JSON representation
A Java Parser library that allows easy parsing and formatting of Java source files
- Host: GitHub
- URL: https://github.com/forge/roaster
- Owner: forge
- License: other
- Created: 2013-03-22T17:29:33.000Z (almost 13 years ago)
- Default Branch: master
- Last Pushed: 2025-04-14T11:54:55.000Z (11 months ago)
- Last Synced: 2025-04-28T13:59:30.098Z (11 months ago)
- Language: Java
- Homepage:
- Size: 1.96 MB
- Stars: 683
- Watchers: 45
- Forks: 105
- Open Issues: 17
-
Metadata Files:
- Readme: README.asciidoc
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
Roaster - The only Java source parser library you'll ever need
===============================================================
image:https://img.shields.io/github/actions/workflow/status/forge/roaster/maven.yml?style=for-the-badge&logo=github["Actions Status", link="https://github.com/forge/roaster/actions"]
image:http://img.shields.io/:license-EPL-blue.svg?style=for-the-badge&logo=apache["License", link="https://www.eclipse.org/legal/epl-v10.html"]
image:https://img.shields.io/github/tag/forge/roaster?logo=apache-maven&label=Maven%20Central&style=for-the-badge["Maven Central", link="https://search.maven.org/artifact/org.jboss.forge.roaster/roaster-jdt"]
image:https://img.shields.io/badge/JVM-17-brightgreen.svg?style=for-the-badge&logo=eclipseadoptium["Supported JVM Versions"]
Roaster (formerly known as java-parser) is a library that allows easy parsing and formatting of java source files.
Roaster introduces a fluent interface to manipulate Java source files, like adding fields, methods, annotations and so on.
Installation
============
* If you are using Maven, add the following dependencies to your project:
```xml
2.30.3.Final
org.jboss.forge.roaster
roaster-api
${version.roaster}
org.jboss.forge.roaster
roaster-jdt
${version.roaster}
runtime
```
* Otherwise, download and extract (or build from sources) the most recent http://search.maven.org/#search|ga|1|a%3A%22roaster-distribution%22[distribution] containing the Roaster distribution and command line tools
Usage
=====
CLI
---
Execute roaster by running the following script (add these to your $PATH for convenience):
[source]
----
bin/roaster (Unix/Linux/OSX)
bin/roaster.bat (Windows)
----
Options described here:
[source,cmd]
----
$ roaster -h
Usage: roaster [OPTION]... FILES ...
The fastest way to build applications, share your software, and enjoy doing it.
-c, --config [CONFIG_FILE]
specify the path to the Eclipse code format profile (usually found at '$PROJECT/.settings/org.eclipse.jdt.core.prefs')
-r, --recursive
format files in found sub-directories recursively
FILES...
specify one or more space-separated files or directories to format
-h, --help
display this help and exit
----
Java Parser API
---------------
Example:
```java
Roaster.parse(JavaClassSource.class, "public class HelloWorld {}");
```
Java Source Code Generation API
-------------------------------
Roaster provides a fluent API to generate java classes. Here an example:
```java
final JavaClassSource javaClass = Roaster.create(JavaClassSource.class);
javaClass.setPackage("com.company.example").setName("Person");
javaClass.addInterface(Serializable.class);
javaClass.addField()
.setName("serialVersionUID")
.setType("long")
.setLiteralInitializer("1L")
.setPrivate()
.setStatic(true)
.setFinal(true);
javaClass.addProperty(Integer.class, "id").setMutable(false);
javaClass.addProperty(String.class, "firstName");
javaClass.addProperty("String", "lastName");
javaClass.addMethod()
.setConstructor(true)
.setPublic()
.setBody("this.id = id;")
.addParameter(Integer.class, "id");
```
Will produce:
```java
package com.company.example;
import java.io.Serializable;
public class Person implements Serializable {
private static final long serialVersionUID = 1L;
private final Integer id;
private String firstName;
private String lastName;
public Integer getId() {
return id;
}
public String getFirstName() {
return firstName;
}
public void setFirstName(String firstName) {
this.firstName = firstName;
}
public String getLastName() {
return lastName;
}
public void setLastName(String lastName) {
this.lastName = lastName;
}
public Person(Integer id) {
this.id = id;
}
}
```
Java Source Code Modification API
---------------------------------
Of course it is possible to mix both approaches (parser and writer) to modify Java code programmatically:
```java
JavaClassSource javaClass =
Roaster.parse(JavaClassSource.class, "public class SomeClass {}");
javaClass.addMethod()
.setPublic()
.setStatic(true)
.setName("main")
.setReturnTypeVoid()
.setBody("System.out.println(\"Hello World\");")
.addParameter("java.lang.String[]", "args");
System.out.println(javaClass);
```
JavaDoc creation and parsing
----------------------------
Here is an example on how to add JavaDoc to a class:
```java
JavaClassSource javaClass =
Roaster.parse(JavaClassSource.class, "public class SomeClass {}");
JavaDocSource javaDoc = javaClass.getJavaDoc();
javaDoc.setFullText("Full class documentation");
// or
javaDoc.setText("Class documentation text");
javaDoc.addTagValue("@author","George Gastaldi");
System.out.println(javaClass);
```
Formatting the Java Source Code
-------------------------------
Roaster formats the Java Source Code by calling the `format()` method:
```java
String javaCode = "public class MyClass{ private String field;}";
String formattedCode = Roaster.format(javaCode);
System.out.println(formattedCode);
```
Parsing the java unit
----------------------
The link:http://docs.oracle.com/javase/specs/jls/se7/html/jls-7.html#jls-7.3[Java Language Specification] allows you to define multiple classes in the same .java file. Roaster supports parsing the entire unit by calling the parseUnit() method:
```java
String javaCode = "public class MyClass{ private String field;} public class AnotherClass {}";
JavaUnit unit = Roaster.parseUnit(javaCode);
JavaClassSource myClass = unit.getGoverningType();
JavaClassSource anotherClass = (JavaClassSource) unit.getTopLevelTypes().get(1);
```
Validate Code Snippets
----------------------
Roaster validates Java snippets and reports as Problem objects by calling the `validateSnippet()` method:
Example:
```java
List problem = Roaster.validateSnippet("public class HelloWorld {}");
// problem.size() == 0
List problem = Roaster.validateSnippet("public class MyClass {");
// problem.size() == 1 containing a new Problem("Syntax error, insert \"}\" to complete ClassBody", 21, 21, 1)
```
Building from sources
=====================
Just run `mvn clean install` to build the sources
Issue tracker
=============
File an issue in our https://github.com/forge/roaster/issues[GitHub Issue Tracker]
Get in touch
============
Roaster uses the same forum and mailing lists as the http://forge.jboss.org/[JBoss Forge] project. See the http://forge.jboss.org/community[JBoss Forge Community] page.
* https://developer.jboss.org/en/forge[User forums]
* https://developer.jboss.org/en/forge/dev[Developer forums]
Related / Similar projects
==========================
For the writer part:
* https://github.com/square/javapoet[square/javapoet]
License
=======
http://www.eclipse.org/legal/epl-v10.html[Eclipse Public License - v 1.0]