Commit 6409daeb authored by Adrian Wuillemet's avatar Adrian Wuillemet
Browse files

Add developer readme

parent 51804837
Pipeline #4594 passed with stages
in 1 minute and 23 seconds
......@@ -7,4 +7,6 @@ Projekt zur Erzeugung von Code aus Fine State Machines.
<br>
[Zur Projekt README](source/README.md)
\ No newline at end of file
[Zur Projekt README](source/README.md)
[Zur Developer README](documentation/README.md)
# Documentation
We are building an open source lightweight tool for commandline usage with the following techs:
## CLI
![Python](https://img.stackshare.io/service/993/pUBY5pVj.png)
![Click](media/click.png)
![Eel](media/eel.png)
## GUI
![HTML5](https://img.stackshare.io/service/2538/kEpgHiC9.png)
![Sass](https://img.stackshare.io/service/1171/jCR2zNJV.png)
![Typescript](https://img.stackshare.io/service/1612/bynNY5dJ.jpg)
![D3.js](https://img.stackshare.io/service/1491/d3-logo.png)
## Tools
![GitLab](https://img.stackshare.io/service/880/lmalkclL.png)
![Visual Studio Code](https://img.stackshare.io/service/4202/jEKFRPKV_400x400.jpg)
![Postman](https://img.stackshare.io/service/1336/logo-mark-404.png)
![Git](https://img.stackshare.io/service/1046/git.png)
## Web *(possibly in the future)*
![Heroku](https://img.stackshare.io/service/133/3wgIDj3j.png)
![NGINX](https://img.stackshare.io/service/1052/YMxUfyWf.png)
![Docker](https://img.stackshare.io/service/586/docker.png)
___
*Icons retrieved from [StackShare.io](https://stackshare.io)*
# Beads - A tool to generate code from state machines
_**2019** <sup>©</sup> Jakob Baatz, Rico Possienka, Pavel Nepke, Marco Wenning, Adrian Wuillemet_<br>
<br>
<br>
## Introduction
As a software developer you can encouter state machines as part of a logic that
can parse content, as a description of AI behaviour or while modelling some
buisness processes.<br>
In whatever form, state machines are cumbersome to code, as the written code is
very repetitive and it is quite easy to loose oversight as the machine gets bigger.<br>
<br>
For this purpose **Beads** can aid you in consistently generating that
code from textfiles or drawings that you provide. Simply write a **.json**
representation of your machine or use our simplified **.bead** format to write
down the logic.<br>
<br>
**Beads** is an open source python and webtech tool that can be used
from the command line and is easy to incorporate into scripts for project builds.
Additionally the Graphical User Interface (GUI) provides means to draw visual
representations of your machines and can persist them as **.svg**, **.png**
and **.json** files.<br>
**Beads<sup>©</sup>** comes with a validaten logic for simple state machines,
that can be turned off if needed.<br>
<br>
<br>
This is a tutorial to download and setup the git project and running the tool for the first time.<br>
All referenced code snippets should be executed from a shell based terminal!
Link to the repository: https://gitlab.beuth-hochschule.de/s40242/stategen
Link to the board: https://gitlab.beuth-hochschule.de/s40242/stategen/-/boards
## Table of Contents
1. [Dependencies](#deps)
2. [Download](#download)
3. [Installation](#install)
4. [Writing your own files](#formats)
5. [Command line interface](#commands)
6. [Graphical user interface](#gui)
<br>
<br>
### 1. Dependencies
<a name="deps"></a>
**Beads<sup>©</sup>** is a commandline tool built with Python for the backend and
web technologies for the Frontend. To setup and start developing the project manually the following dependencies have to be installed on your system:<br>
<br>
* [Git](https://git-scm.com/downloads)
* [Python 3.x.x](https://www.python.org/downloads/)
* [pip](https://pip.pypa.io/en/stable/installing/)
* [npm](https://nodejs.org/en/download)
* [Typescript](https://www.typescriptlang.org/index.html#download-links)
* [Sass](https://sass-lang.com/install)
* Chrome/Chromium
<br>
Verify them using:
```shell
$ git --version
$ python --version
$ pip --version
$ npm --version
$ tsc --version
$ sass --version
```
<br>
<br>
### 2. Download the project
<a name="download"></a>
To download the project simply clone it with git:
```shell
$ git clone git@gitlab.beuth-hochschule.de/s40242/stategen.git
```
The repository will be cloned into ./stategen/<br>
This may take a minute.
After that change into "stategen/source/" folder with:
```shell
cd stategen/source/
```
and you are ready to build/install the project.
<br>
<br>
### 3. Installation
<a name="install"></a>
**Beads** comes packaged with a _Makefile_ that handles the simple build process.
To build the project for the first time run:
```shell
$ make install
```
Alternatively you can install and build the project by hand or setup a shell script that does the job.
Here are the required steps:
```shell
$ pip install click eel markdown
$ npm install @types/d3 --prefix ts/
$ tsc -b ts/
$ sass sass/gui.scss beads/resources/ui/css/gui.css
$ cp README.md beads/resources/info/README.md
```
Now you are good to go.
Verify everything ran smoothly by setting up an alias and running the following commands:
```shell
$ alias beads="python beads/main.py"
$ beads --version
$ beads --help
$ beads languages
$ beads gui
```
If they all run the project got properly installed and is ready for further development.
<br>
<br>
### 4. Writing your own files
<a name="formats"></a>
To run some tests you can either supply **Beads** with a .json file, a .bead file or both.<br>
A version of both files are packaged in the **"stategen/source/files/"** folder and are ready to use.<br>
<br>
Writing them requires knowledge of their good form:
<br>
**Writing a JSON representation of a state machine:**
The .json must have three keys: "name", "nodes" and "transitions". Their content is shown below.<br>
The "start":true attribute of nodes is optional but can only be present once.
```json
{
"name":"NAME",
"nodes": [
{"id":"State_1"},
{"id":"State_2", "start":true},
{"id":"State_3"}
],
"transitions":[
{"label":"transition_a", "from":"State_1", "to":"State_2"},
{"label":"transition_b", "from":"State_2", "to":"State_3"},
{"label":"transition_b", "from":"State_3", "to":"State_1"},
{"label":"transition_c", "from":"State_2", "to":"State_1"},
]
}
```
<br>
**Writing a BEAD representation of a state machine:**
Writing a .bead representation is easier. The .bead format is transition based and does not require a separat declaration of all states.<br>
Name and starting state of the machine can be provided via config comment at the start of the .bead file as shown in the example below:
```
#! name:NAME start:State_2
State_1:transition_a:State_2
State_2:transition_b:State_3
State_3:transition_b:State_1
State_2:transition_c:State_1
```
**INFO**: A .bead file is not a valid argument for '$ beads gui --file'!
<br>
<br>
### 5. Command line interface
<a name="commands"></a>
**Overview of commands and options**<br>
Printing information on the terminal:
```shell
$ beads [command] [option] --help
```
Printing the current version:
```shell
$ beads --version
```
Print an overview of all supported programming languages:
```shell
$ beads languages FILTERSTRING
# Examples
$ beads languages --help
$ beads languages
$ beads languages py
```
The main purpose of the tool is to parse a textual representation of a state machine
into working code.<br>
To to so you use the command 'parse':
```shell
$ beads parse FILES [options]
# Options
$ beads parse FILES
-l / --language # Specify the programming language of the generated code. Default: none
-o / --out # Specify the output file. Default: ./FILENAME.language
-re / --replace-existing # FLAG to replace existing files with the generated code
-nv / --no-validation # FLAG to skip the internal validation of the state machine logic
-bd / --base-directory # Set a base directory, that all files will be saved in. Default: .
-v / --verbose # FLAG to execute the programm in verbose mode printing all debug information
# Examples
$ beads parse --help
$ beads parse files/testfile.json
$ beads parse files/testfile.json files/testfile.bead
$ beads parse files/testfile.json --language python --no-validation
$ beads parse files/testfile.json --out ./out --replace-existing
$ beads parse files/testfile.json files/testfile.bead --base-directory ./out
$ beads parse files/testfile.bead -l java -v -re -bd ./out
```
All commands related to the Graphical User Interface are bound to 'gui':
```shell
$ beads gui [options]
# Options
$ beads gui
-b / --background # Run the gui in the background without opening a window
-p / --port # Run the gui on the specified port. Default: 8000
-v / --verbose # Run the gui in verbose mode. Default: false
--file FILE # Run the gui and load the provided FILE. Needs to be a valid json representation of a state machine.
# Examples
$ beads gui --help
$ beads gui -v -p 11000
$ beads gui --file files/testfile.json
```
You can set some commandline options as default values that will be considered without having to provide them on the commandline. Providing options via commandline however will overwrite defaults.
```shell
$ beads options [options]
# Options
$ beads options
-s / --set-default OPTION VALUE # Set the default VALUE for OPTION
-u / --unset-default OPTION # Unset the default value for OPTION
--unset-all # Unset all currently saved defaults.
--show # Print a list of available Options and their data type
# Examples
$ beads options --help
$ beads options --show
$ beads options --set-default language python
$ beads options --unset-default language
$ beads options -s port 11000 -s language java -u verbose
$ beads options --unset-all
```
<br>
<br>
### 6. Graphical user interface
<a name="gui"></a>
The gui features a tutorial for the drawing of state machines and provides a documentation README.md for offline reference.
For the code generation to work properly it is important to select a programming language in the _menu > languages_ section!
If you want to skip validation while generating code or start the gui on another port just change the corresponding options under _menu > settings_.
To preview the generated code instead of saving it directly just open the preview panel. The corresponding button can be found on the bottom right of the screen next to the generation button.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment