Metadata-Version: 2.1
Name: FiniteConsole
Version: 1.0.2
Summary: A way to simplify development of CLI applications
Home-page: https://github.com/cyrillelamal/FiniteConsole
Author: Cyrille Kossyguine
Author-email: lambda_man@outlook.fr
License: MIT
Description: # 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.
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
