diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | python-beads.spec | 1050 | ||||
| -rw-r--r-- | sources | 1 |
3 files changed, 1052 insertions, 0 deletions
@@ -0,0 +1 @@ +/Beads-0.1.4.tar.gz diff --git a/python-beads.spec b/python-beads.spec new file mode 100644 index 0000000..f389de3 --- /dev/null +++ b/python-beads.spec @@ -0,0 +1,1050 @@ +%global _empty_manifest_terminate_build 0 +Name: python-Beads +Version: 0.1.4 +Release: 1 +Summary: A commandline tool to parse fine state machines into code. +License: MIT License +URL: https://gitlab.com/a.wuillemet/beads +Source0: https://mirrors.aliyun.com/pypi/web/packages/c4/e8/93719a963b0d3f6d6f0ccf16754473510d55ab4d6f56a12d8471a8be96b7/Beads-0.1.4.tar.gz +BuildArch: noarch + +Requires: python3-click +Requires: python3-eel +Requires: python3-markdown + +%description + + +# 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<sup>©</sup>** 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<sup>©</sup>** 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 will 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> +All further informations and details on writing state machines and using **Beads<sup>©</sup>** +can be found below!<br> +<br> +[Project Screenshots](https://docs.google.com/presentation/d/1R3tYoSjhtAN2ghXU36P8B2fT_jkr9z0OJo2ymSYXALM/edit?usp=sharing) +<br> + +## Table of Contents + 1. [Dependencies](#deps) + 2. [Download and Installation](#download) + 3. [Command line usage](#cmd) + 4. [Using the Graphical User Interface](#gui) + 5. [Supported file formats](#formats) + 6. [Used technologies](#techs) + +<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 GUI. To run beads you need to have<br> + +<br> + + * **Python 3.x.x** + * **a web browser of your choice** + +<br> + +installed on your system. And thats it. If you do not have python installed you +can get it from [here](https://www.python.org/downloads/).<br> +The tool is usable without any web browser, however only from the commandline. +<br> + +As listed in the section Used technologies, **Beads<sup>©</sup>** is +built with the python library [Eel](https://pypi.org/project/Eel/) which utilizes Chrome / Chromium +in app-mode to display our GUI. We do not want to force a user that wants to work with the +GUI to install chrome/chromium, neither do we want to package a distribution of them for users +that do not care about the GUI.<br> +<br> +Chrome or Chromium is only a soft dependency, with which **Beads<sup>©</sup>** - GUI +works best. Alternatively any other modern web browser will suffice and the system standard +browser will be used, if no Chrome is detected. +<br> +<br> + +### 2. Download and Installation +<a name="download"></a> + +Dowloading and installing **Beads<sup>©</sup>** is extremely easy:<br> +We deploy the tool and all updates via the [Python Package Index](https://pypi.org). So to get your +hands on the tool simply install it with _pip_ and you are good to go. + +```shell +$ pip install Beads +``` + +Any internal dependencies will be handled by pip!<br> + +The second method is to clone the project with [Git](https://git-scm.com) and set it up +by yourself. We do not support this method and therefore provide no guide on how to. +Any usage described in the sections below may differ if you install the tool this way. +<br> +<br> + +### 3. Commandline usage +<a name="cmd"></a> + +**Beads<sup>©</sup>** follows standard conventions on commandline usage. A list of +available commands and options, as well as documentation for them can be found below.<br> +Alternatively running + +```shell +$ beads --help +#or +$ beads [command] --help +``` + +from the commandline will print the help section of the tool that contains all needed +information as well. We advise users to default to the cmd **--help** option for all commands +and options rather than consulting this section, as that is always up to date. + +**List of commands and options**<br> +_(including examples of usage)_<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 + +# it is possible to filter the languages by appending a search string like 'ava' +# which will only display supported languages that contain the string like 'java' or 'javascript' +$ beads languages ava +``` + +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 /E/documents/controller.bead +# assuming you have a state machine in a .bead file here: /E/documents/controller.bead +# the command will parse the file and save the generated code in the current working directoy. + +$ beads parse /E/documents/controller.beads ../machines/statemachine.json +# it is possible to provide multiple files at once + +$ beads parse machine.json --language python --no-validation +# will skip the validation of state machine logic and try to produce code in python + +$ beads parse machine.json --out ../package/machine.py --replace-existing +# will save generated code in ../package/machine.py and replace an already existing file if there is one + +$ beads parse machine1.bead machine2.bead machine3.bead --base-directory ./machines/code +# will parse all three provided machines and save them in the specified directory ./machines/code + +$ beads parse machine1.bead controller2.json -l java -v -re -bd ../code/generated/ +# Complex example executing verbose, replacing any existing file +# and placing the generated code from both files which will be java code into ../code/generated +``` + +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 -v -p 11000 +# Run the gui in verbose and on localhost:11000 + +$ beads gui --file ./stateMachine.json +# Open the gui and load the provided stateMachine.json to display upon loading +``` + +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 --show +# First prints all available options and then the overview of all currently set defaults + +$ beads options --set-default language python +# Sets the default language used to generate code to python + +$ beads options --unset-default language +# Unsets the default value of language + +$ beads options -s port 11000 -s language java -u verbose +# Multiple -s / -u can be provided with one call: +# First unsets --verbose, then sets --port to 11000 and --language to java + +$ beads options --unset-all +# Clears all saved default options +``` + +<br> +<br> + +### 4. Using the Graphical User Interface +<a name="gui"></a> + +The Graphical User Interface allows the drawing of simple fine state machines. You can draw states and transitions and save the whole graph in different file formats. A tutorial is available within the GUI! +<br> + +All further functionality should be self-explanatory and is properly visualized in the gui. + +<br> +<br> + +### 5. Supported file formats +<a name="formats"></a> + +State machines can be provided in textual representations. Currently there are two file formats that are supported by **Beads<sup>©</sup>**: + + + JSON: file.json + + BEAD: file.bead + +<br> + +**Json format** + +To provide a state machine as a JSON file follow the schema below: + +Three attributes are required: + + + A **name** for the machine + + A list of **nodes** with an "ID" representing the states + + A list of **transitions** with "from" and "to" referencing nodes, and a "label" + +To declare a state as the initial starting state append '"start":true' to the node. + +```json +{ + "name": "NAME", + "nodes": [ + {"id":"ID1", "start":true}, + {"id":"ID2"} + ], + "transitions": [ + {"from":"ID1", "label":"TRANS1", "to":"ID2"}, + {"from":"ID2", "label":"TRANS2", "to":"ID1"} + ] +} +``` +<br> + +**Bead format** + +As an easy-to-write alternative to json files the tool accepts **.bead** files that adhere to the following format: + +``` +#! name:NAME start:ID1 + +ID1:TRANS1:ID2 +ID2:TRANS2:ID1 +``` + +The **.bead** format is transition based. All transitions follow the schema:<br> +FROM_STATE : TRANSITION_NAME : TO_STATE<br> + +The name and the starting point are optional and can be declared as key:value pairs in a config comment on the top of the file. +The comment has to start with '#!' which is followed by a whitespace. + +Parsing of **.bead** files will extract all referenced states so they do not have to be declared separately. + +<br> +<br> + +### 6. Used technologies +<a name='techs'></a> + +We are building an open source lightweight tool for commandline usage with the following techs: + +**CLI** + +___ + + + + +<br> +<br> + +**GUI** + +___ + + + + + + + + + +%package -n python3-Beads +Summary: A commandline tool to parse fine state machines into code. +Provides: python-Beads +BuildRequires: python3-devel +BuildRequires: python3-setuptools +BuildRequires: python3-pip +%description -n python3-Beads + + +# 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<sup>©</sup>** 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<sup>©</sup>** 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 will 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> +All further informations and details on writing state machines and using **Beads<sup>©</sup>** +can be found below!<br> +<br> +[Project Screenshots](https://docs.google.com/presentation/d/1R3tYoSjhtAN2ghXU36P8B2fT_jkr9z0OJo2ymSYXALM/edit?usp=sharing) +<br> + +## Table of Contents + 1. [Dependencies](#deps) + 2. [Download and Installation](#download) + 3. [Command line usage](#cmd) + 4. [Using the Graphical User Interface](#gui) + 5. [Supported file formats](#formats) + 6. [Used technologies](#techs) + +<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 GUI. To run beads you need to have<br> + +<br> + + * **Python 3.x.x** + * **a web browser of your choice** + +<br> + +installed on your system. And thats it. If you do not have python installed you +can get it from [here](https://www.python.org/downloads/).<br> +The tool is usable without any web browser, however only from the commandline. +<br> + +As listed in the section Used technologies, **Beads<sup>©</sup>** is +built with the python library [Eel](https://pypi.org/project/Eel/) which utilizes Chrome / Chromium +in app-mode to display our GUI. We do not want to force a user that wants to work with the +GUI to install chrome/chromium, neither do we want to package a distribution of them for users +that do not care about the GUI.<br> +<br> +Chrome or Chromium is only a soft dependency, with which **Beads<sup>©</sup>** - GUI +works best. Alternatively any other modern web browser will suffice and the system standard +browser will be used, if no Chrome is detected. +<br> +<br> + +### 2. Download and Installation +<a name="download"></a> + +Dowloading and installing **Beads<sup>©</sup>** is extremely easy:<br> +We deploy the tool and all updates via the [Python Package Index](https://pypi.org). So to get your +hands on the tool simply install it with _pip_ and you are good to go. + +```shell +$ pip install Beads +``` + +Any internal dependencies will be handled by pip!<br> + +The second method is to clone the project with [Git](https://git-scm.com) and set it up +by yourself. We do not support this method and therefore provide no guide on how to. +Any usage described in the sections below may differ if you install the tool this way. +<br> +<br> + +### 3. Commandline usage +<a name="cmd"></a> + +**Beads<sup>©</sup>** follows standard conventions on commandline usage. A list of +available commands and options, as well as documentation for them can be found below.<br> +Alternatively running + +```shell +$ beads --help +#or +$ beads [command] --help +``` + +from the commandline will print the help section of the tool that contains all needed +information as well. We advise users to default to the cmd **--help** option for all commands +and options rather than consulting this section, as that is always up to date. + +**List of commands and options**<br> +_(including examples of usage)_<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 + +# it is possible to filter the languages by appending a search string like 'ava' +# which will only display supported languages that contain the string like 'java' or 'javascript' +$ beads languages ava +``` + +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 /E/documents/controller.bead +# assuming you have a state machine in a .bead file here: /E/documents/controller.bead +# the command will parse the file and save the generated code in the current working directoy. + +$ beads parse /E/documents/controller.beads ../machines/statemachine.json +# it is possible to provide multiple files at once + +$ beads parse machine.json --language python --no-validation +# will skip the validation of state machine logic and try to produce code in python + +$ beads parse machine.json --out ../package/machine.py --replace-existing +# will save generated code in ../package/machine.py and replace an already existing file if there is one + +$ beads parse machine1.bead machine2.bead machine3.bead --base-directory ./machines/code +# will parse all three provided machines and save them in the specified directory ./machines/code + +$ beads parse machine1.bead controller2.json -l java -v -re -bd ../code/generated/ +# Complex example executing verbose, replacing any existing file +# and placing the generated code from both files which will be java code into ../code/generated +``` + +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 -v -p 11000 +# Run the gui in verbose and on localhost:11000 + +$ beads gui --file ./stateMachine.json +# Open the gui and load the provided stateMachine.json to display upon loading +``` + +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 --show +# First prints all available options and then the overview of all currently set defaults + +$ beads options --set-default language python +# Sets the default language used to generate code to python + +$ beads options --unset-default language +# Unsets the default value of language + +$ beads options -s port 11000 -s language java -u verbose +# Multiple -s / -u can be provided with one call: +# First unsets --verbose, then sets --port to 11000 and --language to java + +$ beads options --unset-all +# Clears all saved default options +``` + +<br> +<br> + +### 4. Using the Graphical User Interface +<a name="gui"></a> + +The Graphical User Interface allows the drawing of simple fine state machines. You can draw states and transitions and save the whole graph in different file formats. A tutorial is available within the GUI! +<br> + +All further functionality should be self-explanatory and is properly visualized in the gui. + +<br> +<br> + +### 5. Supported file formats +<a name="formats"></a> + +State machines can be provided in textual representations. Currently there are two file formats that are supported by **Beads<sup>©</sup>**: + + + JSON: file.json + + BEAD: file.bead + +<br> + +**Json format** + +To provide a state machine as a JSON file follow the schema below: + +Three attributes are required: + + + A **name** for the machine + + A list of **nodes** with an "ID" representing the states + + A list of **transitions** with "from" and "to" referencing nodes, and a "label" + +To declare a state as the initial starting state append '"start":true' to the node. + +```json +{ + "name": "NAME", + "nodes": [ + {"id":"ID1", "start":true}, + {"id":"ID2"} + ], + "transitions": [ + {"from":"ID1", "label":"TRANS1", "to":"ID2"}, + {"from":"ID2", "label":"TRANS2", "to":"ID1"} + ] +} +``` +<br> + +**Bead format** + +As an easy-to-write alternative to json files the tool accepts **.bead** files that adhere to the following format: + +``` +#! name:NAME start:ID1 + +ID1:TRANS1:ID2 +ID2:TRANS2:ID1 +``` + +The **.bead** format is transition based. All transitions follow the schema:<br> +FROM_STATE : TRANSITION_NAME : TO_STATE<br> + +The name and the starting point are optional and can be declared as key:value pairs in a config comment on the top of the file. +The comment has to start with '#!' which is followed by a whitespace. + +Parsing of **.bead** files will extract all referenced states so they do not have to be declared separately. + +<br> +<br> + +### 6. Used technologies +<a name='techs'></a> + +We are building an open source lightweight tool for commandline usage with the following techs: + +**CLI** + +___ + + + + +<br> +<br> + +**GUI** + +___ + + + + + + + + + +%package help +Summary: Development documents and examples for Beads +Provides: python3-Beads-doc +%description help + + +# 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<sup>©</sup>** 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<sup>©</sup>** 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 will 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> +All further informations and details on writing state machines and using **Beads<sup>©</sup>** +can be found below!<br> +<br> +[Project Screenshots](https://docs.google.com/presentation/d/1R3tYoSjhtAN2ghXU36P8B2fT_jkr9z0OJo2ymSYXALM/edit?usp=sharing) +<br> + +## Table of Contents + 1. [Dependencies](#deps) + 2. [Download and Installation](#download) + 3. [Command line usage](#cmd) + 4. [Using the Graphical User Interface](#gui) + 5. [Supported file formats](#formats) + 6. [Used technologies](#techs) + +<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 GUI. To run beads you need to have<br> + +<br> + + * **Python 3.x.x** + * **a web browser of your choice** + +<br> + +installed on your system. And thats it. If you do not have python installed you +can get it from [here](https://www.python.org/downloads/).<br> +The tool is usable without any web browser, however only from the commandline. +<br> + +As listed in the section Used technologies, **Beads<sup>©</sup>** is +built with the python library [Eel](https://pypi.org/project/Eel/) which utilizes Chrome / Chromium +in app-mode to display our GUI. We do not want to force a user that wants to work with the +GUI to install chrome/chromium, neither do we want to package a distribution of them for users +that do not care about the GUI.<br> +<br> +Chrome or Chromium is only a soft dependency, with which **Beads<sup>©</sup>** - GUI +works best. Alternatively any other modern web browser will suffice and the system standard +browser will be used, if no Chrome is detected. +<br> +<br> + +### 2. Download and Installation +<a name="download"></a> + +Dowloading and installing **Beads<sup>©</sup>** is extremely easy:<br> +We deploy the tool and all updates via the [Python Package Index](https://pypi.org). So to get your +hands on the tool simply install it with _pip_ and you are good to go. + +```shell +$ pip install Beads +``` + +Any internal dependencies will be handled by pip!<br> + +The second method is to clone the project with [Git](https://git-scm.com) and set it up +by yourself. We do not support this method and therefore provide no guide on how to. +Any usage described in the sections below may differ if you install the tool this way. +<br> +<br> + +### 3. Commandline usage +<a name="cmd"></a> + +**Beads<sup>©</sup>** follows standard conventions on commandline usage. A list of +available commands and options, as well as documentation for them can be found below.<br> +Alternatively running + +```shell +$ beads --help +#or +$ beads [command] --help +``` + +from the commandline will print the help section of the tool that contains all needed +information as well. We advise users to default to the cmd **--help** option for all commands +and options rather than consulting this section, as that is always up to date. + +**List of commands and options**<br> +_(including examples of usage)_<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 + +# it is possible to filter the languages by appending a search string like 'ava' +# which will only display supported languages that contain the string like 'java' or 'javascript' +$ beads languages ava +``` + +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 /E/documents/controller.bead +# assuming you have a state machine in a .bead file here: /E/documents/controller.bead +# the command will parse the file and save the generated code in the current working directoy. + +$ beads parse /E/documents/controller.beads ../machines/statemachine.json +# it is possible to provide multiple files at once + +$ beads parse machine.json --language python --no-validation +# will skip the validation of state machine logic and try to produce code in python + +$ beads parse machine.json --out ../package/machine.py --replace-existing +# will save generated code in ../package/machine.py and replace an already existing file if there is one + +$ beads parse machine1.bead machine2.bead machine3.bead --base-directory ./machines/code +# will parse all three provided machines and save them in the specified directory ./machines/code + +$ beads parse machine1.bead controller2.json -l java -v -re -bd ../code/generated/ +# Complex example executing verbose, replacing any existing file +# and placing the generated code from both files which will be java code into ../code/generated +``` + +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 -v -p 11000 +# Run the gui in verbose and on localhost:11000 + +$ beads gui --file ./stateMachine.json +# Open the gui and load the provided stateMachine.json to display upon loading +``` + +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 --show +# First prints all available options and then the overview of all currently set defaults + +$ beads options --set-default language python +# Sets the default language used to generate code to python + +$ beads options --unset-default language +# Unsets the default value of language + +$ beads options -s port 11000 -s language java -u verbose +# Multiple -s / -u can be provided with one call: +# First unsets --verbose, then sets --port to 11000 and --language to java + +$ beads options --unset-all +# Clears all saved default options +``` + +<br> +<br> + +### 4. Using the Graphical User Interface +<a name="gui"></a> + +The Graphical User Interface allows the drawing of simple fine state machines. You can draw states and transitions and save the whole graph in different file formats. A tutorial is available within the GUI! +<br> + +All further functionality should be self-explanatory and is properly visualized in the gui. + +<br> +<br> + +### 5. Supported file formats +<a name="formats"></a> + +State machines can be provided in textual representations. Currently there are two file formats that are supported by **Beads<sup>©</sup>**: + + + JSON: file.json + + BEAD: file.bead + +<br> + +**Json format** + +To provide a state machine as a JSON file follow the schema below: + +Three attributes are required: + + + A **name** for the machine + + A list of **nodes** with an "ID" representing the states + + A list of **transitions** with "from" and "to" referencing nodes, and a "label" + +To declare a state as the initial starting state append '"start":true' to the node. + +```json +{ + "name": "NAME", + "nodes": [ + {"id":"ID1", "start":true}, + {"id":"ID2"} + ], + "transitions": [ + {"from":"ID1", "label":"TRANS1", "to":"ID2"}, + {"from":"ID2", "label":"TRANS2", "to":"ID1"} + ] +} +``` +<br> + +**Bead format** + +As an easy-to-write alternative to json files the tool accepts **.bead** files that adhere to the following format: + +``` +#! name:NAME start:ID1 + +ID1:TRANS1:ID2 +ID2:TRANS2:ID1 +``` + +The **.bead** format is transition based. All transitions follow the schema:<br> +FROM_STATE : TRANSITION_NAME : TO_STATE<br> + +The name and the starting point are optional and can be declared as key:value pairs in a config comment on the top of the file. +The comment has to start with '#!' which is followed by a whitespace. + +Parsing of **.bead** files will extract all referenced states so they do not have to be declared separately. + +<br> +<br> + +### 6. Used technologies +<a name='techs'></a> + +We are building an open source lightweight tool for commandline usage with the following techs: + +**CLI** + +___ + + + + +<br> +<br> + +**GUI** + +___ + + + + + + + + + +%prep +%autosetup -n Beads-0.1.4 + +%build +%py3_build + +%install +%py3_install +install -d -m755 %{buildroot}/%{_pkgdocdir} +if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi +if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi +if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi +if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi +pushd %{buildroot} +if [ -d usr/lib ]; then + find usr/lib -type f -printf "\"/%h/%f\"\n" >> filelist.lst +fi +if [ -d usr/lib64 ]; then + find usr/lib64 -type f -printf "\"/%h/%f\"\n" >> filelist.lst +fi +if [ -d usr/bin ]; then + find usr/bin -type f -printf "\"/%h/%f\"\n" >> filelist.lst +fi +if [ -d usr/sbin ]; then + find usr/sbin -type f -printf "\"/%h/%f\"\n" >> filelist.lst +fi +touch doclist.lst +if [ -d usr/share/man ]; then + find usr/share/man -type f -printf "\"/%h/%f.gz\"\n" >> doclist.lst +fi +popd +mv %{buildroot}/filelist.lst . +mv %{buildroot}/doclist.lst . + +%files -n python3-Beads -f filelist.lst +%dir %{python3_sitelib}/* + +%files help -f doclist.lst +%{_docdir}/* + +%changelog +* Tue Jun 20 2023 Python_Bot <Python_Bot@openeuler.org> - 0.1.4-1 +- Package Spec generated @@ -0,0 +1 @@ +1d62c02e5233c708905c7f24bdc9c685 Beads-0.1.4.tar.gz |