tiramisu-cmdline-parser/README.md

167 lines
5.4 KiB
Markdown
Raw Normal View History

2018-12-01 08:28:35 +01:00
# tiramisu-cmdline-parser
2018-11-29 21:57:46 +01:00
2018-11-29 22:49:35 +01:00
Python3 parser for command-line options and arguments using Tiramisu engine.
2018-11-29 22:47:12 +01:00
2018-12-01 08:28:35 +01:00
# example
2018-11-29 22:47:12 +01:00
2018-12-01 08:28:35 +01:00
Let us start with a simple example
2018-11-29 22:47:12 +01:00
```python
#!/usr/bin/env python3
from tiramisu_cmdline_parser import TiramisuCmdlineParser
2018-12-01 08:28:35 +01:00
from tiramisu import IntOption, StrOption, BoolOption, ChoiceOption, \
SymLinkOption, OptionDescription, Config
# build a Config with:
# * a choice for select a sub argument (str, list, int)
choiceoption = ChoiceOption('cmd',
'choice the sub argument',
('str', 'list', 'int'),
2019-01-28 17:05:50 +01:00
properties=('mandatory',
'positional'))
2018-12-01 08:28:35 +01:00
# * a boolean to pass script in verbosity mode with argument -v --verbosity
2018-11-29 22:47:12 +01:00
booloption = BoolOption('verbosity',
'increase output verbosity',
default=False)
2018-12-01 08:28:35 +01:00
short_booloption = SymLinkOption('v', booloption)
# * a string option if cmd is 'str'
str_ = StrOption('str',
'string option',
properties=('mandatory',),
requires=[{'option': choiceoption,
'expected': 'str',
'action': 'disabled',
'inverse': True}])
# * a list of strings option if cmd is 'list'
list_ = StrOption('list',
'list string option',
multi=True,
properties=('mandatory',),
requires=[{'option': choiceoption,
'expected': 'list',
'action': 'disabled',
'inverse': True}])
# * an integer option if cmd is 'int'
int_ = IntOption('int',
'int option',
properties=('mandatory',),
requires=[{'option': choiceoption,
'expected': 'int',
'action': 'disabled',
'inverse': True}])
2018-12-01 09:53:31 +01:00
# Now build Config
2018-12-01 08:28:35 +01:00
config = Config(OptionDescription('root',
'root',
[choiceoption,
booloption,
short_booloption,
str_,
list_,
int_
]))
# initialise the parser
2019-01-28 17:05:50 +01:00
config.property.read_write()
2019-01-28 11:44:50 +01:00
parser = TiramisuCmdlineParser(config)
2018-12-01 08:28:35 +01:00
# parse arguments of current script
2018-11-29 22:47:12 +01:00
parser.parse_args()
2018-12-01 08:28:35 +01:00
# now, print the result
print('result:')
config.property.read_only()
for key, value in config.value.dict().items():
print('- {} ({}): {}'.format(key,
config.option(key).option.doc(),
value))
2018-11-29 22:47:12 +01:00
```
2018-12-01 08:28:35 +01:00
Let's print help:
2018-11-29 22:49:35 +01:00
```bash
2018-12-01 08:28:35 +01:00
[gnunux@localhost tiramisu-parser]$ python3 prog.py str -h
usage: prog.py [-h] [-v] --str STR --list LIST [LIST ...] --int INT
{str,list,int}
2018-11-29 22:47:12 +01:00
positional arguments:
2018-12-01 08:28:35 +01:00
{str,list,int} choice the sub argument
2018-11-29 22:47:12 +01:00
optional arguments:
2018-12-01 08:28:35 +01:00
-h, --help show this help message and exit
-v, --verbosity increase output verbosity
--str STR string option
--list LIST [LIST ...]
list string option
--int INT int option
2018-11-29 22:47:12 +01:00
```
2018-12-01 08:28:35 +01:00
The positional argument 'cmd' is mandatory:
2018-11-29 22:49:35 +01:00
```bash
2018-12-01 08:28:35 +01:00
[gnunux@localhost tiramisu-parser]$ python3 prog.py
usage: prog.py [-h] [-v] --str STR --list LIST [LIST ...] --int INT
{str,list,int}
prog.py: error: the following arguments are required: cmd
2018-11-29 22:47:12 +01:00
```
2018-12-01 08:28:35 +01:00
If 'cmd' is 'str', --str become mandatory:
```bash
[gnunux@localhost tiramisu-parser]$ python3 prog.py str
usage: prog.py [-h] [-v] --str STR --list LIST [LIST ...] --int INT
{str,list,int}
prog.py: error: the following arguments are required: --str
```
2018-12-01 09:53:31 +01:00
If 'cmd' is 'str', cannot set --int argument:
```bash
[gnunux@localhost tiramisu-parser]$ python3 prog.py str --int 3
usage: prog.py [-h] [-v] --str STR --list LIST [LIST ...] --int INT
{str,list,int}
prog.py: error: unrecognized arguments: --int
```
2018-12-01 08:28:35 +01:00
With all mandatories arguments:
2018-11-29 22:49:35 +01:00
```bash
2018-12-01 08:28:35 +01:00
[gnunux@localhost tiramisu-parser]$ python3 prog.py str --str value
result:
- cmd (choice the sub argument): str
- verbosity (increase output verbosity): False
- v (increase output verbosity): False
- str (string option): value
2018-11-29 22:47:12 +01:00
```
2018-11-29 22:49:35 +01:00
```bash
2018-12-01 08:28:35 +01:00
[gnunux@localhost tiramisu-parser]$ python3 prog.py int --int 3
result:
- cmd (choice the sub argument): int
- verbosity (increase output verbosity): False
- v (increase output verbosity): False
- int (int option): 3
2018-11-29 22:47:12 +01:00
```
2018-11-29 22:49:35 +01:00
```bash
2018-12-01 08:28:35 +01:00
[gnunux@localhost tiramisu-parser]$ python3 prog.py list --list a b c
result:
- cmd (choice the sub argument): list
- verbosity (increase output verbosity): False
- v (increase output verbosity): False
- list (list string option): ['a', 'b', 'c']
2018-11-29 22:47:12 +01:00
```
2018-12-01 09:53:31 +01:00
Add --verbosity argument:
```bash
[gnunux@localhost tiramisu-parser]$ python3 prog.py list --list a b c -v
result:
- cmd (choice the sub argument): list
- verbosity (increase output verbosity): True
- v (increase output verbosity): True
- list (list string option): ['a', 'b', 'c']
[gnunux@localhost tiramisu-parser]$ python3 prog.py list --list a b c --verbosity
result:
- cmd (choice the sub argument): list
- verbosity (increase output verbosity): True
- v (increase output verbosity): True
- list (list string option): ['a', 'b', 'c']
```