{
"info": {
"author": "Jakob Baatz, Rico Possienka, Pavel Nepke, Marco Wenning, Adrian Wuillemet",
"author_email": "",
"bugtrack_url": null,
"classifiers": [
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
"Programming Language :: Python :: 3"
],
"description": "\n\n# Beads - A tool to generate code from state machines\n\n_**2019** \u00a9 Jakob Baatz, Rico Possienka, Pavel Nepke, Marco Wenning, Adrian Wuillemet_
\n
\n
\n\n## Introduction\n\nAs a software developer you can encouter state machines as part of a logic that\ncan parse content, as a description of AI behaviour or while modelling some\nbuisness processes.
\nIn whatever form, state machines are cumbersome to code, as the written code is\nvery repetitive and it is quite easy to loose oversight as the machine gets bigger.
\n
\nFor this purpose **Beads\u00a9** can aid you in consistently generating that\ncode from textfiles or drawings that you provide. Simply write a **.json**\n representation of your machine or use our simplified _**.bead**_ format to write\ndown the logic.
\n
\n**Beads\u00a9** is an open source python and webtech tool that can be used\nfrom the command line and is easy to incorporate into scripts for project builds.\nAdditionally the Graphical User Interface (GUI) provides means to draw visual\nrepresentations of your machines and will persist them as _**.svg**_, _**.png**_\n and _**.json**_ files.
\n**Beads\u00a9** comes with a validaten logic for simple state machines,\nthat can be turned off if needed.
\n
\nAll further informations and details on writing state machines and using **Beads\u00a9**\ncan be found below!
\n
\n[Project Screenshots](https://docs.google.com/presentation/d/1R3tYoSjhtAN2ghXU36P8B2fT_jkr9z0OJo2ymSYXALM/edit?usp=sharing)\n
\n\n## Table of Contents\n 1. [Dependencies](#deps)\n 2. [Download and Installation](#download)\n 3. [Command line usage](#cmd)\n 4. [Using the Graphical User Interface](#gui)\n 5. [Supported file formats](#formats)\n 6. [Used technologies](#techs)\n\n
\n
\n\n### 1. Dependencies \n \n\n**Beads\u00a9** is a commandline tool built with Python for the backend and\nweb technologies for the GUI. To run beads you need to have
\n\n
\n\n * **Python 3.x.x**\n * **a web browser of your choice**\n\n
\n\ninstalled on your system. And thats it. If you do not have python installed you\ncan get it from [here](https://www.python.org/downloads/).
\nThe tool is usable without any web browser, however only from the commandline.\n
\n\nAs listed in the section Used technologies, **Beads\u00a9** is\nbuilt with the python library [Eel](https://pypi.org/project/Eel/) which utilizes Chrome / Chromium\nin app-mode to display our GUI. We do not want to force a user that wants to work with the\nGUI to install chrome/chromium, neither do we want to package a distribution of them for users\nthat do not care about the GUI.
\n
\nChrome or Chromium is only a soft dependency, with which **Beads\u00a9** - GUI\nworks best. Alternatively any other modern web browser will suffice and the system standard\nbrowser will be used, if no Chrome is detected.\n
\n
\n\n### 2. Download and Installation \n \n\nDowloading and installing **Beads\u00a9** is extremely easy:
\nWe deploy the tool and all updates via the [Python Package Index](https://pypi.org). So to get your\nhands on the tool simply install it with _pip_ and you are good to go.\n\n```shell\n$ pip install Beads\n```\n\nAny internal dependencies will be handled by pip!
\n\nThe second method is to clone the project with [Git](https://git-scm.com) and set it up\nby yourself. We do not support this method and therefore provide no guide on how to.\nAny usage described in the sections below may differ if you install the tool this way.\n
\n
\n\n### 3. Commandline usage \n \n\n**Beads\u00a9** follows standard conventions on commandline usage. A list of\navailable commands and options, as well as documentation for them can be found below.
\nAlternatively running\n\n```shell\n$ beads --help \n#or\n$ beads [command] --help\n```\n\nfrom the commandline will print the help section of the tool that contains all needed\ninformation as well. We advise users to default to the cmd **--help** option for all commands\nand options rather than consulting this section, as that is always up to date.\n\n**List of commands and options**
\n_(including examples of usage)_
\n\nPrinting information on the terminal:\n```shell\n$ beads [command] [option] --help\n```\n\nPrinting the current version:\n```shell\n$ beads --version\n```\n\nPrint an overview of all supported programming languages:\n```shell\n$ beads languages\n\n# it is possible to filter the languages by appending a search string like 'ava'\n# which will only display supported languages that contain the string like 'java' or 'javascript'\n$ beads languages ava \n```\n\nThe main purpose of the tool is to parse a textual representation of a state machine\ninto working code.
\nTo to so you use the command 'parse':\n```shell\n$ beads parse FILES [options]\n\n# Options\n$ beads parse FILES\n -l / --language # Specify the programming language of the generated code. Default: none\n -o / --out # Specify the output file. Default: ./FILENAME.language\n -re / --replace-existing # FLAG to replace existing files with the generated code\n -nv / --no-validation # FLAG to skip the internal validation of the state machine logic\n -bd / --base-directory # Set a base directory, that all files will be saved in. Default: .\n\n -v / --verbose # FLAG to execute the programm in verbose mode printing all debug information\n\n\n# Examples\n\n$ beads parse /E/documents/controller.bead\n# assuming you have a state machine in a .bead file here: /E/documents/controller.bead\n# the command will parse the file and save the generated code in the current working directoy.\n\n$ beads parse /E/documents/controller.beads ../machines/statemachine.json\n# it is possible to provide multiple files at once\n\n$ beads parse machine.json --language python --no-validation\n# will skip the validation of state machine logic and try to produce code in python\n\n$ beads parse machine.json --out ../package/machine.py --replace-existing\n# will save generated code in ../package/machine.py and replace an already existing file if there is one\n\n$ beads parse machine1.bead machine2.bead machine3.bead --base-directory ./machines/code\n# will parse all three provided machines and save them in the specified directory ./machines/code\n\n$ beads parse machine1.bead controller2.json -l java -v -re -bd ../code/generated/\n# Complex example executing verbose, replacing any existing file\n# and placing the generated code from both files which will be java code into ../code/generated\n```\n\nAll commands related to the Graphical User Interface are bound to 'gui':\n```shell\n$ beads gui [options]\n\n# Options\n$ beads gui\n -b / --background # Run the gui in the background without opening a window\n -p / --port # Run the gui on the specified port. Default: 8000\n -v / --verbose # Run the gui in verbose mode. Default: false\n --file FILE # Run the gui and load the provided FILE. Needs to be a valid json representation of a state machine.\n\n\n# Examples\n\n$ beads gui -v -p 11000\n# Run the gui in verbose and on localhost:11000\n\n$ beads gui --file ./stateMachine.json\n# Open the gui and load the provided stateMachine.json to display upon loading\n```\n\nYou 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.\n\n```shell\n$ beads options [options]\n\n# Options\n$ beads options\n -s / --set-default OPTION VALUE # Set the default VALUE for OPTION\n -u / --unset-default OPTION # Unset the default value for OPTION\n --unset-all # Unset all currently saved defaults.\n --show # Print a list of available Options and their data type\n\n\n# Examples\n\n$ beads options --show\n# First prints all available options and then the overview of all currently set defaults\n\n$ beads options --set-default language python\n# Sets the default language used to generate code to python\n\n$ beads options --unset-default language\n# Unsets the default value of language\n\n$ beads options -s port 11000 -s language java -u verbose\n# Multiple -s / -u can be provided with one call:\n# First unsets --verbose, then sets --port to 11000 and --language to java\n\n$ beads options --unset-all\n# Clears all saved default options\n```\n\n
\n
\n\n### 4. Using the Graphical User Interface\n\n\nThe 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!\n
\n\nAll further functionality should be self-explanatory and is properly visualized in the gui.\n\n
\n
\n\n### 5. Supported file formats\n\n\nState machines can be provided in textual representations. Currently there are two file formats that are supported by **Beads\u00a9**:\n\n + JSON: file.json\n + BEAD: file.bead\n\n
\n\n**Json format**\n\nTo provide a state machine as a JSON file follow the schema below:\n\nThree attributes are required:\n\n + A **name** for the machine \n + A list of **nodes** with an \"ID\" representing the states \n + A list of **transitions** with \"from\" and \"to\" referencing nodes, and a \"label\" \n\nTo declare a state as the initial starting state append '\"start\":true' to the node.\n\n```json\n{\n \"name\": \"NAME\",\n \"nodes\": [\n {\"id\":\"ID1\", \"start\":true},\n {\"id\":\"ID2\"}\n ],\n \"transitions\": [\n {\"from\":\"ID1\", \"label\":\"TRANS1\", \"to\":\"ID2\"},\n {\"from\":\"ID2\", \"label\":\"TRANS2\", \"to\":\"ID1\"}\n ]\n}\n```\n
\n\n**Bead format**\n\nAs an easy-to-write alternative to json files the tool accepts **.bead** files that adhere to the following format:\n\n```\n#! name:NAME start:ID1 \n\nID1:TRANS1:ID2 \nID2:TRANS2:ID1 \n```\n\nThe **.bead** format is transition based. All transitions follow the schema:
\nFROM_STATE : TRANSITION_NAME : TO_STATE
\n\nThe 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.\nThe comment has to start with '#!' which is followed by a whitespace.\n\nParsing of **.bead** files will extract all referenced states so they do not have to be declared separately.\n\n
\n
\n\n### 6. Used technologies\n\n\nWe are building an open source lightweight tool for commandline usage with the following techs:\n\n**CLI**\n\n___\n\n\n\n\n
\n
\n\n**GUI**\n\n___\n\n\n\n\n\n\n\n",
"description_content_type": "text/markdown",
"docs_url": null,
"download_url": "",
"downloads": {
"last_day": -1,
"last_month": -1,
"last_week": -1
},
"home_page": "https://gitlab.com/a.wuillemet/beads",
"keywords": "state machine code generation gui",
"license": "",
"maintainer": "",
"maintainer_email": "",
"name": "Beads",
"package_url": "https://pypi.org/project/Beads/",
"platform": "",
"project_url": "https://pypi.org/project/Beads/",
"project_urls": {
"Homepage": "https://gitlab.com/a.wuillemet/beads"
},
"release_url": "https://pypi.org/project/Beads/0.1.3/",
"requires_dist": [
"click",
"eel",
"markdown"
],
"requires_python": "",
"summary": "A commandline tool to parse fine state machines into code.",
"version": "0.1.3"
},
"last_serial": 5923406,
"releases": {
"0.1.0": [
{
"comment_text": "",
"digests": {
"md5": "dbd020ca0447a80a2b0d3e431f517b65",
"sha256": "7c3c542dfa96b8705589c8c4017b2e52c21061c43e9749ef84637788eb186359"
},
"downloads": -1,
"filename": "Beads-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dbd020ca0447a80a2b0d3e431f517b65",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 1095934,
"upload_time": "2019-07-09T21:06:41",
"url": "https://files.pythonhosted.org/packages/6e/b1/0090ec2c1c7b8564cde82a8473157b6e377dec1d5608d52f08d82d6e6a24/Beads-0.1.0-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "6602a345e60c8cd4a362adc67736e4e5",
"sha256": "b24af8062c233ccb670b4f2dfbcd002f88873191b276cfc8bb352070e5655c86"
},
"downloads": -1,
"filename": "Beads-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "6602a345e60c8cd4a362adc67736e4e5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 1074777,
"upload_time": "2019-07-09T21:06:44",
"url": "https://files.pythonhosted.org/packages/20/b1/437c8a884ca4b6e3dbb25c45306aad97f5be3a21471f22f52816c5ff5eee/Beads-0.1.0.tar.gz"
}
],
"0.1.1": [
{
"comment_text": "",
"digests": {
"md5": "9d425af8dafa2e26c564f10b5966cb91",
"sha256": "8e35019de4df69478a8a537fa83db5e6af4f8933914ac175f85b5962097ac0f4"
},
"downloads": -1,
"filename": "Beads-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9d425af8dafa2e26c564f10b5966cb91",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 1135635,
"upload_time": "2019-07-09T21:38:17",
"url": "https://files.pythonhosted.org/packages/13/57/7638e12c4c6748205590d3cad1677b3acd0197b5f080177122fd22815f2c/Beads-0.1.1-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "5322d45aedbe0ed4ef2e955333340fa8",
"sha256": "0431934b8eca9cf84c525ef87499c6c5a1a8cf11105a5f74da288a0322f6b29f"
},
"downloads": -1,
"filename": "Beads-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "5322d45aedbe0ed4ef2e955333340fa8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 1117125,
"upload_time": "2019-07-09T21:38:19",
"url": "https://files.pythonhosted.org/packages/a1/d9/7f52e578db08ea669ba3132ba6bd3fb1058bd3c30f585a4d8d483cfb1228/Beads-0.1.1.tar.gz"
}
],
"0.1.2": [
{
"comment_text": "",
"digests": {
"md5": "952cdbf0311ee15a9ed7d24eb59ad549",
"sha256": "fc9cd314776c4e544be6a6fa48deafa2b9be7203c4d55750e8c8db49845ca86d"
},
"downloads": -1,
"filename": "Beads-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "952cdbf0311ee15a9ed7d24eb59ad549",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 1135941,
"upload_time": "2019-07-10T19:23:14",
"url": "https://files.pythonhosted.org/packages/a9/f8/02652ed99689533e7429208978158d6c060e230e49df62a5d489958fca19/Beads-0.1.2-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "1e9a6bd5167d90aa68b8c8ccee9de333",
"sha256": "7f41f510587bc7c5d485214155b81beffb02af911cfcb13de9eb880ec0391a40"
},
"downloads": -1,
"filename": "Beads-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "1e9a6bd5167d90aa68b8c8ccee9de333",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 1117528,
"upload_time": "2019-07-10T19:23:17",
"url": "https://files.pythonhosted.org/packages/0f/39/0530880b11a67a2b3bb9171eadcf288472438ca94326ee0795816a31a2d3/Beads-0.1.2.tar.gz"
}
],
"0.1.3": [
{
"comment_text": "",
"digests": {
"md5": "65f1f4a58f9202195af65c3f74be08b7",
"sha256": "3168349fff4eae41c3a280affa7cb38576f9455f089e9af94fd1698f43fa2a85"
},
"downloads": -1,
"filename": "Beads-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "65f1f4a58f9202195af65c3f74be08b7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 28839,
"upload_time": "2019-10-03T13:15:37",
"url": "https://files.pythonhosted.org/packages/20/09/99bcf28183974082b1db79b0985aa915805c35166586019a531db409e409/Beads-0.1.3-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "f6e5b47818f9567ea969b97ed6fb628f",
"sha256": "0d621e9abf413be9dd851bc201ca968839e623b83164bba74dd3de00f725fff0"
},
"downloads": -1,
"filename": "Beads-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "f6e5b47818f9567ea969b97ed6fb628f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 22397,
"upload_time": "2019-10-03T13:15:38",
"url": "https://files.pythonhosted.org/packages/e8/77/c8c4c595078c3b0fc887c62c35f29582612e3d25500359cb6d10eb042075/Beads-0.1.3.tar.gz"
}
]
},
"urls": [
{
"comment_text": "",
"digests": {
"md5": "65f1f4a58f9202195af65c3f74be08b7",
"sha256": "3168349fff4eae41c3a280affa7cb38576f9455f089e9af94fd1698f43fa2a85"
},
"downloads": -1,
"filename": "Beads-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "65f1f4a58f9202195af65c3f74be08b7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 28839,
"upload_time": "2019-10-03T13:15:37",
"url": "https://files.pythonhosted.org/packages/20/09/99bcf28183974082b1db79b0985aa915805c35166586019a531db409e409/Beads-0.1.3-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "f6e5b47818f9567ea969b97ed6fb628f",
"sha256": "0d621e9abf413be9dd851bc201ca968839e623b83164bba74dd3de00f725fff0"
},
"downloads": -1,
"filename": "Beads-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "f6e5b47818f9567ea969b97ed6fb628f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 22397,
"upload_time": "2019-10-03T13:15:38",
"url": "https://files.pythonhosted.org/packages/e8/77/c8c4c595078c3b0fc887c62c35f29582612e3d25500359cb6d10eb042075/Beads-0.1.3.tar.gz"
}
]
}