Update README.md

isaacmaffeis · web-flow · commit 6e813c968a5a · 2024-10-03T19:22:41.000+02:00
diff --git a/README.md b/README.md
@@ -23,6 +23,18 @@ systems using Abstract State Machines (ASMs).
 The [Asmeta](https://github.com/asmeta/asmeta/tree/master) framework provides a comprehensive suite
 of tools for creating, simulating, verifying, and analyzing ASM models.
 
+## Project Overview
+
+This repository contains two executable projects:
+
+- [asmetal2java_codegen](#Asmetal2java_codegen) (Main Project)
+- [asmetal2java_asmgen](#Asmetal2java_asmgen) (Extension Project)
+
+# Asmetal2java_codegen
+
+The main project, **asmetal2java_codegen**, is responsible for translating an Abstract State Machine (ASM) into Java code. 
+It generates an executable class named <asmFileName>_Exe that allows users to interact with the ASM step by step. 
+This feature provides a hands-on approach to work with ASMs, enabling users to manually follow the execution of the state machine at each step.
 
 ## How to Start:
 
@@ -46,45 +58,133 @@ of tools for creating, simulating, verifying, and analyzing ASM models.
 
 4. Start the application by running the generated JAR file:
     ```shell
-    java -jar ./asmetal2java_asmgen/target/asmetal2java_asmgen-0.0.1-SNAPSHOT-jar-with-dependencies.jar
+    java -jar ./asmetal2java_codegen/target/asmetal2java_codegen-0.0.1-SNAPSHOT-jar-with-dependencies.jar
      ```
 
 5. Customize execution with additional options:
     ```shell
-    java -jar ./asmetal2java_asmgen/target/asmetal2java_asmgen-0.0.1-SNAPSHOT-jar-with-dependencies.jar -input <input> -output <output> -D<property=value>
+    java -jar ./asmetal2java_codegen/target/asmetal2java_codegen-0.0.1-SNAPSHOT-jar-with-dependencies.jar -input <input> -output <output> -D<property=value>
     ```
     - `-input` : The ASM input file (required)
 
     - `-output` : The output folder (optional, defaults to `./output/`)
 
-    - `-D <property=value>` : Additional properties (optional, see `-help` for more info)
+    - `-D <property=value>` : Additional translator options
+      
+     | Option             | Argument Type     | Description |
+     |--------------------|-------------------|-------------|
+     | `-input`           | String (required) | Path to the ASM input file. |
+     | `-output`          | String (optional) | Specifies the output folder. Defaults to `./output/`. |  
+     | `-Dformatter`      |  boolean (optional)       | whether the generated code should be formatted. |
+     | `-DshuffleRandom` | boolean (optional) |  whether a random shuffle should be applied. |
+     | `-DoptimizeSeqMacroRule` | boolean (optional) | whether to optimize the sequence macro rule. |
+
+
+7. Example of a use case:
+    ```shell
+    java -jar ./asmetal2java_asmgen/target/asmetal2java_codegen-0.0.1-SNAPSHOT-jar-with-dependencies.jar -input "examples/RegistroDiCassa.asm" -output "../asmetal2java_examples/src/" -Dformatter=true
+     ```
+
+### Using Docker
+
+3. Open Docker Desktop and build the Docker image:
+    ```shell
+    docker build -t asmetal2java_codegen .
+    ```
+
+4. Run the application within a Docker container:
+    ```shell
+    docker run --rm asmetal2java_codegen
+    ```
+
+5. Customize execution by passing options:
+    ```shell
+    docker run --rm -v "$(pwd)/<input>:/app/<input>" -v "$(pwd)/asmetal2java_codegen/<output>:/app/asmetal2java_codegen/<output>" asmetal2java_codegen -input <input> -output <output> -D<property=value>
+    ```
+
+    - `-v "$(pwd)/<input>:/app/<input>"` : Maps the input file from the host to the container (required)
 
+    - `-v "$(pwd)/<output>:/app/<output>"` : Maps the output folder from the host to the container (required, use `<output>` as `output` for the default path)
 
 6. Example of a use case:
     ```shell
-    java -jar ./asmetal2java_asmgen/target/asmetal2java_asmgen-0.0.1-SNAPSHOT-jar-with-dependencies.jar -input "examples/RegistroDiCassa.asm" -output "../asmetal2java_examples/src/" -Dformatter=true
+    docker run --rm -v "$(pwd)/asmetal2java_codegen/examples:/app/asmetal2java_codegen/examples" -v "$(pwd)/asmetal2java_codegen/output:/app/output" asmetal2java_codegen -input "examples/RegistroDiCassa.asm" -output "output"
+    ```
+# Asmetal2java_asmgen
+
+The extension project, **asmetal2java_asmgen**, extends asmetal2java_codegen by generating a class named <asmFileName>_ASM. 
+Unlike the executable class generated by asmetal2java_codegen, which requires user interaction to step through the Abstract State Machine (ASM) execution, 
+the _ASM class produced by asmetal2java_asmgen is designed for automated processes without the need for manual interactions.
+
+## How to Start:
+
+### Cloning the Repository
+1. Open PowerShell or your preferred terminal and clone the repository:
+    ```shell
+    git clone https://github.com/isaacmaffeis/asmetal2java.git
+    ```
+
+2. Navigate into the project directory:
+    ```shell
+    cd ./asmetal2java
+    ```
+
+### Using Maven
+
+3. Install the project and generate the executable JAR:
+    ```shell
+    mvn clean install
+    ```
+
+4. Start the application by running the generated JAR file:
+    ```shell
+    java -jar ./asmetal2java_asmgen/target/asmetal2java_asmgen-0.0.1-SNAPSHOT-jar-with-dependencies.jar
+     ```
+
+5. Customize execution with additional options:
+    ```shell
+    java -jar ./asmetal2java_asmgen/target/asmetal2java_asmgen-0.0.1-SNAPSHOT-jar-with-dependencies.jar -input <input> -output <output> -D<property=value>
+    ```
+    - `-input` : The ASM input file (required)
+
+    - `-output` : The output folder (optional, defaults to `./output/`)
+
+    - `-D <property=value>` : Additional translator options
+      
+     | Option             | Argument Type     | Description |
+     |--------------------|-------------------|-------------|
+     | `-input`           | String (required) | Path to the ASM input file. |
+     | `-output`          | String (optional) | Specifies the output folder. Defaults to `./output/`. |  
+     | `-Dformatter`      |  boolean (optional)       | whether the generated code should be formatted. |
+     | `-DshuffleRandom` | boolean (optional) |  whether a random shuffle should be applied. |
+     | `-DoptimizeSeqMacroRule` | boolean (optional) | whether to optimize the sequence macro rule. |
+     | `-finalState` | String (optional) | Final state condition of the ASM |
+
+7. Example of a use case:
+    ```shell
+    java -jar ./asmetal2java_asmgen/target/asmetal2java_asmgen-0.0.1-SNAPSHOT-jar-with-dependencies.jar -input "examples/RegistroDiCassav4.asm" -output "../asmetal2java_examples/src/" -Dformatter=true -finalState state>=5:statoCassa==Stati.CHIUSO
      ```
 
 ### Using Docker
 
 3. Open Docker Desktop and build the Docker image:
     ```shell
-    docker build -t asmetal2java .
+    docker build -t asmetal2java_asmgen .
     ```
 
 4. Run the application within a Docker container:
     ```shell
-    docker run --rm asmetal2java
+    docker run --rm asmetal2java_asmgen
     ```
 
 5. Customize execution by passing options:
     ```shell
-    docker run --rm -v "$(pwd)/<input>:/app/<input>" -v "$(pwd)/asmetal2java_codegen/<output>:/app/asmetal2java_codegen/<output>" asmetal2java -input <input> -output <output> -D<property=value>
+    docker run --rm -v "$(pwd)/<input>:/app/<input>" -v "$(pwd)/asmetal2java_asmgen/<output>:/app/asmetal2java_asmgen/<output>" asmetal2java_asmgen -input <input> -output <output> -D<property=value>
     ```
 
     - `-v "$(pwd)/<input>:/app/<input>"` : Maps the input file from the host to the container (required)
 
-    - `-v "$(pwd)/<output>:/app/asmetal2java_codegen/<output>"` : Maps the output folder from the host to the container (required, use `<output>` as `output` for the default path)
+    - `-v "$(pwd)/<output>:/app/<output>"` : Maps the output folder from the host to the container (required, use `<output>` as `output` for the default path)
 
     - `-input` : The ASM input file (required)
 
@@ -94,5 +194,5 @@ of tools for creating, simulating, verifying, and analyzing ASM models.
 
 6. Example of a use case:
     ```shell
-    docker run --rm -v "$(pwd)/asmetal2java_codegen/examples:/app/asmetal2java_codegen/examples" -v "$(pwd)/asmetal2java_codegen/output:/app/asmetal2java_codegen/output" asmetal2java -input "examples/RegistroDiCassa.asm" -output "output"
+    docker run --rm -v "$(pwd)/asmetal2java_asmgen/examples:/app/asmetal2java_asmgen/examples" -v "$(pwd)/asmetal2java_asmgen/output:/app/output" asmetal2java_asmgen -input "examples/RegistroDiCassav4.asm" -output "output"
     ```
