First commit

Presenting the automatabpp module

Author: grimar2008

README.md

@@ -1 +1,110 @@
-# Python Automata Based Programming Paradigm
+# Python Automata-Based Programming Paradigm
+
+### Short introduction to the project
+
+Presenting my Python programming paradigm with which we can separate the application into several parts:
+
+- Behaviour
+- Execution
+- MainLoop
+
+Many of the people reading this might think: _"Hey, but MainLoop **is** the behaviour and execution as well"_ and you would be right.
+However, do allow me to elaborate on this. My reasoning is that everything should be simplified if it can be.
+
+The goal here is actually to define some behaviour parts of your program in easy to read graphs and only write the execution parts in the code.
+This way you can concentrate on writing code for your main loop only.
+
+Naturally, everything is better when there is an example with it to explain it even more so I recommend you check [the examples](#additional-links) in the repository first.
+
+### A short explanation of the project
+
+To really simplify what this is all about in one sentence: ___"Instead of programming the code yourself you draw graphs to define the behaviour."___
+
+These graphs are loaded when first executing your code and are _automatically_ connected to their execution part.
+
+Each graph is called a machine, and each execution is called a state. (Yes, there can be several machines working consecutively at the same time)
+
+To get a better idea of what's going on here's a quick example. Using a [__yEd Graph Editor__][4] Create a .graphml graph like this one and store it in the _graphs/_ folder of your project as _first.graphml_ .
+
+![](./README/images/first.png)
+
+Run the next code: (don't forget to clone the repository into your project folder)
+
+```python
+import automatabpp as FSM
+
+FSM.BEHAVIOUR.load_behaviour_from_graph("first.graphml", "My First Finite State Machine")
+
+@FSM.EXECUTION.state
+def ON_START(*args, **kwargs):
+    print("FSM start")
+
+@FSM.EXECUTION.state
+def HELLO(*args, **kwargs):
+    print("Hello!")
+
+FSM.OPERATION.start_fsm()                   # prints "FSM start"
+FSM.OPERATION.run_fsm("is_anyone_there")    # prints "Hello!"
+```
+
+To learn more please check [the examples at the bottom of the page](#additional-links).
+
+***
+
+### Why a paradigm and not a pattern?
+
+While developing this project I ran into this quote on [wikipedia][1]. To quote:
+
+> "Automata-based programming is a programming paradigm in which the program or part of it is thought of as a model of a finite state machine (automatabpp) or any other (often more complicated) formal automaton."
+
+There is also a [definition on programming paradigm][2] that I found fitting this project perfectly.
+
+> "A programming paradigm is a style, or “way,” of programming."
+
+Indeed, there is more than enough style in developing this way once you learn how to do it.
+
+### How does this differ from ... ?
+
+There are countless ways to develop your program and this one is just one take on it.
+However I do feel there are some advanteges to using the Automata-Based programming over some other approach.
+* Explanation of the code can be easily visualized since most of the code is done by drawing graphs
+* If the machines are well defined the execution and the main loop can be really simple
+* __It's fun__ _(if you consider drawing FSMs to be fun)_
+
+I'll also leave these [two quotes here][3]:
+> "Programs must be written for people to read, and only incidentally for machines to execute." - Abelson & Sussman
+
+> "Typing is no substitute for thinking." - Richard W. Hamming
+
+### What other software do I need ?
+I would recommend you download the [yEd Graph Editor from their official homepage][4]. This project can only import ___.graphml___ graphs at the moment.
+However I do plan on adding code to import more formats in the future.
+
+__yEd Graph Editor__ is used for viewing and drawing our state machine graphs.
+We consider nodes of the graph to be the states and the edges to be the transitions.
+
+I also recommend using **Python 3.4+** although I haven't even tried it yet on the older versions. This project uses `logging` and `xml` Python modules so install them if needed.
+
+### Directories
+
+* **./automatabpp** - our module source code. This directory contains the python code for this project.
+* **./comparisons** - a small module which offers some lambda comparison functions you can use with this project.
+* **./graphs** - yEd graphs are stored in this directory by default
+* **./README** - I've really took my time to write all of this so I would appreciate you checking it out
+
+### Additional Links
+
+Here are some other .md links for You to read about this project.
+* [A list of available functions](README/FSM.md)
+* [Tutorial](README/tutorial.md) - make a _"Hello, World!"_ type of application (sort of). Also some more insight on what happens in the code itself.
+* [Example 1](README/examples/example1.md) - a simple e-mail validation machine
+* [Example 2](README/examples/example2.md) - an example for developing with multiple machines
+* [Example 3](README/examples/example3.md) - an example showcasing Base64 encode with this paradigm
+* [Example 4](README/examples/example4.md) - developing your embedded application with _complex_ behaviour
+* [Other](README/other.md)
+
+
+[1]: https://en.wikipedia.org/wiki/Automata-based_programming "Automata-based programming"
+[2]: https://cs.lmu.edu/~ray/notes/paradigms/ "Programming Paradigms"
+[3]: https://en.wikiquote.org/wiki/Programming_languages "Wikiquote - Programming languages"
+[4]: https://www.yworks.com/products/yed "yWorks Homepage"

README/FSM.md

@@ -0,0 +1,53 @@
+# FSM
+
+I won't cover too much how the code is written but rather how to use it.
+
+Once we `import automatabpp` into our python script we can use the following 4 classes.
+
+| [OPERATION](#operation) | [BEHAVIOUR](#behaviour) | [EXECUTION](#execution) | [INTERFACE](#interface) |
+| --- | --- | --- | --- |
+
+
+### OPERATION
+
+Operation is a class that only executes the global operations on the FSMs.
+```python
+OPERATION.start_fsm()       # Starts the FSMs by sending the '_start_' command to all the machines
+
+OPERATION.stop_fsm()        # Stops all the FSMs by sending the '_stop_' command to all the machines,
+                            # reseting them to the default '_START_' state and emptying the machine commands stack.
+
+OPERATION.reset_fsm()       # Stops and starts the FSMs
+
+OPERATION.run_fsm()         # Runs all the commands in the CommandQueue until the queue is empty.
+
+OPERATION.run_fsm(cmd)      # Runs only the cmd on all machines now without running the rest of the queue.
+```
+
+### BEHAVIOUR
+Behaviour class is used to load the machine behaviour from the graph.
+```python
+BEHAVIOUR.set_default_graph_directory(path)             # sets the default graph directory path
+
+BEHAVIOUR.load_behaviour_from_graph(path, machine_name) # loads the machine from path and stores it as machine_name
+```
+
+### EXECUTION
+Execution class consists only of an operator on our function that defines what function should be called once the state has been reached.
+```python
+EXECUTION.state(func)       # usually used as a decorator over the function we wish to be called on state execution
+```
+
+### INTERFACE
+Interface is an interface to the automatabpp we can use. Consists of only a decorator we can use on a function.
+```python
+INTERFACE.run_command_if_lambda_on_result_true(lambda_function, command)
+# When the function decorated with this function is called, the command will be run if the lambda on result is True
+```
+
+
+| [Back to Main][prev] | ----- | [Tutorial][next] |
+| --- | --- | --- |
+
+[prev]: ../README.md "Main"
+[next]: tutorial.md "Tutorial"

README/examples/example1.md

@@ -0,0 +1,103 @@
+# Example 1
+
+Here is an explanation of [example1.py][pycode] script you can run.
+
+| [BACKGROUND](#background) | [GRAPH](#graph) | [CODE OVERVIEW](#code-overview)| [OTHER](#other) |
+| --- | --- | --- | --- |
+
+### Background
+
+One of the basic uses of FSMs is regex validation, and one of the most used regex validations is e-mail address validation.
+
+[This stack overflow answer][1] sheds some light on what regex we should use to check if an e-mail is valid or not.
+
+What I will do here is walk you through implementing a simple automatabpp overcoming this problem.
+
+### Graph
+
+Here is the graph from the above mentioned stack overflow answer:
+
+<img src="https://i.stack.imgur.com/YI6KR.png" width="640" height="400" />
+
+I guess this graph could have been made somewhat simpler but this is not of interest at the moment.
+What we will do is implement just the upper half of this graph as we really don't want to deal with some weird ASCII characters currently.
+
+The image of our state machine that implements this behaviour can be seen on the next picture. It is located in the _graphs_ folder under the name _email/email.graphml_
+
+<img src="../images/examples/example1/email.png" width="640" height="420" />
+
+Be sure to check how the transitions are defined. If we want to use multiple commands between the same state we only need to separate it by spaces or newlines.
+
+If the validation fails at any step the state of the machine will be `GARBAGE` and if this has been our last character to check we only need to send the `_stop_` command to see if the result is an e-mail or not.
+
+
+### Code Overview
+
+Let's see how this is implemented in the [example1.py][pycode] script.
+
+
+- We import all the automatabpp module classes:
+    ```python
+    from automatabpp import *
+    ```
+- This is a function we will use to shorten the code:
+    ```python
+    def test_email():
+        for char in email_to_test:
+            OPERATION.run_fsm(char)
+        OPERATION.stop_fsm()
+    ```
+    What this means is we will take one by one character from the e-mail and run it through our machine. At the very end we will send the `_stop_` command to let the automatabpp know we're done.
+
+- Here comes our graph loading and execution definitions. The `EXECUTION.state` decorator connects the function to the state with the same name in the graph:
+    ```python
+    BEHAVIOUR.load_behaviour_from_graph("email/email.graphml", "E-Mail validation machine")
+
+    @EXECUTION.state
+    def GARBAGE(**_):
+        print("{} IS NOT A VALID EMAIL".format(email_to_test))
+
+    @EXECUTION.state
+    def EMAIL(**_):
+        print("{} IS A VALID EMAIL".format(email_to_test))
+    ```
+    We are only interested in two states here: "Is it, or is it not, a valid e-mail?"
+
+- Let's run the machine and check our first e-mail address:
+    ```python
+    OPERATION.start_fsm()
+
+    email_to_test = "[email protected]"
+    test_email()
+    ```
+- Once we're done we can restart the machine since it is currently in __EMAIL__ state and check another e-mail address:
+    ```python
+    OPERATION.reset_fsm()
+
+    email_to_test = "an._invalid@email@example-"
+    test_email()
+    ```
+
+If we run our code we should see the following in the console:
+```console
+user@computer:~$ python example1.py
+a_valid@email.example IS A VALID EMAIL
+an._invalid@email@example- IS NOT A VALID EMAIL
+user@computer:~$
+```
+
+### Other
+
+Let's check a couple of things we've learned here:
+* We don't need to define every state execution in the code
+* The FSMs can be reset at any time
+* We can define multiple transitions using the same edge in a graph
+
+
+| [Back to Tutorial][prev] | ----- | [Example 2][next] |
+| --- | --- | --- |
+
+[1]: https://stackoverflow.com/questions/201323/how-to-validate-an-email-address-using-a-regular-expression "E-Mail regex"
+[pycode]: ../../example1.py "pycode"
+[prev]: ../tutorial.md "Tutorial"
+[next]: example2.md "Example 2"

README/examples/example2.md

@@ -0,0 +1,100 @@
+# Example 2
+
+I needed a simple example of how the machines can work and communicate together so I came up with this one. Check the code at [example2.py][pycode] .
+
+| [BACKGROUND](#background) | [GRAPH](#graph) | [CODE OVERVIEW](#code-overview)| [OTHER](#other) |
+| --- | --- | --- | --- |
+
+### Background
+
+It might not be obvious so far but there can be multiple machines parsing commands at the same time. They can even
+command each other what to do next, and all that without having to write a single line of py code (other than importing and running the automatabpp).
+
+### Graph
+
+Let's see the two graphs we will be using this time. The first one is called _hbfs/harderfaster.graphml_
+
+<img src="../images/examples/example2/harderfaster.png" width="640" height="420" />
+
+I've already put a note in the image about what you should note this time. The node `HARDER` has the value `better` in it's description. What this means is that once the state `HARDER` is executed the command `better` will be added to the `CommandQueue` for later execution.
+
+State `FASTER` also has a similar description named `stronger`.
+
+Let's check the graph under _hbfs/betterstronger.graphml_
+
+<img src="../images/examples/example2/betterstronger.png" width="640" height="420" />
+
+The graph is almost the same with the only difference of one additional state.
+This state is added so the two graphs are balanced and don't start at the same time.
+
+
+### Code Overview
+
+Let's see how this is implemented in the [example2.py][pycode] script.
+
+
+- We import all the automatabpp module classes:
+    ```python
+    from automatabpp import *
+    ```
+- Let's define a function for printing everything in the same line but with a delay:
+    ```python
+    def print_w_timeout(text: str):
+        import time
+        print("\r {}".format(text), end="")
+        time.sleep(0.6)
+    ```
+
+- Load the first graph:
+    ```python
+    BEHAVIOUR.load_behaviour_from_graph("hbfs/harderfaster.graphml", "HARDER/FASTER")
+
+    @EXECUTION.state
+    def HARDER(**_):
+        print_w_timeout("Work it harder")
+
+    @EXECUTION.state
+    def FASTER(**_):
+        print_w_timeout("Do it faster")
+    ```
+    The execution is just printing with our custom print function.
+
+- Do the same for the second graph:
+    ```python
+    BEHAVIOUR.load_behaviour_from_graph("hbfs/betterstronger.graphml", "BETTER/STRONGER")
+
+    @EXECUTION.state
+    def BETTER(**_):
+        print_w_timeout("make it better")
+
+    @EXECUTION.state
+    def STRONGER(**_):
+        print_w_timeout("makes us stronger")
+    ```
+
+- All that's left is to run the machine:
+    ```python
+    OPERATION.start_fsm()
+    OPERATION.run_fsm()
+    ```
+    One thing to note here is that the `OPERATION.run_fsm()` is executed here without any argument.
+    That means it will run all the commands in the `CommandQueue` until the queue is empty.
+    
+Run the code and see what you get.
+```console
+user@computer:~$ python example2.py
+```
+
+### Other
+
+Let's check a couple of things we've learned here:
+* We can define multiple graphs at the same time
+* The after-execution-commands can also be defined in the graph
+* Graphs defined in this way can be stuck in an infinite loop
+
+| [Back to Example 1][prev] | ----- | [Example 3][next] |
+| --- | --- | --- |
+
+[pycode]: ../../example2.py "pycode"
+[prev]: example1.md "Example 1"
+[next]: example3.md "Example 3"