github/RRG-Proxmark3
1
0
Fork 0
mirror of https://github.com/RfidResearchGroup/proxmark3.git synced 2025-08-20 13:23:51 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

clean cliparser doc and add arg_dbl

Browse source
This commit is contained in:
Philippe Teuwen 2020-10-04 15:13:32 +02:00
commit 7009f2ade7
1 changed files with 46 additions and 40 deletions
Download patch file Download diff file Expand all files Collapse all files

86
doc/cliparser.md
View file

@ -13,24 +13,24 @@ lf config h H
even the external tools which we collected into this repo, under folder */tools/* folder uses their own argument parsing. even the external tools which we collected into this repo, under folder */tools/* folder uses their own argument parsing.
In order to counter this and unify it, there was discussion over at the official repository a few years ago [link to issue](https://github.com/Proxmark/proxmark3/issues/467) and there it became clear a change is needed. Among the different solutions suggested @merlokk's idea of using the lib cliparser was agreed upon. The lib was adapted and implemented for commands like In order to counter this and unify it, there was discussion over at the official repository a few years ago [link to issue](https://github.com/Proxmark/proxmark3/issues/467) and there it became clear a change is needed. Among the different solutions suggested @merlokk's idea of using the lib cliparser was agreed upon. The lib was adapted and implemented for commands like
``` ```
[usb] pm3 --> emv [usb] pm3 --> emv
[usb] pm3 --> hf fido [usb] pm3 --> hf fido
``` ```
And then it fell into silence since it wasn't well documented how to use the cliparser. Looking at source code wasn't very efficient. However the need of a better cli parsing was still there. And then it fell into silence since it wasn't well documented how to use the cliparser. Looking at source code wasn't very efficient. However the need of a better cli parsing was still there.
Fast forward today, where more commands has used the cliparser but it still wasn't the natural way when adding a new client command to the Proxmark3 client. Fast forward today, where more commands has used the cliparser but it still wasn't the natural way when adding a new client command to the Proxmark3 client.
After more discussions among @doegox, @iceman1001 and @mrwalker the concept became more clear on how to use the cliparser lib in the _preferred_ way. After more discussions among @doegox, @iceman1001 and @mrwalker the concept became more clear on how to use the cliparser lib in the _preferred_ way.
The aftermath was a design and layout specfied which lead to a simpler implemtentation of the cliparser in the client source code while still unfiy all helptexts with the new colours support and a defined layout. As seen below, the simplicity and clearness. The aftermath was a design and layout specfied which lead to a simpler implemtentation of the cliparser in the client source code while still unfiy all helptexts with the new colours support and a defined layout. As seen below, the simplicity and clearness.
![sample of new style helptext](http://www.icedev.se/proxmark3/helptext.png) ![sample of new style helptext](http://www.icedev.se/proxmark3/helptext.png)
Furthermore @mrwalker offered to take notes and thus this document was created. Furthermore @mrwalker offered to take notes and thus this document was created.
This is the _new_ and _prefered_ way to implement _helptext_ and _cli parsing_ for Proxmark3 client commands and it's external tools. This is the _new_ and _prefered_ way to implement _helptext_ and _cli parsing_ for Proxmark3 client commands and it's external tools.
@ -42,11 +42,11 @@ It will also add the `-h --help` option automatic.
## design comments ## design comments
* where possible all options should be lowercase. * where possible all options should be lowercase.
* extended options preceded with -- should be short * extended options preceded with -- should be short
* options provided directly (without an option identifier) should be avoided. * options provided directly (without an option identifier) should be avoided.
* -vv for extra verbos should be avoided; use of debug level is preferred. * -vv for extra verbos should be avoided; use of debug level is preferred.
* with --options the equal is not needed (will work with and without) so don't use '=' * with --options the equal is not needed (will work with and without) so don't use '='
e.g. cmd --cn 12345 e.g. cmd --cn 12345
@ -82,9 +82,9 @@ CLIParserInit (\<context\>, \<description\>, \<notes\n examples ... \>);
use -> to separate example and example comment and \\n to separate examples. use -> to separate example and example comment and \\n to separate examples.
e.g. lf indala clone -r a0000000a0002021 -> this uses ..... e.g. lf indala clone -r a0000000a0002021 -> this uses .....
CLIParserInit(&ctx, "lf indala clone", CLIParserInit(&ctx, "lf indala clone",
"clone INDALA UID to T55x7 or Q5/T5555 tag", "clone INDALA UID to T55x7 or Q5/T5555 tag",
"lf indala clone --heden 888\n" "lf indala clone --heden 888\n"
"lf indala clone --fc 123 --cn 1337\n" "lf indala clone --fc 123 --cn 1337\n"
"lf indala clone -r a0000000a0002021\n" "lf indala clone -r a0000000a0002021\n"
"lf indala clone -l -r 80000001b23523a6c2e31eba3cbee4afb3c6ad1fcf649393928c14e5"); "lf indala clone -l -r 80000001b23523a6c2e31eba3cbee4afb3c6ad1fcf649393928c14e5");
@ -93,9 +93,9 @@ e.g. lf indala clone -r a0000000a0002021 -> this uses .....
void *argtable[] = { void *argtable[] = {
arg_param_begin, arg_param_begin,
arg_lit0("l", "long", "optional - long UID 224 bits"), arg_lit0("l", "long", "optional - long UID 224 bits"),
arg_int0("c", "heden", "<decimal>", "Cardnumber for Heden 2L format"), arg_int0("c", "heden", "<decimal>", "Cardnumber for Heden 2L format"),
arg_strx0("r", "raw", "<hex>", "raw bytes"), arg_strx0("r", "raw", "<hex>", "raw bytes"),
arg_lit0("q", "Q5", "optional - specify writing to Q5/T5555 tag"), arg_lit0("q", "Q5", "optional - specify writing to Q5/T5555 tag"),
arg_int0(NULL, "fc", "<decimal>", "Facility Code (26 bit format)"), arg_int0(NULL, "fc", "<decimal>", "Facility Code (26 bit format)"),
arg_int0(NULL, "cn", "<decimal>", "Cardnumber (26 bit format)"), arg_int0(NULL, "cn", "<decimal>", "Cardnumber (26 bit format)"),
@ -105,30 +105,36 @@ e.g. lf indala clone -r a0000000a0002021 -> this uses .....
_All options has a parameter index, since `-h --help` is added automatic, it will be assigned index 0. _All options has a parameter index, since `-h --help` is added automatic, it will be assigned index 0.
Hence all options you add will start at index 1 and upwards._ Hence all options you add will start at index 1 and upwards._
**Notes:** **Notes:**
**bool option. true if supplied** **bool option. true if supplied**
bool : arg_lit0 ("\<short option\>", "\<long option\>", \["\<format\>",\] \<"description"\>) bool : arg_lit0 ("\<short option\>", "\<long option\>", \<"description"\>)
**integer that is optional** **integer that is optional**
optional integer : arg_int0 ("\<short option\>", "\<long option\>", \["\<format\>",\] \<"description"\>) optional integer : arg_int0 ("\<short option\>", "\<long option\>", "\<format\>", \<"description"\>)
**integer that is required** **integer that is required**
required integer : arg_int1 ("\<short option\>", "\<long option\>", \["\<format\>",\] \<"description"\>) required integer : arg_int1 ("\<short option\>", "\<long option\>", "\<format\>", \<"description"\>)
**String option that is optional and only one instance can be provided** **double that is optional**
optional string : arg_str0("\<short option\>", "\<long option\>", \["\<format\>",\] \<"description"\>) optional double : arg_dbl0 ("\<short option\>", "\<long option\>", "\<format\>", \<"description"\>)
**String option that is required and only one instance can be provided** **double that is required**
required string : arg_str1("\<short option\>", "\<long option\>", \["\<format\>",\] \<"description"\>) required double : arg_dbl1 ("\<short option\>", "\<long option\>", "\<format\>", \<"description"\>)
**String option that is optional and can have up to 250 instances provided** **String option that is optional and only one instance can be provided**
optional string : arg_strx0 ("\<short option\>", "\<long option\>", \["\<format\>",\] \<"description"\>) optional string : arg_str0("\<short option\>", "\<long option\>", "\<format\>", \<"description"\>)
**String option that is required/at least one instance and can have up to 250 instances** **String option that is required and only one instance can be provided**
required string : arg_strx1 ("\<short option\>", "\<long option\>", \["\<format\>",\] \<"description"\>) required string : arg_str1("\<short option\>", "\<long option\>", "\<format\>", \<"description"\>)
**String option that is optional and can have up to 250 instances provided**
optional string : arg_strx0 ("\<short option\>", "\<long option\>", "\<format\>", \<"description"\>)
**String option that is required/at least one instance and can have up to 250 instances**
required string : arg_strx1 ("\<short option\>", "\<long option\>", "\<format\>", \<"description"\>)
**if an option does not have a short or long option, use NULL in its place**
**if an option does not have a short or long option, use NULL in its place**
### show the menu ### show the menu
CLIExecWithReturn(\<context\>, \<command line to parse\>, \<arg/opt table\>, \<return on error\>); CLIExecWithReturn(\<context\>, \<command line to parse\>, \<arg/opt table\>, \<return on error\>);
@ -146,32 +152,32 @@ The parser will format and color and layout as needed.
It will also add the `-h --help` option automatic. It will also add the `-h --help` option automatic.
**bool option** **bool option**
arg_get_lit(\<context\>, \<opt index\>); arg_get_lit(\<context\>, \<opt index\>);
is_long_uid = arg_get_lit(ctx, 1); is_long_uid = arg_get_lit(ctx, 1);
**int option** **int option**
arg_get_int_def(\<context\>, \<opt index\>, \<default value\>); arg_get_int_def(\<context\>, \<opt index\>, \<default value\>);
cardnumber = arg_get_int_def(ctx, 2, -1); cardnumber = arg_get_int_def(ctx, 2, -1);
**hex option** **hex option**
CLIGetHexWithReturn(\<context\>, \<opt index\>, \<store variable\>, \<ptr to stored length\>); CLIGetHexWithReturn(\<context\>, \<opt index\>, \<store variable\>, \<ptr to stored length\>);
?? as an array of uint_8 ?? ?? as an array of uint_8 ??
uint8_t aid[2] = {0}; uint8_t aid[2] = {0};
int aidlen; int aidlen;
CLIGetHexWithReturn(ctx, 2, aid, &aidlen); CLIGetHexWithReturn(ctx, 2, aid, &aidlen);
**hex option returning ???** **hex option returning ???**
uint8_t key[24] = {0}; uint8_t key[24] = {0};
int keylen = 0; int keylen = 0;
int res_klen = CLIParamHexToBuf(arg_get_str(ctx, 3), key, 24, &keylen); int res_klen = CLIParamHexToBuf(arg_get_str(ctx, 3), key, 24, &keylen);
quick test : seems res_keylen == 0 when ok so not key len ??? quick test : seems res_keylen == 0 when ok so not key len ???
**string option** **string option**
CLIGetStrWithReturn(\<context\>,\<opt index\>, \<unsigned char \*\>, \<int \*\>); CLIGetStrWithReturn(\<context\>,\<opt index\>, \<unsigned char \*\>, \<int \*\>);
uint8_t Buffer[100]; uint8_t Buffer[100];