{"thread":{"id":"41808","subject":"[PATCH] api-parse-options.txt: document OPT_CMDMODE()","startedAt":"2016-03-24T09:07:01Z","lastAt":"2016-03-25T21:24:43Z","messageCount":9,"participants":["Pranit Bauva","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"281650","messageId":"01020153a7e08100-cf66fc9f-7293-4d8c-98c6-f322721c741f-000000@eu-west-1.amazonses.com","threadId":"41808","inReplyTo":null,"subject":"[PATCH] api-parse-options.txt: document OPT_CMDMODE()","fromName":"Pranit Bauva","fromEmail":"pranit.bauva@gmail.com","sentAt":"2016-03-24T09:07:01Z","receivedAt":"2016-03-24T09:07:01Z","isPatch":true,"sender":{"key":"pranit.bauva@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2959938?v=4"},"body":"OPT_CMDMODE() was introduced in the release of 1.8.5 which makes the use\nof subcommands in the form of arguments a lot cleaner and easier.\n---\n Documentation/technical/api-parse-options.txt | 6 ++++++\n 1 file changed, 6 insertions(+)\n\ndiff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt\nindex 5f0757d..8130d26 100644\n--- a/Documentation/technical/api-parse-options.txt\n+++ b/Documentation/technical/api-parse-options.txt\n@@ -231,6 +231,12 @@ There are some macros to easily define options:\n \tpass the command-line option, which can be specified multiple times,\n \tto another command.\n \n+`OPT_CMDMODE(short, long, &int_var, description, enum_val)`::\n+\tIntroduce an option for subcommands. It is useful when you want to use\n+\tthe command with a particular sub command only and ignore other sub\n+\tcommands it has. It will set `int_var` to enum_val if the argument is\n+\tinvoked.\n+\n \n The last element of the array must be `OPT_END()`.\n \n\n--\nhttps://github.com/git/git/pull/219\n"},{"id":"281678","messageId":"xmqqtwjvamhe.fsf@gitster.mtv.corp.google.com","threadId":"41808","inReplyTo":"01020153a7e08100-cf66fc9f-7293-4d8c-98c6-f322721c741f-000000@eu-west-1.amazonses.com","subject":"Re: [PATCH] api-parse-options.txt: document OPT_CMDMODE()","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-03-24T16:07:09Z","receivedAt":"2016-03-24T16:07:09Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Pranit Bauva writes:\n\n> OPT_CMDMODE() was introduced in the release of 1.8.5 which makes the use\n> of subcommands in the form of arguments a lot cleaner and easier.\n> ---\n\nSign-off?\n\n> Documentation/technical/api-parse-options.txt | 6 ++++++\n> 1 file changed, 6 insertions(+)\n>\n> diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt\n> index 5f0757d..8130d26 100644\n> --- a/Documentation/technical/api-parse-options.txt\n> +++ b/Documentation/technical/api-parse-options.txt\n> @@ -231,6 +231,12 @@ There are some macros to easily define options:\n> \tpass the command-line option, which can be specified multiple times,\n> \tto another command.\n> \n> +`OPT_CMDMODE(short, long, &int_var, description, enum_val)`::\n> +\tIntroduce an option for subcommands. It is useful when you want to use\n> +\tthe command with a particular sub command only and ignore other sub\n> +\tcommands it has. It will set `int_var` to enum_val if the argument is\n> +\tinvoked.\n> +\n\nSorry, but I do not get what \"when you want to... ignore other sub\ncommand it has\" wants to say.\n\nCMDMODE is a mechanism to actively notice when multiple \"operation\nmode\" options that specify mutually incompatible operation modes are\ngiven and error out without the user of parse_options() to implement\nthat mutual exclusion herself. That is, if you have 'add', 'remove'\nand 'edit' operation modes, with OPT_BOOL(), you would have to say:\n\n\toptions[] = {\n OPT_BOOL('a', \"add\", &add, ...),\n OPT_BOOL('r', \"remove\", &remove, ...),\n OPT_BOOL('e', \"edit\", &edit, ...),\n ...\n\t};\n parse_options(ac, av, prefix, options, ...);\n\n\tif (!!add + !!remove + !!edit > 1)\n \tdie(\"at most one add/remove/edit can be used at a time\");\n\n\tif (add)\n \tdo_add();\n\tif (remove)\n \tdo_remove();\n\tif (edit)\n \tdo_edit();\n\nbut with CMDMODE, you can do:\n\n\toptions[] = {\n OPT_BOOL('a', \"add\", &mode, ...),\n OPT_BOOL('r', \"remove\", &mode, ...),\n OPT_BOOL('e', \"edit\", &mode, ...),\n ...\n\t};\n parse_options(ac, av, prefix, options, ...);\n\n switch (mode) {\n case 'a': do_add(); break;\n case 'r': do_remove(); break;\n case 'e': do_edit(); break;\n\t\t...\n\t}\n\nand parse_options notices that \"mode\" is shared across these three\noptions, and implements the mutual-exclusion itself.\n"},{"id":"281685","messageId":"CAFZEwPPhq0HNpJt3mt=AWZw7S3ikEL2XX-SOM8CcRkFie=9vcQ@mail.gmail.com","threadId":"41808","inReplyTo":"xmqqtwjvamhe.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] api-parse-options.txt: document OPT_CMDMODE()","fromName":"Pranit Bauva","fromEmail":"pranit.bauva@gmail.com","sentAt":"2016-03-24T16:55:29Z","receivedAt":"2016-03-24T16:55:29Z","isPatch":true,"sender":{"key":"pranit.bauva@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2959938?v=4"},"body":"On Thu, Mar 24, 2016 at 9:37 PM, Junio C Hamano wrote:\n> Pranit Bauva writes:\n>\n>> OPT_CMDMODE() was introduced in the release of 1.8.5 which makes the use\n>> of subcommands in the form of arguments a lot cleaner and easier.\n>> ---\n>\n> Sign-off?\n\nWill include this.\n\n>> Documentation/technical/api-parse-options.txt | 6 ++++++\n>> 1 file changed, 6 insertions(+)\n>>\n>> diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt\n>> index 5f0757d..8130d26 100644\n>> --- a/Documentation/technical/api-parse-options.txt\n>> +++ b/Documentation/technical/api-parse-options.txt\n>> @@ -231,6 +231,12 @@ There are some macros to easily define options:\n>> pass the command-line option, which can be specified multiple times,\n>> to another command.\n>>\n>> +`OPT_CMDMODE(short, long, &int_var, description, enum_val)`::\n>> + Introduce an option for subcommands. It is useful when you want to use\n>> + the command with a particular sub command only and ignore other sub\n>> + commands it has. It will set `int_var` to enum_val if the argument is\n>> + invoked.\n>> +\n>\n> Sorry, but I do not get what \"when you want to... ignore other sub\n> command it has\" wants to say.\n\nWhat I meant by this statement is that (your example), let's say we\nhave \"add\", \"remove\" and \"edit\" sub commands. Now the user has to pick\nbetween the three. He cannot choose more than 1 from these.\n\n> CMDMODE is a mechanism to actively notice when multiple \"operation\n> mode\" options that specify mutually incompatible operation modes are\n> given and error out without the user of parse_options() to implement\n> that mutual exclusion herself. That is, if you have 'add', 'remove'\n> and 'edit' operation modes, with OPT_BOOL(), you would have to say:\n>\n> options[] = {\n> OPT_BOOL('a', \"add\", &add, ...),\n> OPT_BOOL('r', \"remove\", &remove, ...),\n> OPT_BOOL('e', \"edit\", &edit, ...),\n> ...\n> };\n> parse_options(ac, av, prefix, options, ...);\n>\n> if (!!add + !!remove + !!edit > 1)\n> die(\"at most one add/remove/edit can be used at a time\");\n>\n> if (add)\n> do_add();\n> if (remove)\n> do_remove();\n> if (edit)\n> do_edit();\n>\n> but with CMDMODE, you can do:\n>\n> options[] = {\n> OPT_BOOL('a', \"add\", &mode, ...),\n> OPT_BOOL('r', \"remove\", &mode, ...),\n> OPT_BOOL('e', \"edit\", &mode, ...),\n> ...\n> };\n> parse_options(ac, av, prefix, options, ...);\n>\n> switch (mode) {\n> case 'a': do_add(); break;\n> case 'r': do_remove(); break;\n> case 'e': do_edit(); break;\n> ...\n> }\n>\n> and parse_options notices that \"mode\" is shared across these three\n> options, and implements the mutual-exclusion itself.\n\nThanks for taking time to explain all the details behind it. I can\ninclude these bits in the documentation. :)\n"},{"id":"281688","messageId":"xmqqy49794pc.fsf@gitster.mtv.corp.google.com","threadId":"41808","inReplyTo":"CAFZEwPPhq0HNpJt3mt=AWZw7S3ikEL2XX-SOM8CcRkFie=9vcQ@mail.gmail.com","subject":"Re: [PATCH] api-parse-options.txt: document OPT_CMDMODE()","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-03-24T17:16:31Z","receivedAt":"2016-03-24T17:16:31Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Pranit Bauva writes:\n\n>>> +`OPT_CMDMODE(short, long, &int_var, description, enum_val)`::\n>>> + Introduce an option for subcommands. It is useful when you want to use\n>>> + the command with a particular sub command only and ignore other sub\n>>> + commands it has. It will set `int_var` to enum_val if the argument is\n>>> + invoked.\n>>> +\n>>\n>> Sorry, but I do not get what \"when you want to... ignore other sub\n>> command it has\" wants to say.\n>\n> What I meant by this statement is that (your example), let's say we\n> have \"add\", \"remove\" and \"edit\" sub commands. Now the user has to pick\n> between the three. He cannot choose more than 1 from these.\n\nThen I find the word \"ignore others\" misleading. Quite the\ncontrary, the user has to be aware of the others and not to give\nthem.\n\n\tDefine an \"operating mode\" option, only one of which in the\n\tsame group of \"operating mode\" options that share the same\n\t`int_var` can be given by the user. `enum_val` is set to\n\t`int_var` when the option is used, but an error is reported\n if other \"operating mode\" option has already set its value\n to the same `int_var`.\n\nor something?\n"},{"id":"281701","messageId":"CAFZEwPN=Vo7qR+6zwYhz+rB7Q0a28LRd_zEK-stF_Y4ThYq_4w@mail.gmail.com","threadId":"41808","inReplyTo":"xmqqy49794pc.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] api-parse-options.txt: document OPT_CMDMODE()","fromName":"Pranit Bauva","fromEmail":"pranit.bauva@gmail.com","sentAt":"2016-03-24T18:04:32Z","receivedAt":"2016-03-24T18:04:32Z","isPatch":true,"sender":{"key":"pranit.bauva@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2959938?v=4"},"body":"On Thu, Mar 24, 2016 at 10:46 PM, Junio C Hamano wrote:\n> Pranit Bauva writes:\n>\n>>>> +`OPT_CMDMODE(short, long, &int_var, description, enum_val)`::\n>>>> + Introduce an option for subcommands. It is useful when you want to use\n>>>> + the command with a particular sub command only and ignore other sub\n>>>> + commands it has. It will set `int_var` to enum_val if the argument is\n>>>> + invoked.\n>>>> +\n>>>\n>>> Sorry, but I do not get what \"when you want to... ignore other sub\n>>> command it has\" wants to say.\n>>\n>> What I meant by this statement is that (your example), let's say we\n>> have \"add\", \"remove\" and \"edit\" sub commands. Now the user has to pick\n>> between the three. He cannot choose more than 1 from these.\n>\n> Then I find the word \"ignore others\" misleading. Quite the\n> contrary, the user has to be aware of the others and not to give\n> them.\n>\n> Define an \"operating mode\" option, only one of which in the\n> same group of \"operating mode\" options that share the same\n> `int_var` can be given by the user. `enum_val` is set to\n> `int_var` when the option is used, but an error is reported\n> if other \"operating mode\" option has already set its value\n> to the same `int_var`.\n>\n> or something?\n\nSeems a crystal clear explanation to me. Thanks. I was unaware that it\nthrows an error.\n"},{"id":"281868","messageId":"01020153af24cfbc-a145ad2b-0cc2-4378-bce9-6b1f68251ce8-000000@eu-west-1.amazonses.com","threadId":"41808","inReplyTo":"01020153a7e08100-cf66fc9f-7293-4d8c-98c6-f322721c741f-000000@eu-west-1.amazonses.com","subject":"[PATCH v2] api-parse-options.txt: document OPT_CMDMODE()","fromName":"Pranit Bauva","fromEmail":"pranit.bauva@gmail.com","sentAt":"2016-03-25T18:58:58Z","receivedAt":"2016-03-25T18:58:58Z","isPatch":true,"sender":{"key":"pranit.bauva@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2959938?v=4"},"body":"OPT_CMDMODE mechanism was introduced in the release of 1.8.5 to actively\nnotice when multiple \"operation mode\" options that specify mutually\nincompatible operation modes are given.\n\nSigned-off-by: Pranit Bauva \n---\n Documentation/technical/api-parse-options.txt | 7 +++++++\n 1 file changed, 7 insertions(+)\n\ndiff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt\nindex 5f0757d..695bd4b 100644\n--- a/Documentation/technical/api-parse-options.txt\n+++ b/Documentation/technical/api-parse-options.txt\n@@ -231,6 +231,13 @@ There are some macros to easily define options:\n \tpass the command-line option, which can be specified multiple times,\n \tto another command.\n \n+`OPT_CMDMODE(short, long, &int_var, description, enum_val)`::\n+\tDefine an \"operation mode\" option, only one of which in the same\n+\tgroup of \"operating mode\" options that share the same `int_var`\n+\tcan be given by the user. `enum_val` is set to `int_var` when the\n+\toption is used, but an error is reported if other \"operating mode\"\n+\toption has already set its value to the same `int_var`.\n+\n \n The last element of the array must be `OPT_END()`.\n \n\n--\nhttps://github.com/git/git/pull/219\n"},{"id":"281870","messageId":"CAFZEwPOaqZmE4oUy7PWDNv_Qvz+hPgZH2YO6VKk5XUtGYL-ziQ@mail.gmail.com","threadId":"41808","inReplyTo":"01020153af24cfbc-a145ad2b-0cc2-4378-bce9-6b1f68251ce8-000000@eu-west-1.amazonses.com","subject":"Re: [PATCH v2] api-parse-options.txt: document OPT_CMDMODE()","fromName":"Pranit Bauva","fromEmail":"pranit.bauva@gmail.com","sentAt":"2016-03-25T19:08:44Z","receivedAt":"2016-03-25T19:08:44Z","isPatch":true,"sender":{"key":"pranit.bauva@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2959938?v=4"},"body":"I have used bits from your email. I forgot to add \"Helped-by: Junio C\nHamano \" . Could you squash it in?\n\nOn Sat, Mar 26, 2016 at 12:28 AM, Pranit Bauva wrote:\n> OPT_CMDMODE mechanism was introduced in the release of 1.8.5 to actively\n> notice when multiple \"operation mode\" options that specify mutually\n> incompatible operation modes are given.\n>\n> Signed-off-by: Pranit Bauva \n> ---\n> Documentation/technical/api-parse-options.txt | 7 +++++++\n> 1 file changed, 7 insertions(+)\n>\n> diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt\n> index 5f0757d..695bd4b 100644\n> --- a/Documentation/technical/api-parse-options.txt\n> +++ b/Documentation/technical/api-parse-options.txt\n> @@ -231,6 +231,13 @@ There are some macros to easily define options:\n> pass the command-line option, which can be specified multiple times,\n> to another command.\n>\n> +`OPT_CMDMODE(short, long, &int_var, description, enum_val)`::\n> + Define an \"operation mode\" option, only one of which in the same\n> + group of \"operating mode\" options that share the same `int_var`\n> + can be given by the user. `enum_val` is set to `int_var` when the\n> + option is used, but an error is reported if other \"operating mode\"\n> + option has already set its value to the same `int_var`.\n> +\n>\n> The last element of the array must be `OPT_END()`.\n>\n>\n> --\n> https://github.com/git/git/pull/219\n> --\n> To unsubscribe from this list: send the line \"unsubscribe git\" in\n> the body of a message to majordomo@vger.kernel.org\n> More majordomo info at http://vger.kernel.org/majordomo-info.html\n"},{"id":"281874","messageId":"01020153af6a22a0-88286f19-ad5c-4a4e-9571-8905ea7dd731-000000@eu-west-1.amazonses.com","threadId":"41808","inReplyTo":"01020153af24cfbc-a145ad2b-0cc2-4378-bce9-6b1f68251ce8-000000@eu-west-1.amazonses.com","subject":"[PATCH v3] api-parse-options.txt: document OPT_CMDMODE()","fromName":"Pranit Bauva","fromEmail":"pranit.bauva@gmail.com","sentAt":"2016-03-25T20:14:41Z","receivedAt":"2016-03-25T20:14:41Z","isPatch":true,"sender":{"key":"pranit.bauva@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2959938?v=4"},"body":"OPT_CMDMODE mechanism was introduced in the release of 1.8.5 to actively\nnotice when multiple \"operation mode\" options that specify mutually\nincompatible operation modes are given.\n\nHelped-by: Junio C Hamano \nSigned-off-by: Pranit Bauva \n---\n Documentation/technical/api-parse-options.txt | 7 +++++++\n 1 file changed, 7 insertions(+)\n\ndiff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt\nindex 5f0757d..695bd4b 100644\n--- a/Documentation/technical/api-parse-options.txt\n+++ b/Documentation/technical/api-parse-options.txt\n@@ -231,6 +231,13 @@ There are some macros to easily define options:\n \tpass the command-line option, which can be specified multiple times,\n \tto another command.\n \n+`OPT_CMDMODE(short, long, &int_var, description, enum_val)`::\n+\tDefine an \"operation mode\" option, only one of which in the same\n+\tgroup of \"operating mode\" options that share the same `int_var`\n+\tcan be given by the user. `enum_val` is set to `int_var` when the\n+\toption is used, but an error is reported if other \"operating mode\"\n+\toption has already set its value to the same `int_var`.\n+\n \n The last element of the array must be `OPT_END()`.\n \n\n--\nhttps://github.com/git/git/pull/219\n"},{"id":"281878","messageId":"xmqqvb4a1c9w.fsf@gitster.mtv.corp.google.com","threadId":"41808","inReplyTo":"CAFZEwPOaqZmE4oUy7PWDNv_Qvz+hPgZH2YO6VKk5XUtGYL-ziQ@mail.gmail.com","subject":"Re: [PATCH v2] api-parse-options.txt: document OPT_CMDMODE()","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-03-25T21:24:43Z","receivedAt":"2016-03-25T21:24:43Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Pranit Bauva writes:\n\n> I have used bits from your email. I forgot to add \"Helped-by: Junio C\n> Hamano \" . Could you squash it in?\n\nIt's OK to omit such a credit for a patch this small. After\nunderstanding the issues, you would have written essentially the\nsame thing yourself.\n\nThanks, queued v2 already.\n"}]}