Metadata-Version: 2.1
Name: cmdmenu
Version: 0.1.1
Summary: A library for creating hierarchical command line arg menus.
Home-page: https://github.com/arkocal/pycmdmenu.git
Author: Ali Rasim Kocal
Author-email: arkocal@gmail.com
License: UNKNOWN
Description: # cmdmenu
        
        `cmdmenu` is a simple library based on `argparse` for automatically creating command line interfaces
        consisting of levels of hierarchy (like git) and linking them to functions.
        
        ## Installation
        
        Run `pip install cmdmenu`
        
        ## Usage
        
        See `/examples` for full exampes.
        
        ### Adding commands
        
        Use the `cmdmenu.add_command` function for adding commands.
        
        ```python
        import argparse
        import cmdmenu
        
        def echo(message):
            print(message)
        
        def mirror_echo(message):
            print(message[::-1])
        
        parser = argparse.ArgumentParser("An example application")
        subparsers = parser.add_subparsers()
        
        cmdmenu.add_command(subparsers, echo)
        cmdmenu.parse_and_run_with(parser)
        ```
        
        Run like this.
        ```
        $ python main.py echo Hello
        Hello
        $ python main.py mirror_echo Hello
        olleH
        ```
        
        You can add a help message and a description to your commands using the
        `cmdmenu_function` decorator. If you only specify one parameter, it will be used for both,
        otherwise, the first one is the short help message, the second one is the description.
        
        You can also add a string annotation to function parameters to generate help message
        
        ```python
        @cmdmenu.cmdmenu_function("Echo to terminal", "Longer description of echo")
        def echo(message: "Message to echo"):
            print(message)
        ```
        
        ```
        $ python main.py --help
        usage: An example application [-h] {echo,mirror_echo} ...
        
        positional arguments:
          {echo,mirror_echo}
            echo              Echo to terminal
            mirror_echo       Echo reversed
        
        optional arguments:
          -h, --help          show this help message and exit
        $ python main.py echo --help
        usage: An example application echo [-h] message
        
        Longer description of echo
        
        positional arguments:
          message     Message to echo
        
        optional arguments:
          -h, --help  show this help message and exit
        ```
        
        #### Default values
        `cmdmenu` respects parameter default values. If a parameter has a default value, a flag will
        be created for it. You can override the flag name using a dictionary annotation (see below) with the
        `name` parameter.
        
        ```python
        @cmdmenu.cmdmenu_function("Print a hello world message")
        def hello(name=None):
            if name is None:
                print("Hello, World!")
            else:
                print("Hello, {}".format(name))
        ```
        
        ```
        $ python main.py hello
        Hello, World!
        $ python main.py hello --name Ali
        Hello, Ali!
        ```
        
        
        #### More annotations
        You can pass a dictionary as parameter annotation, the arguments are then passed to `argparse`.
        See `add_command` docstring for more details.
        
        ```python
        @cmdmenu.cmdmenu_function("Print sum of given numbers")
        def add_numbers(numbers: {"help": "Numbers to sum up",
                          "nargs": "+", "type":int}):
            print(sum(numbers))
        ```
        
        ```
        $ python main.py add_numbers 1 2 3
        6
        ```
        
        ### Adding modules
        
        You can all functions marked by the `cmdmenu_function` in a module (and its submodules)
        using the `add_module` function.
        
        You can save the functions from previous example in my_commands.py, and run the following
        
        ```python
        import argparse
        import cmdmenu
        
        import my_commands
        
        if __name__ == "__main__":
            parser = argparse.ArgumentParser("An example application")
            subparsers = parser.add_subparsers()
        
            cmdmenu.add_module(subparsers, my_commands, toplevel=True)
            cmdmenu.parse_and_run_with(parser)
        ```
        
        This will create an identical program. The `toplevel=True` parameter indicates that the functions
        should be added directly without creating an editional level.
        
        By default `add_module` adds all the submodules of given module, which contain a variable called
        `CMDMENU_META`.
        
        Take the following structure as
        an example:
        ```
        main.py
        fakegit
            __init__.py -> defines add, rm
            remote.py -> defines add rename
            my_addon/
        	features -> defines foo, bar
        	items -> defines baz
        ```
        
        By adding fakegit as a toplevel, you get the following commands, each with positional and keyword
        arguments as defined by the functions:
        ```
        python main.py add
        python main.py rm
        python main.py remote add
        python main.py remote rename
        python main.py my_addon features foo
        python main.py my_addon features bar
        python main.py items baz
        ```
        
        Submodule menu behaviour and documentation can be configured with a `CMDMENU_META` dictionary.
        See `add_module` docstring for details.
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
