FiniteConsole 1.0.2
A way to simplify development of CLI applications
License: MIT
Requires Python: >=3.6

# FiniteConsole
A way to simplify development of CLI applications.
## Getting started
This module is based on the finite state machine pattern. It may be logic to represent 
a list of options in the terminal (a page) as a state. So the other lists of 
options (pages) are the other states. The program can be represented as an 
oriented graph with mappings from one state to another one.  
Further the terms "menu" and "option" are interchangeable with the terms 
"state" and "mapping".
### Create the program
Use the `Program` class to create the program object which is singleton. You can 
initialize the program with a `Menu` or append it later.
```python
from FiniteConsole import Program, Menu

p = Program()  # Empty
p.init_menu = Menu('main')

p.drop()
p = Program(Menu('initial'))
```
The program can be dropped with the `drop` method.
### Define a state (a menu)
The states are instances of `Menu` class.  
The constructor takes a required parameter `id_` which is its id. **It must be unique 
for a whole program!**
```python
from FiniteConsole import Menu

main_menu = Menu('main')
```
After you have created the `Program` instance, all new `Menu` instances 
will be appended to the program automatically.
```python
from FiniteConsole import Program, Menu

p = Program(Menu('main'))
Menu(1)
Menu('another_one')
print(p.menus)
# {'main': <Menu object...>, '1': <Menu object...>, 'another_one': <Menu object...>}
```
The second parameter `action` is a function, basically it is None. It means the 
state is not finite.  
Finite states do something and then returns to the precedent state.
```python
import sys
from FiniteConsole import Menu

main_menu = Menu('main')
exit_menu = Menu('exit', lambda: sys.exit())
```
If the program state changes on "exit", the function will be executed.  
Parameters are passed to the function via `args` and `kwargs` attributes of 
the program, they are cleared at every loop iteration. Returned value is in the
`result` attribute of the program, it is conserved until the function returns a 
new value.
```python
from FiniteConsole import Program, Menu

finite = Menu('calc', lambda x: x*x)
p = Program(finite)
p.start_loop()  # E.g. as a thread
p.args = [5]
...
print(p.result)
# 25
```
To remove states use `remove_menus` method of the `Program` instance. You can 
pass either `str` containing ids or `Menu` instances.
### Append a mapping (an option)
Use `append_options` of `Menu` instance to append options to the menu. 
It takes `Option` object, which parameters are `inp` - input name, 
`out` - output name, `description` - text for CLI.
```python
import sys
from FiniteConsole import Menu, Option

main_menu = Menu('main').append_options(
    Option('1', 'exit', 'Quit'),
    Option('2', 'do_stuff_1', 'Amazing stuff'),
    Option('yes', 'Another menu', 'Go to another menu, etc.')
)
```
To remove options use `remove_options` method of a `Menu` instance.
### Run
Just use `start_loop` and `stop_loop` methods to run and stop the program.  
If your graph has faults, e.g. options leading nowhere, you will see report about 
these faults in the CLI. 
## Extensions
You can change representation of options and input method. 
### Render
Redefine the method `render` of the `Menu` class. It is responsible for CLI 
presentation of menus.
### Input for mapper
Redefine the method `read_input` of the `Menu` class. It is responsible for getting 
of a new input for mapping. The returned value must be a `str` with id of a new 
state.
## Example
```python
import sys
from FiniteConsole import Menu, Option, Program


def func():
    x = float(input('Enter a number: '))
    print(x*x)


main_menu = Menu('main').append_options(
    Option('0', 'exit', 'Quit'),  # Finite
    Option('1', 'stuff_1', 'Square'),  # Finite
    Option('3', 'submenu', 'Go to another menu')
)
p = Program(main_menu)

Menu('submenu').append_options(Option('back', 'main', 'Go back'))

# Finite states
Menu('exit', lambda: sys.exit())
Menu('stuff_1', func)


p.start_loop()
```
And yes. You can change program's comportment while runtime: append other menus, 
options, etc.