diff --git a/doc/cliparser.md b/doc/cliparser.md index e4cc8e062..0e4691757 100644 --- a/doc/cliparser.md +++ b/doc/cliparser.md @@ -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. -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 --> 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. -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) -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. @@ -42,11 +42,11 @@ It will also add the `-h --help` option automatic. ## design comments -* where possible all options should be lowercase. -* extended options preceded with -- should be short -* options provided directly (without an option identifier) should be avoided. -* -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 '=' +* where possible all options should be lowercase. +* extended options preceded with -- should be short +* options provided directly (without an option identifier) should be avoided. +* -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 '=' e.g. cmd --cn 12345 @@ -82,9 +82,9 @@ CLIParserInit (\, \, \); use -> to separate example and example comment and \\n to separate examples. e.g. lf indala clone -r a0000000a0002021 -> this uses ..... - CLIParserInit(&ctx, "lf indala clone", - "clone INDALA UID to T55x7 or Q5/T5555 tag", - "lf indala clone --heden 888\n" + CLIParserInit(&ctx, "lf indala clone", + "clone INDALA UID to T55x7 or Q5/T5555 tag", + "lf indala clone --heden 888\n" "lf indala clone --fc 123 --cn 1337\n" "lf indala clone -r a0000000a0002021\n" "lf indala clone -l -r 80000001b23523a6c2e31eba3cbee4afb3c6ad1fcf649393928c14e5"); @@ -93,9 +93,9 @@ e.g. lf indala clone -r a0000000a0002021 -> this uses ..... void *argtable[] = { arg_param_begin, - arg_lit0("l", "long", "optional - long UID 224 bits"), - arg_int0("c", "heden", "", "Cardnumber for Heden 2L format"), - arg_strx0("r", "raw", "", "raw bytes"), + arg_lit0("l", "long", "optional - long UID 224 bits"), + arg_int0("c", "heden", "", "Cardnumber for Heden 2L format"), + arg_strx0("r", "raw", "", "raw bytes"), arg_lit0("q", "Q5", "optional - specify writing to Q5/T5555 tag"), arg_int0(NULL, "fc", "", "Facility Code (26 bit format)"), arg_int0(NULL, "cn", "", "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. Hence all options you add will start at index 1 and upwards._ -**Notes:** -**bool option. true if supplied** -bool : arg_lit0 ("\", "\", \["\",\] \<"description"\>) +**Notes:** +**bool option. true if supplied** +bool : arg_lit0 ("\", "\", \<"description"\>) -**integer that is optional** - optional integer : arg_int0 ("\", "\", \["\",\] \<"description"\>) +**integer that is optional** + optional integer : arg_int0 ("\", "\", "\", \<"description"\>) -**integer that is required** - required integer : arg_int1 ("\", "\", \["\",\] \<"description"\>) +**integer that is required** + required integer : arg_int1 ("\", "\", "\", \<"description"\>) -**String option that is optional and only one instance can be provided** - optional string : arg_str0("\", "\", \["\",\] \<"description"\>) +**double that is optional** + optional double : arg_dbl0 ("\", "\", "\", \<"description"\>) -**String option that is required and only one instance can be provided** - required string : arg_str1("\", "\", \["\",\] \<"description"\>) +**double that is required** + required double : arg_dbl1 ("\", "\", "\", \<"description"\>) -**String option that is optional and can have up to 250 instances provided** - optional string : arg_strx0 ("\", "\", \["\",\] \<"description"\>) +**String option that is optional and only one instance can be provided** + optional string : arg_str0("\", "\", "\", \<"description"\>) -**String option that is required/at least one instance and can have up to 250 instances** - required string : arg_strx1 ("\", "\", \["\",\] \<"description"\>) +**String option that is required and only one instance can be provided** + required string : arg_str1("\", "\", "\", \<"description"\>) + +**String option that is optional and can have up to 250 instances provided** + optional string : arg_strx0 ("\", "\", "\", \<"description"\>) + +**String option that is required/at least one instance and can have up to 250 instances** + required string : arg_strx1 ("\", "\", "\", \<"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 CLIExecWithReturn(\, \, \, \); @@ -146,32 +152,32 @@ The parser will format and color and layout as needed. It will also add the `-h --help` option automatic. -**bool option** +**bool option** arg_get_lit(\, \); is_long_uid = arg_get_lit(ctx, 1); -**int option** +**int option** arg_get_int_def(\, \, \); cardnumber = arg_get_int_def(ctx, 2, -1); -**hex option** +**hex option** CLIGetHexWithReturn(\, \, \, \); ?? as an array of uint_8 ?? - + uint8_t aid[2] = {0}; int aidlen; CLIGetHexWithReturn(ctx, 2, aid, &aidlen); -**hex option returning ???** +**hex option returning ???** uint8_t key[24] = {0}; int keylen = 0; 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(\,\, \, \); uint8_t Buffer[100];