# J2EO: Java to EO Translator
-o
```
For example the following command will translate `SimpleTest.java` file
into `output_eo` directory:
```shell
java -jar j2eo.jar src/test/resources/SimpleTest.java -o output_eo
```
You also can translate an entire folder. For example, the following command
wil translate `test1` directory into `output_eo` directory:
```shell
java -jar j2eo.jar src/test/resources/polystat_tests/test1 -o output_eo
```
You can also use [yegor256/j2eo](https://hub.docker.com/r/yegor256/j2eo) image
for [Docker](https://docs.docker.com/get-docker/):
```
$ docker run -v $(pwd):/eo yegor256/j2eo hello.java --target output
```
This command will translate `hello.java` in the current directory, saving the
output to `output/` subdirectory.
### Unit tests
Built-in unit tests may be executed using:
```shell
gradle test
```
### Bundled test suite
J2EO comes with 1000+ bundled tests. There are two testing scenarios:
#### Static check execution:
- Java source code is translated to EO using J2EO project
- Obtained EO code are compared with saved one. If they match — test is passed.
If not — test is failed.
All saved EO programs are located
in [translated_test](src/test/resources/translated_tests) directory.
This scenario can be executed by the following command:
`./gradlew test --tests "common.TestJ2EOStaticCheck"`
#### Parallel execution:
- original Java source code of the text is compiled with Java compiler and
executed. Stdout output is saved.
- Java source code is translated to EO using J2EO project, then compiled with EO
compiler and executed. Stdout output is stored.
- Stdout outputs are compared. If they match — test is passed. If not — test is
failed.
This scenario may be executed using `./test_candidates.sh` script.
Test suite follows the **Java Language Specification** structure, covering
applicable chapters and sections of the Java specifications.
### Running translator on Hadoop
Hadoop is a large Java project (contains ~1.8M lines of code as of time of
writing this). We included it as a benchmark of the translator.
Repository contains a script to build J2EO, download Hadoop repo and run J2EO on
it.
Usage:
```shell
./test-hadoop.sh
```
It will download zipped `hadoop` and unpack it (in a separate folder)
into `../j2eo-data` relative to the project's root. Next, it will put the If you
no more need that folder, run
```sh
rm -rf ../j2eo-data
```
---
## Motivation
This project is a part of Polystat project, the goal of which is to statically
analyze different languages using EOLANG,
the implementation of phi-calculus. In order to do that, the first step is to
convert source language into EO. This
particular repository contains translator from Java to EO.
---
## Decisions
**Q**: Why do we implement yet another Java parser?
**A**: Publicly available parsers only support older versions of Java, while we
aim to support the latest version (
currently 16). Thus, we had to create our own parser.
Also in recent versions, external Java grammar implemented in ANTLR was added as
an alternative. It claims to support Java 17, and it does, as for our testing on
big projects.
class__ > super # Inheritance simulation
super > @
[] > new # new is representation
# of object itself
class__.new > super
super > @ # Inheritance simulation
"class__" > className # Name of class is being saved
1 > address # Identify that it
# isn't a null object
[this] > init # Initializes class members
... # default values
... # Class methods and variables
... # Static methods and variables
[this] > constructor # Constructor
...
```
### 10 Arrays
___
#### 10.2 Array Variables
Translator supports both types of arrays: primitive and reference.
Examples: `int[]` and `String[]`
#### 10.3 Array Creation
Look at [15.10.1](#15.10.1-array-creation-expressions) section.
#### 10.4 Array Access
For access to array elements translator uses `get` provided by EO `array`
object. However, as indexes it uses primitive wrappers.
Example is provided in [15.10.3](#15.10.3-array-access-expressions) section.
#### 10.6 Array Initializers
An array initializer is written as a comma-separated list of expressions,
enclosed
by braces { and }. Example, `{ 1 + 1, 2 }`
Currently, it is the only way to store something in array. Other types of
initializers (e.g. `new Type[num]`) are unsupported.
Example:
```java
{1+1,2}
```
-->
```eo
[] > initializerArray_1
* > @
initializerSimple_1
initializerSimple_2
[] > initializerSimple_1
binary_1 > @
[] > binary_1
literal_1.add > @
literal_2
[] > literal_1
prim__int.constructor_2 > @
prim__int.new
1
[] > literal_2
prim__int.constructor_2 > @
prim__int.new
1
[] > initializerSimple_2
literal_3 > @
[] > literal_3
prim__int.constructor_2 > @
prim__int.new
2
```
#### 10.7 Array Members
For now only `length` attribute is supported. During translation, it remains
unchanged.
### 14 Blocks, Statements, and Patterns
---
#### 14.2 Blocks
By Java grammar, blocks are sequence of declarations and statements separated by
curly braces. Translator creates new EO object for each block. Example:
```java
{
declaration;
statement;
}
```
-->
```eo
[] > block_1
seq > @
declaration_1
statement_1
```
Number after object name is needed just for avoiding name
collisions. `declaration_1` and `statement_1` are EO objects. They describe
internal structure of itself. Inside a `seq` object they are just dataizing.
Now let's look to real Java code:
```java
void foo(){
int a=1;
println(a);
}
```
->
```eo
1 [this] > foo
2 seq > @
3 variableDeclaration_1
4 statementExpression_1
5 prim__int.constructor_1 > a
6 prim__int.new
7 [] > variableDeclaration_1
8 a.write > @
9 initializerSimple_1
10 [] > initializerSimple_1
11 literal_1 > @
12 [] > literal_1
13 prim__int.constructor_2 > @
14 prim__int.new
15 1
16 [] > statementExpression_1
17 this.println > @
18 this
19 simpleReference_1
20 [] > simpleReference_1
21 a > @
```
Any variables in blocks are declared separately from the `seq` object. In this
case `int a` was declared at lines 5-6. Also it has an initializer `1`. So
translator assign `a` to initializer value at lines 7-9. This initializer is
simple one. It is a just literal. Translator mentioned it on lines 10-11.
Literals are translated to EO objects itself (lines 12-15).
Any statement in blocks are statement expression by default. Their behaviour as
a declarations are described separately. In this case statement `println(a)` is
declared on lines 16-19. By default, any method is considered as class method.
So access to it is performed via `this` (line 17). Moreover, it is necessary to
pass `this` as argument during method invocation (line 18). `println(a)` is call
with single argument `a`. It is a simple reference that was mentioned at line
19. Simple reference is itself a distinct object which translator declared on
lines 20-21.
#### 14.4 Local Variable Declarations
A local variable declaration declares and optionally initializes one or more
local
variables. Translator keeps location of declaration unchanged.
E.g. class member declarations stay inside class body, local method variables
stays inside a method body and e.t.c. Depending on the type declared entity can
be stored in `cage`, primitive wrapper or in separate EO object.
Example of class member declaration:
```java
class A {
int member;
}
```
-->
```eo
[] > class__A
...
[] > new
...
prim__int.constructor_1 > member
prim__int.new
...
```
Example of class member with initializer:
```java
class A {
int member = 0;
}
```
-->
```eo
[] > class__A
...
[] > new
...
[this] > init
seq > @
variableDeclaration_1
[] > variableDeclaration_1
this.member.write > @
initializerSimple_1
[] > initializerSimple_1
literal_1 > @
[] > literal_1
prim__int.constructor_2 > @
prim__int.new
0
prim__int.constructor_1 > member
prim__int.new
...
```
In this case when instance of class `A` would be created, `init` object would be
called for initializing variables.
Example of local method variable with initializer:
```java
void m(){
int a=0;
}
```
-->
```eo
[this] > m
seq > @
variableDeclaration_1
prim__int.constructor_1 > a
prim__int.new
[] > variableDeclaration_1
a.write > @
initializerSimple_1
[] > initializerSimple_1
literal_1 > @
[] > literal_1
prim__int.constructor_2 > @
prim__int.new
0
```
Here the same logic is applicable as in previous example. Variable itself is
being stored out of `seq` object, but it dataizes its initialization.
Example with nested class is located
in [8.5](#8.5 Member Class and Interface Declarations).
#### 14.5 Statements
All statements of block are being stored inside `seq` object after translation.
Each of them is represented by unique name which during dataization simulates
behaviour of initial statement.
Example:
```java
{
int a=1;
method();
}
```
-->
```eo
[] > block_1
seq > @
variableDeclaration_1 # int a = 1;
statementExpression_1 # method();
prim__int.constructor_1 > a # int a
prim__int.new
[] > variableDeclaration_1 # assignment
a.write > @
initializerSimple_1
[] > initializerSimple_1
literal_1 > @
[] > literal_1 # literal: 1
prim__int.constructor_2 > @
prim__int.new
1
[] > statementExpression_1 # method()
this.method > @ # call
this
```
#### 14.6 The Empty Statement
Translator ignores it.
#### 14.9 The if Statement
Example:
```java
if(cond)
then_block;
else
else_block;
```
-->
```eo
[] > ifThenElse_1
translated_cond.if > @
block_1
block_2
... # translation of cond
[] > block_1
... # then_block translation
[] > block_2
... # else_block translation
```
If no else part is provided then translator generate empty block (`empty`):
```eo
[] > empty_1
TRUE > @
```
#### 14.10 The assert Statement
Example:
```java
assert cond:expr;
```
-->
```eo
[] > assert_1
translated_cond.if > @
TRUE
[]
translated_expr > msg
... # translation of cond
... # translation of expr
```
#### 14.12 The while Statement
Example:
```java
while(cond)
block;
```
-->
```eo
[] > while_1
translated_cond.while > @
[while_i]
block_1 > @
... # translation of cond
[] > block_1
... # block translation
```
#### 14.13 The do Statement
Example:
```java
do
block;
while(cond);
```
-->
```eo
[] > do_1
translated_cond.do > @
[do_i]
block_1 > @
... # translation of cond
[] > block_1
... # block translation
```
Note: currently there is no runtime support of `do` object.
### 15 Expressions
---
#### 15.8.1 Lexical Literals
Now supported only integer, floating point and string literals. Translator use
wrappers to simulate behaviour of Java primitives.
Let's consider an assign operator in Java write value into variable and return
its value. `memory` in EO does not provide a such behaviour.
Therefore, we need to use a wrapper.
Examples:
`1` ->
```eo
[] > literal_1
prim__int.constructor_2 > @
prim__int.new
1
```
`1.0` ->
```eo
[] > literal_1
prim__float.constructor_2 > @
prim__float.new
1.0
```
`"string"` ->
```eo
[] > literal_1
class__String.constructor_2 > @
class__String.new
"string"
```
#### 15.8.3 this
It's remaining unchanged.
#### 15.8.5 Parenthesized Expressions
`(expresion)` ->
```eo
[] > parenthesized_1
expresion > @
```
It can be simplified, but we keep such translation to maintain more complex
cases.
#### 15.9 Class Instance Creation Expression
`new A(arg)` ->
```eo
[] > statementExpression_1
class__A.constructor > @
class__A.new
simpleReference_1
[] > simpleReference_1
arg > @
```
For referencing variables `simpleReference_1` is used. It can be simplified, but
it's used for maintaining complex cases.
#### 15.10.1 Array Creation Expressions
Currently, only creation with array initializers is supported. Example of array
initializers: `{1, 2, 3}`.
For storing array translator uses `cage` object. For simulation of array
initializers translator uses `array` aka `*` object from EO.
`int[] array = {1}` ->
```eo
[] > variableDeclaration_1
array.write > @
initializerArray_1
[] > initializerArray_1
* > @
initializerSimple_1
[] > initializerSimple_1
literal_1 > @
[] > literal_1
prim__int.constructor_2 > @
prim__int.new
1
```
#### 15.10.3 Array Access Expressions
`array[idx]` ->
```eo
[] > statementExpression_1
simpleReference_1.get > @
simpleReference_2.v
[] > simpleReference_1
array > @
[] > simpleReference_2
idx > @
```
`simpleReference_2.v` is getting int value from wrapper.
#### 15.11 Field Access Expressions
`a.b` ->
```eo
[] > statementExpression_1
simpleReference_1.b > @
[] > simpleReference_1
a > @
```
It can be simplified, but we keep such translation for generalization.
#### 15.11.2 Accessing Superclass Members using `super`
`a.super.b` ->
```eo
[] > statementExpression_1
simpleReference_1.super.b > @
[] > simpleReference_1
a > @
```
#### 15.12 Method Invocation Expressions
`a.b(arg)` ->
```eo
[] > statementExpression_1
a.b > @ # call of b
a # a should be passed
simpleReference_2 # args
[] > simpleReference_2
arg > @
```
#### 15.14.2 Postfix Increment Operator `++`
`expr++` ->
```eo
[] > statementExpression_1
simpleReference_1.inc_post > @ # increment itself
[] > simpleReference_1
expr > @
```
#### 15.14.3 Postfix Decrement Operator `--`
`expr--` ->
```eo
[] > statementExpression_1
simpleReference_1.dec_post > @ # decrement itself
[] > simpleReference_1
expr > @
```
#### 15.15.1 Prefix Increment Operator `++`
`++expr` ->
```
[] > statementExpression_1
simpleReference_1.inc_pre > @ # increment itself
[] > simpleReference_1
expr > @
```
#### 15.15.2 Prefix Decrement Operator `--`
`--expr` ->
```
[] > statementExpression_1
simpleReference_1.dec_pre > @ # decrement itself
[] > simpleReference_1
expr > @
```
#### 15.15.3 Unary Plus Operator `+`
`+expr` ->
```
[] > statementExpression_1
simpleReference_1 > @
[] > simpleReference_1
expr > @
```
It can be simplified, but we keep such translation for generalization.
#### 15.15.4 Unary Minus Operator `-`
`-expr` ->
```eo
[] > statementExpression_1
simpleReference_1.neg > @ # negation itself
[] > simpleReference_1
expr > @
```
#### 15.16 Cast Expressions
`(int) 1.0` ->
```eo
[] > statementExpression_1
prim__int.from > @ # cast itself
literal_1
[] > literal_1
prim__float.constructor_2 > @
prim__float.new
1.0
```
#### 15.17-26 Binary Operators
`left operand right` ->
```eo
[] > statementExpression_1
simpleReference_1.t_operand > @
simpleReference_2
[] > simpleReference_1
left > @
[] > simpleReference_2
right > @
```
`t_opernad` is translated `operand`
There are only runtime support only for following operands:
`+`, `-`, `*`, `%`, `/`, `&&`, `||`, `>`, `<`, `>=`, `<=`, `==`, `!=`, `<<`, `>>`
and `>>>`
[](https://github.com/polystat/j2eo/actions/workflows/gradle-build.yml)
[](https://codecov.io/gh/polystat/j2eo)
[](https://hitsofcode.com/view/github/polystat/j2eo)
This is a translator of **Java** programming language
to [EOLANG](https://www.eolang.org) programming language.
## Usage
### Prerequisites
- **Java 11+** (make sure command `java -version` shows 11+ version of Java
in terminal if you have multiple Java
version installed).
- **Gradle 7.4+** to build the project.
- **Maven 3.8+** to run tests (be aware
of [possible conflicts](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=980467)
of the
latest versions of Maven and Java on some OSs).
- **ANTLR4 4.9.2** to build parser.
You can refer to [ACCEPTANCE.md](ACCEPTANCE.md) file for instructions on
installing these components.
### Build sources
In order to build `j2eo` transpiler from sources, you need to:
1. Clone the repo. You have two options clone it by using `HTTPS` or `SSH`, just
choose one of them which is suitable for you:
1) HTTPS:
```shell
git clone https://github.com/polystat/j2eo.git
```
2) SSH:
```shell
git clone git@github.com:polystat/j2eo.git
```
2. Open the project root folder:
```shell
cd j2eo
```
3. Build the project:
```shell
./build.sh
```
See the [troubleshooting section](./README.md#troubleshooting) in case of
problems
### Run transpiler
After build process, **j2eo.jar** file will appear in the project root
folder (`./j2eo`). With this file, is it possible to translate **.java** files
or packages into **.eo** packages. In order to translate `java` sources
into `eo` sources just run the next command:
```shell
java -jar j2eo.jar