Beads 0.1.4

A commandline tool to parse fine state machines into code.

Beads - A tool to generate code from state machines

2019 ^© Jakob Baatz, Rico Possienka, Pavel Nepke, Marco Wenning, Adrian Wuillemet

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.
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.

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.

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 will persist them as .svg, .png and .json files.
Beads^© comes with a validaten logic for simple state machines, that can be turned off if needed.

All further informations and details on writing state machines and using Beads^© can be found below!

Project Screenshots

Table of Contents

1. Dependencies
2. Download and Installation
3. Command line usage
4. Using the Graphical User Interface
5. Supported file formats
6. Used technologies

1. Dependencies

Beads^© is a commandline tool built with Python for the backend and web technologies for the GUI. To run beads you need to have

• Python 3.x.x
• a web browser of your choice

installed on your system. And thats it. If you do not have python installed you can get it from here.
The tool is usable without any web browser, however only from the commandline.

As listed in the section Used technologies, Beads^© is built with the python library 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.

Chrome or Chromium is only a soft dependency, with which Beads^© - GUI works best. Alternatively any other modern web browser will suffice and the system standard browser will be used, if no Chrome is detected.

2. Download and Installation

Dowloading and installing Beads^© is extremely easy:
We deploy the tool and all updates via the Python Package Index. So to get your hands on the tool simply install it with pip and you are good to go.

$ pip install Beads

Any internal dependencies will be handled by pip!

The second method is to clone the project with Git 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.

3. Commandline usage

Beads^© follows standard conventions on commandline usage. A list of available commands and options, as well as documentation for them can be found below.
Alternatively running

$ 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
(including examples of usage)

Printing information on the terminal:

$ beads [command] [option] --help

Printing the current version:

$ beads --version

Print an overview of all supported programming languages:

$ 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.
To to so you use the command 'parse':

$ 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':

$ 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.

$ 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

4. Using the Graphical User Interface

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!

All further functionality should be self-explanatory and is properly visualized in the gui.

5. Supported file formats

State machines can be provided in textual representations. Currently there are two file formats that are supported by Beads^©:

• JSON: file.json
• BEAD: file.bead

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.

{
   "name": "NAME",
   "nodes": [
      {"id":"ID1", "start":true},
      {"id":"ID2"}
   ],
   "transitions": [
      {"from":"ID1", "label":"TRANS1", "to":"ID2"},
      {"from":"ID2", "label":"TRANS2", "to":"ID1"}
   ]
}

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:
FROM_STATE : TRANSITION_NAME : TO_STATE

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.

6. Used technologies

We are building an open source lightweight tool for commandline usage with the following techs:

CLI

---

GUI

---