README.md 2.93 KB
Newer Older
René Schöne's avatar
René Schöne committed
1
# RelAST Preprocessor
Niklas Fors's avatar
Niklas Fors committed
2

René Schöne's avatar
René Schöne committed
3
![RelAST process](relast-process.png)
Niklas Fors's avatar
Niklas Fors committed
4

René Schöne's avatar
René Schöne committed
5
6
See [releases page](/../../releases) for the latest version.

René Schöne's avatar
René Schöne committed
7
8
The RelAST preprocessor takes a `.relast` file as input comprising AST rules and relations. It produces files that afterwards are processed by JastAdd to generated Java code.
To use it in your project, build the JAR file running
Niklas Fors's avatar
Niklas Fors committed
9

René Schöne's avatar
René Schöne committed
10
11
12
```
./gradlew jar
```
Niklas Fors's avatar
Niklas Fors committed
13

René Schöne's avatar
René Schöne committed
14
This will produce `build/libs/relast.jar`. Copy it to your project and extend your build config (preferably Gradle) with the following:
Niklas Fors's avatar
Niklas Fors committed
15

René Schöne's avatar
René Schöne committed
16
17
18
19
20
21
22
23
24
25
26
```
task preprocess(type: JavaExec) {
    group = 'Build'
    main = "-jar"
    args = [
            "libs/relast.jar",
            "./src/main/jastadd/main.relast",
            "--listClass=RefList",
            "--jastAddList=JastAddList",
            "--file"
    ]
Niklas Fors's avatar
Niklas Fors committed
27

René Schöne's avatar
René Schöne committed
28
29
30
31
32
33
34
35
36
37
    inputs.files file("./src/main/jastadd/main.relast")
    outputs.files file("./src/main/jastadd/mainGen.ast"), file("./src/main/jastadd/mainGen.jadd")
}
```

Note that you may have to change

- the directory of `relast.jar`
- the `.relast` file(s) both as argument(s) and input file(s)
- the output files
38
39
40
41
42
43
44
45
46
47
48
49
50
51
- parameters of RelAST (in this case, the list classes were renamed), the following table shows the supported ones

## Supported command-line options

|         Name        |                                             Description                                              |    Default    |
|---------------------|------------------------------------------------------------------------------------------------------|---------------|
| `--ast`             | Print AST (ignores `--quiet` option)                                                                 | Do not print  |
| `--grammarName`     | Directory and file prefix for the generated grammar and jrag created by RelAST.                      | `Grammar`     |
| `--jastAddList`     | Alternative name for `List` nodes (has to match the option `--List` of JastAdd or its default List). | `List`        |
| `--listClass`       | Set the class name of the nonterminal reference list                                                 | `ArrayList`   |
| `--quiet`           | Do not output anything on stdout.                                                                    | Normal output |
| `--resolverHelper`  | Set to `true` to generate means for lazy resolving.                                                  | `false`       |
| `--serializer`      | Generate a (de-)serializer. One of {`jackson`, `jackson-json-pointer`, `jackson-manual-references`}. | No serializer |
| `--useJastAddNames` | Set to `true` to use accessor names for relations matching JastAdd naming convention.                | `false`       |
René Schöne's avatar
René Schöne committed
52
53

## Supported relations
Niklas Fors's avatar
Niklas Fors committed
54
55
56
57
58

	// Directed relations
	A.b    -> B;
	A.b?   -> B;
	A.bs*  -> B;
René Schöne's avatar
René Schöne committed
59
60
61
	B      <- A.b  ;
	B      <- A.b? ;
	B      <- A.bs*;
Niklas Fors's avatar
Niklas Fors committed
62
63
64
65
66
67
68
69
70
71
72

	// Bidirectional relations
	A.b   <-> B.a;
	A.b   <-> B.a?;
	A.b   <-> B.as*;
	A.b?  <-> B.a;
	A.b?  <-> B.a?;
	A.b?  <-> B.as*;
	A.bs* <-> B.a;
	A.bs* <-> B.a?;
	A.bs* <-> B.as*;