* Inconsistencies in handling command flags: `--flag=value` different than `--flag value` @ 2020-04-24 12:53 Ciprian Dorin Craciun 2020-04-27 17:53 ` David Bremner 0 siblings, 1 reply; 19+ messages in thread From: Ciprian Dorin Craciun @ 2020-04-24 12:53 UTC (permalink / raw) To: notmuch [Again sorry for double reporting. BTW, where should I search for previous bugs? I've currently tried the mailing list archive.] Trying to play with `notmuch` from a wrapper, I've stumbled upon the following command line flags handling bug: ~~~~ notmuch show --format json --entire-thread true --body false -- 'ciprian@volution.ro' notmuch show --format json --entire-thread true --body=false -- 'ciprian@volution.ro' #=> yields nothing notmuch show --format json --entire-thread=true --body false -- 'ciprian@volution.ro' #=> yields some emails notmuch show --format json --entire-thread=true --body=false -- 'ciprian@volution.ro' #=> yields lots of emails ~~~~ I would expect that `--flag value` and `--flag=value` are equivalent, at least for the options that the manual states `--flag=(true|false)`. However based on the previous experiments it seems that using anything except `--flag=value` yields inconsistent results. Hope it helps, Ciprian. ^ permalink raw reply [flat|nested] 19+ messages in thread
* Re: Inconsistencies in handling command flags: `--flag=value` different than `--flag value` 2020-04-24 12:53 Inconsistencies in handling command flags: `--flag=value` different than `--flag value` Ciprian Dorin Craciun @ 2020-04-27 17:53 ` David Bremner 2020-04-27 18:02 ` Daniel Kahn Gillmor 0 siblings, 1 reply; 19+ messages in thread From: David Bremner @ 2020-04-27 17:53 UTC (permalink / raw) To: Ciprian Dorin Craciun, notmuch Ciprian Dorin Craciun <ciprian.craciun@gmail.com> writes: > [Again sorry for double reporting. BTW, where should I search for > previous bugs? I've currently tried the mailing list archive.] Another option is https://nmbug.notmuchmail.org/status This is just pointers into the mailing archive, but triaged. > > Trying to play with `notmuch` from a wrapper, I've stumbled upon the > following command line flags handling bug: > > ~~~~ > notmuch show --format json --entire-thread true --body false -- > 'ciprian@volution.ro' > notmuch show --format json --entire-thread true --body=false -- > 'ciprian@volution.ro' Quoting notmuch(1) OPTION SYNTAX All options accepting an argument can be used with '=' or ':' as a separator. For the cases where it's not ambiguous (in particular excluding boolean options), a space can also be used. So what you are seeing is a side effect of "--entire-thread true" not being supported syntax. You can see what's happening with NOTMUCH_DEBUG_QUERY=t notmuch show --format json --entire-thread true djkldsfjkl the "true" is considered the first search term. In your example you could just delete the "true" to switch on the option. ^ permalink raw reply [flat|nested] 19+ messages in thread
* Re: Inconsistencies in handling command flags: `--flag=value` different than `--flag value` 2020-04-27 17:53 ` David Bremner @ 2020-04-27 18:02 ` Daniel Kahn Gillmor 2020-04-27 18:20 ` Tomi Ollila 0 siblings, 1 reply; 19+ messages in thread From: Daniel Kahn Gillmor @ 2020-04-27 18:02 UTC (permalink / raw) To: David Bremner, Ciprian Dorin Craciun, notmuch [-- Attachment #1.1: Type: text/plain, Size: 1058 bytes --] On Mon 2020-04-27 14:53:07 -0300, David Bremner wrote: > Quoting notmuch(1) > > OPTION SYNTAX > All options accepting an argument can be used with '=' > or ':' as a separator. For the cases where it's not ambiguous > (in particular excluding boolean options), a space can also be > used. This is a pretty twisty way to say what we mean. Are there other cases besides boolean options? If there are, perhaps it'd be clearer to say something like this for the last sentence: Except for boolean options and other potential ambiguous cases, a space can also be used as a separator. If there aren't, we could say: Except for boolean options (which would be ambiguous), a space can also be used as a separator. Alternately, we could deprecate using whitespace for all options, produce explicit warnings to stderr when whitespace appears on the next release, remove the suggestion to use a whitespace separator from the documentation, and eventually phase it out entirely in some future release. --dkg [-- Attachment #1.2: signature.asc --] [-- Type: application/pgp-signature, Size: 227 bytes --] [-- Attachment #2: Type: text/plain, Size: 0 bytes --] ^ permalink raw reply [flat|nested] 19+ messages in thread
* Re: Inconsistencies in handling command flags: `--flag=value` different than `--flag value` 2020-04-27 18:02 ` Daniel Kahn Gillmor @ 2020-04-27 18:20 ` Tomi Ollila 2020-04-27 19:21 ` Ciprian Dorin Craciun 0 siblings, 1 reply; 19+ messages in thread From: Tomi Ollila @ 2020-04-27 18:20 UTC (permalink / raw) To: Daniel Kahn Gillmor, David Bremner, Ciprian Dorin Craciun, notmuch On Mon, Apr 27 2020, Daniel Kahn Gillmor wrote: > On Mon 2020-04-27 14:53:07 -0300, David Bremner wrote: >> Quoting notmuch(1) >> >> OPTION SYNTAX >> All options accepting an argument can be used with '=' >> or ':' as a separator. For the cases where it's not ambiguous >> (in particular excluding boolean options), a space can also be >> used. > > This is a pretty twisty way to say what we mean. Are there other cases > besides boolean options? If there are, perhaps it'd be clearer to say > something like this for the last sentence: > > Except for boolean options and other potential ambiguous cases, a > space can also be used as a separator. > > If there aren't, we could say: > > Except for boolean options (which would be ambiguous), a space can > also be used as a separator. > > Alternately, we could deprecate using whitespace for all options, > produce explicit warnings to stderr when whitespace appears on the next was it so, that originally we did not support whitespace, but David added that in some commit... > release, remove the suggestion to use a whitespace separator from the > documentation, and eventually phase it out entirely in some future > release. Alternatively we could check that next arg is (case-insensitively) (subset of) 'true', 'false', 'yes', 'no', '0', '1', 't', 'nil' (but not tpyoes of these ;) and in that case have that as an option value... ... would that work better for human user who just wants to be fluent on command line -- frontends can then always use = and option values... > --dkg Tomi ^ permalink raw reply [flat|nested] 19+ messages in thread
* Re: Inconsistencies in handling command flags: `--flag=value` different than `--flag value` 2020-04-27 18:20 ` Tomi Ollila @ 2020-04-27 19:21 ` Ciprian Dorin Craciun 2020-04-29 2:16 ` Daniel Kahn Gillmor 0 siblings, 1 reply; 19+ messages in thread From: Ciprian Dorin Craciun @ 2020-04-27 19:21 UTC (permalink / raw) To: Tomi Ollila; +Cc: notmuch, Daniel Kahn Gillmor On Mon, Apr 27, 2020 at 9:21 PM Tomi Ollila <tomi.ollila@iki.fi> wrote: > > On Mon 2020-04-27 14:53:07 -0300, David Bremner wrote: > >> Quoting notmuch(1) > >> > >> OPTION SYNTAX > >> All options accepting an argument can be used with '=' > >> or ':' as a separator. For the cases where it's not ambiguous > >> (in particular excluding boolean options), a space can also be > >> used. I definitively skipped over that warning, mainly because I was reading the man-page for the specific command (i.e. `notmuch-search`, etc.) that don't feature that warning. Please note that I understand "why" I get this behavior, and definitively I agree that it's my fault. However my initial report was intended to find a way that new users don't shoot themselves in the foot, especially since many will use `notmuch` from a script, and sometimes they don't thoroughly check the arguments passed by the user. > > Alternately, we could deprecate using whitespace for all options, > > produce explicit warnings to stderr when whitespace appears on the next > > was it so, that originally we did not support whitespace, but David > added that in some commit... From a "correctness" point of view, this would be the best approach. However I think it could be too late to introduce it, and it would break too many integrations. > > release, remove the suggestion to use a whitespace separator from the > > documentation, and eventually phase it out entirely in some future > > release. > > Alternatively we could check that next arg is (case-insensitively) > (subset of) 'true', 'false', 'yes', 'no', '0', '1', 't', 'nil' > (but not tpyoes of these ;) and in that case have that as an option > value... This would be perhaps the best approach. However I don't think it would solve the issues for integrators that would not see these warnings in the logs, until it is too late. > ... would that work better for human user who just wants to be > fluent on command line -- frontends can then always use = and option > values... Perhaps there could be an additional option (either on the command line or in the configuration) that would apply "strict" checking, and not letting any other form except `--argument=value`, including the boolean flags, and failing loudly. I think this third option would enable much safer integrations. (BTW, this "strict" option could also apply to the parsing of the search terms, which most of the time are under the control of the end user.) Ciprian. ^ permalink raw reply [flat|nested] 19+ messages in thread
* Re: Inconsistencies in handling command flags: `--flag=value` different than `--flag value` 2020-04-27 19:21 ` Ciprian Dorin Craciun @ 2020-04-29 2:16 ` Daniel Kahn Gillmor 2020-04-29 14:18 ` Tomi Ollila 2020-04-29 15:33 ` Jameson Graef Rollins 0 siblings, 2 replies; 19+ messages in thread From: Daniel Kahn Gillmor @ 2020-04-29 2:16 UTC (permalink / raw) To: Ciprian Dorin Craciun, Tomi Ollila; +Cc: notmuch [-- Attachment #1.1: Type: text/plain, Size: 2801 bytes --] On Mon 2020-04-27 22:21:36 +0300, Ciprian Dorin Craciun wrote: > On Mon, Apr 27, 2020 at 9:21 PM Tomi Ollila <tomi.ollila@iki.fi> wrote: >>> [dkg wrote:] >>> release, remove the suggestion to use a whitespace separator from the >>> documentation, and eventually phase it out entirely in some future >>> release. >> >> Alternatively we could check that next arg is (case-insensitively) >> (subset of) 'true', 'false', 'yes', 'no', '0', '1', 't', 'nil' >> (but not tpyoes of these ;) and in that case have that as an option >> value... > > This would be perhaps the best approach. However I don't think it > would solve the issues for integrators that would not see these > warnings in the logs, until it is too late. this looks really ugly to me, in that some legitimate queries (e.g. those that include terms like "true" or "1") might not be accessible, unless the user supplies --booloption=true instead of --booloption. I mean, these are all slightly idiosyncratic corner cases, but this particular corner case looks super ugly and hard to explain to me. i'm trying to imagine writing some example text that explains it for the man page, and it comes out horribly complex! If we can't explain it succinctly in the manpage, should we be implementing it? > Perhaps there could be an additional option (either on the command > line or in the configuration) that would apply "strict" checking, and > not letting any other form except `--argument=value`, including the > boolean flags, and failing loudly. > > I think this third option would enable much safer integrations. > > (BTW, this "strict" option could also apply to the parsing of the > search terms, which most of the time are under the control of the end > user.) I've spent many years helping to maintain GnuPG now, and i'm pretty wary of having contextually different modes of argument parsing and interacting/intersecting arguments. It also leads to some weird ambiguities: if --strict is supplied on the command line, then does it need to be first on the command line? or could parsing the command line turn out different if you tack on --strict at the end? Seems like we'd be injecting additional idiosyncracies to chase after the first. One final way we could normalize everything and make it less idiosyncratic, with shorter, simpler man pages: deprecate and then drop the --booloption/--no-booloption mechanisms, requiring --booloption=true or --booloption=false instead. Once they're dropped, allow whitespace between "--booloption true" and "--booloption false" just like every other type of option. in case it's not clear: I believe that "we have succinct and yet complete man pages" is a convenient shorthand for "have we made this command-line program behave in an understandable/usable way?" --dkg [-- Attachment #1.2: signature.asc --] [-- Type: application/pgp-signature, Size: 227 bytes --] [-- Attachment #2: Type: text/plain, Size: 0 bytes --] ^ permalink raw reply [flat|nested] 19+ messages in thread
* Re: Inconsistencies in handling command flags: `--flag=value` different than `--flag value` 2020-04-29 2:16 ` Daniel Kahn Gillmor @ 2020-04-29 14:18 ` Tomi Ollila 2020-04-29 15:39 ` David Bremner 2020-04-29 15:33 ` Jameson Graef Rollins 1 sibling, 1 reply; 19+ messages in thread From: Tomi Ollila @ 2020-04-29 14:18 UTC (permalink / raw) To: Daniel Kahn Gillmor, Ciprian Dorin Craciun; +Cc: notmuch On Tue, Apr 28 2020, Daniel Kahn Gillmor wrote: > > One final way we could normalize everything and make it less > idiosyncratic, with shorter, simpler man pages: deprecate and then drop > the --booloption/--no-booloption mechanisms, requiring --booloption=true > or --booloption=false instead. Once they're dropped, allow whitespace > between "--booloption true" and "--booloption false" just like every > other type of option. I must say, being it perhaps slightly inconvenient to the user, that this is IMO the best option, and just allowing 'true' and 'false' (case-sensitively). Least chance to work how used did not expected... > in case it's not clear: I believe that "we have succinct and yet > complete man pages" is a convenient shorthand for "have we made this > command-line program behave in an understandable/usable way?" Sounds/looks like reasonable expectation... > > --dkg Tomi ^ permalink raw reply [flat|nested] 19+ messages in thread
* Re: Inconsistencies in handling command flags: `--flag=value` different than `--flag value` 2020-04-29 14:18 ` Tomi Ollila @ 2020-04-29 15:39 ` David Bremner 2020-04-29 15:45 ` Jameson Graef Rollins 2020-04-29 15:59 ` Inconsistencies in handling command flags: `--flag=value` different than `--flag value` Ciprian Dorin Craciun 0 siblings, 2 replies; 19+ messages in thread From: David Bremner @ 2020-04-29 15:39 UTC (permalink / raw) To: Daniel Kahn Gillmor, Jani Nikula; +Cc: notmuch Tomi Ollila <tomi.ollila@iki.fi> writes: > On Tue, Apr 28 2020, Daniel Kahn Gillmor wrote: > >> >> One final way we could normalize everything and make it less >> idiosyncratic, with shorter, simpler man pages: deprecate and then drop >> the --booloption/--no-booloption mechanisms, requiring --booloption=true >> or --booloption=false instead. Once they're dropped, allow whitespace >> between "--booloption true" and "--booloption false" just like every >> other type of option. > > I must say, being it perhaps slightly inconvenient to the user, that > this is IMO the best option, and just allowing 'true' and 'false' > (case-sensitively). Least chance to work how used did not expected... > I guess I'm a bit leery of removing UI features that presumably at least some people rely on. It's pretty upsetting to have sofware break one's muscle memory. d ^ permalink raw reply [flat|nested] 19+ messages in thread
* Re: Inconsistencies in handling command flags: `--flag=value` different than `--flag value` 2020-04-29 15:39 ` David Bremner @ 2020-04-29 15:45 ` Jameson Graef Rollins 2020-04-29 16:28 ` David Bremner 2020-05-05 18:28 ` Carl Worth 2020-04-29 15:59 ` Inconsistencies in handling command flags: `--flag=value` different than `--flag value` Ciprian Dorin Craciun 1 sibling, 2 replies; 19+ messages in thread From: Jameson Graef Rollins @ 2020-04-29 15:45 UTC (permalink / raw) To: David Bremner, Daniel Kahn Gillmor, Jani Nikula; +Cc: notmuch On Wed, Apr 29 2020, David Bremner <david@tethera.net> wrote: > I guess I'm a bit leery of removing UI features that presumably at least > some people rely on. It's pretty upsetting to have sofware break one's > muscle memory. I dare say there are few people that have muscle memory for the notmuch command line (especially for notmuch show), and fewer that aren't themselves developers... ^ permalink raw reply [flat|nested] 19+ messages in thread
* Re: Inconsistencies in handling command flags: `--flag=value` different than `--flag value` 2020-04-29 15:45 ` Jameson Graef Rollins @ 2020-04-29 16:28 ` David Bremner 2020-05-05 18:28 ` Carl Worth 1 sibling, 0 replies; 19+ messages in thread From: David Bremner @ 2020-04-29 16:28 UTC (permalink / raw) To: Jameson Graef Rollins, Daniel Kahn Gillmor, Jani Nikula; +Cc: notmuch Jameson Graef Rollins <jrollins@caltech.edu> writes: > On Wed, Apr 29 2020, David Bremner <david@tethera.net> wrote: >> I guess I'm a bit leery of removing UI features that presumably at least >> some people rely on. It's pretty upsetting to have sofware break one's >> muscle memory. > > I dare say there are few people that have muscle memory for the notmuch > command line (especially for notmuch show), and fewer that aren't > themselves developers... Yep. But those are the users I care the most about. d ^ permalink raw reply [flat|nested] 19+ messages in thread
* Re: Inconsistencies in handling command flags: `--flag=value` different than `--flag value` 2020-04-29 15:45 ` Jameson Graef Rollins 2020-04-29 16:28 ` David Bremner @ 2020-05-05 18:28 ` Carl Worth 2020-05-07 19:26 ` [PATCH] notmuch(1): clarify documentation about --option/value separators Daniel Kahn Gillmor 1 sibling, 1 reply; 19+ messages in thread From: Carl Worth @ 2020-05-05 18:28 UTC (permalink / raw) To: Jameson Graef Rollins, David Bremner, Daniel Kahn Gillmor, Jani Nikula Cc: notmuch [-- Attachment #1.1: Type: text/plain, Size: 1722 bytes --] On Wed, Apr 29 2020, Jameson Graef Rollins wrote: > I dare say there are few people that have muscle memory for the notmuch > command line (especially for notmuch show), and fewer that aren't > themselves developers... Here, the concern isn't just "muscle memory" (forcing users to learn how to retype commands at the command line) but also that users can have developed scripts that call notmuch, and we would need to have an extremely significant reason to break those. And the notmuch CLI, from the beginning, was intentionally designed to be comfortable for users to use directly (by typing at an interactive shell), and for users to also incorporate into various scripts. And even if they _are_ developers, they don't deserve to have their environments broken either. That said, it is unfortunate that some confusion has crept into the API. I have to admit that I do not understand what this sentence of the documentation means: For the cases where it's not ambiguous (in particular excluding boolean options), a space can also be used. What are the possible cases where it could be ambiguous? I'm personally opposed to adding any new option like --strict that changes how command-line options are parsed. I'm also opposed to renaming any of our existing command-line options. It seems clear we could at least fix the wording of the above documentation to make it clear that a space separator cannot be used for Boolean options. The only further change that could possibly make sense (to improve consistency) would be to back out support for using a space separator for _any_ options. But that introduces all the opportunities to break users' environments, so it's probably a non-starter as well. -Carl [-- Attachment #1.2: signature.asc --] [-- Type: application/pgp-signature, Size: 832 bytes --] [-- Attachment #2: Type: text/plain, Size: 0 bytes --] ^ permalink raw reply [flat|nested] 19+ messages in thread
* [PATCH] notmuch(1): clarify documentation about --option/value separators 2020-05-05 18:28 ` Carl Worth @ 2020-05-07 19:26 ` Daniel Kahn Gillmor 2020-05-07 23:40 ` Carl Worth 0 siblings, 1 reply; 19+ messages in thread From: Daniel Kahn Gillmor @ 2020-05-07 19:26 UTC (permalink / raw) To: Notmuch Mail id:CA+Tk8fzRiqxWpd=r8=DRvEewNZXUZgD7MKyRLB1A=R-LxxGEZw@mail.gmail.com started a thread of discussion that showed that the cli's current idiosyncrasies around dealing with boolean options were not understandable. This attempts to improve the documentation at least (actual changes to the API might be better, but have not reached consensus). Note that no one in the discussion thread identified any other (non-boolean) command-line options that cannot use space as a separator. If such an option is identified (or introduced in the future), it should be added explicitly to this part of the manual. Signed-off-by: Daniel Kahn Gillmor <dkg@fifthhorseman.net> --- doc/man1/notmuch.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/man1/notmuch.rst b/doc/man1/notmuch.rst index d2cd8da5..3dcc646c 100644 --- a/doc/man1/notmuch.rst +++ b/doc/man1/notmuch.rst @@ -128,9 +128,9 @@ OPTION SYNTAX ------------- All options accepting an argument can be used with '=' or ':' as a -separator. For the cases where it's not ambiguous (in particular -excluding boolean options), a space can also be used. The following -are all equivalent: +separator. Except for boolean options (wihch would be ambiguous), a +space can also be used as a separator. The following are all +equivalent: :: -- 2.26.2 ^ permalink raw reply related [flat|nested] 19+ messages in thread
* Re: [PATCH] notmuch(1): clarify documentation about --option/value separators 2020-05-07 19:26 ` [PATCH] notmuch(1): clarify documentation about --option/value separators Daniel Kahn Gillmor @ 2020-05-07 23:40 ` Carl Worth 2020-05-08 12:01 ` David Bremner 2020-05-08 16:06 ` Daniel Kahn Gillmor 0 siblings, 2 replies; 19+ messages in thread From: Carl Worth @ 2020-05-07 23:40 UTC (permalink / raw) To: Daniel Kahn Gillmor, Notmuch Mail [-- Attachment #1.1: Type: text/plain, Size: 364 bytes --] On Thu, May 07 2020, Daniel Kahn Gillmor wrote: > +separator. Except for boolean options (wihch would be ambiguous), a Misspelling of "which". And while I'm here, strictly speaking Boolean is generally capitalized in English, (being one of those adjectives that is derived from a proper noun). Otherwise, this looks like a good improvement to me. Thanks! -Carl [-- Attachment #1.2: signature.asc --] [-- Type: application/pgp-signature, Size: 832 bytes --] [-- Attachment #2: Type: text/plain, Size: 0 bytes --] ^ permalink raw reply [flat|nested] 19+ messages in thread
* Re: [PATCH] notmuch(1): clarify documentation about --option/value separators 2020-05-07 23:40 ` Carl Worth @ 2020-05-08 12:01 ` David Bremner 2020-05-08 16:06 ` Daniel Kahn Gillmor 1 sibling, 0 replies; 19+ messages in thread From: David Bremner @ 2020-05-08 12:01 UTC (permalink / raw) To: Carl Worth, Daniel Kahn Gillmor, Notmuch Mail Carl Worth <cworth@cworth.org> writes: > On Thu, May 07 2020, Daniel Kahn Gillmor wrote: >> +separator. Except for boolean options (wihch would be ambiguous), a > > Misspelling of "which". And while I'm here, strictly speaking Boolean is > generally capitalized in English, (being one of those adjectives that is > derived from a proper noun). I pushed this to master with s/wihch/which/. I left boolean for a future patch since there are around 7 occurences in the docs, currently all lower case. d ^ permalink raw reply [flat|nested] 19+ messages in thread
* Re: [PATCH] notmuch(1): clarify documentation about --option/value separators 2020-05-07 23:40 ` Carl Worth 2020-05-08 12:01 ` David Bremner @ 2020-05-08 16:06 ` Daniel Kahn Gillmor 1 sibling, 0 replies; 19+ messages in thread From: Daniel Kahn Gillmor @ 2020-05-08 16:06 UTC (permalink / raw) To: Carl Worth, Notmuch Mail [-- Attachment #1.1: Type: text/plain, Size: 829 bytes --] On Thu 2020-05-07 16:40:26 -0700, Carl Worth wrote: > On Thu, May 07 2020, Daniel Kahn Gillmor wrote: >> +separator. Except for boolean options (wihch would be ambiguous), a > > Misspelling of "which". And while I'm here, strictly speaking Boolean is > generally capitalized in English, (being one of those adjectives that is > derived from a proper noun). > > Otherwise, this looks like a good improvement to me. Thanks! Thanks for catching the "which" misspelling, which should obviously be fixed if/when the patch is applied. notmuch-search-terms(7) contains both capitalized and non-capitalized spellings of "boolean". I welcome capitalization cleanup for this over the whole codebase, and hope that a decision about this particular nit-pick isn't cause for delay of an otherwise uncontroversial improvement. --dkg [-- Attachment #1.2: signature.asc --] [-- Type: application/pgp-signature, Size: 227 bytes --] [-- Attachment #2: Type: text/plain, Size: 0 bytes --] ^ permalink raw reply [flat|nested] 19+ messages in thread
* Re: Inconsistencies in handling command flags: `--flag=value` different than `--flag value` 2020-04-29 15:39 ` David Bremner 2020-04-29 15:45 ` Jameson Graef Rollins @ 2020-04-29 15:59 ` Ciprian Dorin Craciun 2020-04-29 16:07 ` Jameson Graef Rollins 1 sibling, 1 reply; 19+ messages in thread From: Ciprian Dorin Craciun @ 2020-04-29 15:59 UTC (permalink / raw) To: David Bremner; +Cc: notmuch, Daniel Kahn Gillmor On Wed, Apr 29, 2020 at 6:39 PM David Bremner <david@tethera.net> wrote: > I guess I'm a bit leery of removing UI features that presumably at least > some people rely on. It's pretty upsetting to have sofware break one's > muscle memory. I think there are two complete different use-cases for the `notmuch` binary: * a simple CLI to query the database, in which case the current flags seem OK; * a "poor-mans" API to query the database, more bellow; (I know there already exists an `libnotmuch` API accessible in many programming languages. However for prototyping, and even for safety and robustness, when performance isn't an issue, I find the tool-based approach much more resilient.) Now about the "API" use-case, I assume that at the moment many users have already integrated `notmuch` as it is with the current flags and behaviour. Thus I agree that changing any flags in backward incompatible way would make a lot of people unhappy, and will generate perhaps quite a bit of "customer support". :) However, even with my `--strict` argument, I was perhaps leaning toward adding a more API-friendly command line parser, that would basically only take arguments in the form `--flag=value`, anything else being considered a search term, and anything not a flag but before a single `--` should be considered an error. Regarding the `--boolean` vs `--no-boolean` it does solve the strictness problem, however it makes the life of script developers quite hard, as now he has a `case` or `if/then/else`. Therefore I would say that `--flag=value` is the best option as it can be simply written as `--flag={FLAG:-true}` or in Python for example `"--flag=%s" % _flag`. Thinking even further uppon this, perhaps an even simpler idea would be to provide a new command, like for example `notmuch api` that takes on `stdin` a JSON with a specific format and does its job. Ciprian. ^ permalink raw reply [flat|nested] 19+ messages in thread
* Re: Inconsistencies in handling command flags: `--flag=value` different than `--flag value` 2020-04-29 15:59 ` Inconsistencies in handling command flags: `--flag=value` different than `--flag value` Ciprian Dorin Craciun @ 2020-04-29 16:07 ` Jameson Graef Rollins 0 siblings, 0 replies; 19+ messages in thread From: Jameson Graef Rollins @ 2020-04-29 16:07 UTC (permalink / raw) To: Ciprian Dorin Craciun, David Bremner; +Cc: notmuch, Daniel Kahn Gillmor On Wed, Apr 29 2020, Ciprian Dorin Craciun <ciprian.craciun@gmail.com> wrote: > I think there are two complete different use-cases for the `notmuch` binary: > * a simple CLI to query the database, in which case the current flags seem OK; > * a "poor-mans" API to query the database, more bellow; > > (I know there already exists an `libnotmuch` API accessible in many > programming languages. However for prototyping, and even for safety > and robustness, when performance isn't an issue, I find the tool-based > approach much more resilient.) > > Now about the "API" use-case, I assume that at the moment many users > have already integrated `notmuch` as it is with the current flags and > behaviour. Thus I agree that changing any flags in backward > incompatible way would make a lot of people unhappy, and will generate > perhaps quite a bit of "customer support". :) This is a good point. The CLI might be "poor", but important apps like notmuch-emacs are using them, so we should be careful about changing the interface. > Regarding the `--boolean` vs `--no-boolean` it does solve the > strictness problem, however it makes the life of script developers > quite hard, as now he has a `case` or `if/then/else`. Therefore I > would say that `--flag=value` is the best option as it can be simply > written as `--flag={FLAG:-true}` or in Python for example `"--flag=%s" > % _flag`. Also a good point. I guess the --flag=value interface is a safer/easier one to converge on. > Thinking even further uppon this, perhaps an even simpler idea would > be to provide a new command, like for example `notmuch api` that takes > on `stdin` a JSON with a specific format and does its job. This actually sounds like a pretty good idea... jamie. ^ permalink raw reply [flat|nested] 19+ messages in thread
* Re: Inconsistencies in handling command flags: `--flag=value` different than `--flag value` 2020-04-29 2:16 ` Daniel Kahn Gillmor 2020-04-29 14:18 ` Tomi Ollila @ 2020-04-29 15:33 ` Jameson Graef Rollins 2020-04-30 16:59 ` Daniel Kahn Gillmor 1 sibling, 1 reply; 19+ messages in thread From: Jameson Graef Rollins @ 2020-04-29 15:33 UTC (permalink / raw) To: Daniel Kahn Gillmor, Ciprian Dorin Craciun, Tomi Ollila; +Cc: notmuch On Tue, Apr 28 2020, Daniel Kahn Gillmor <dkg@fifthhorseman.net> wrote: > One final way we could normalize everything and make it less > idiosyncratic, with shorter, simpler man pages: deprecate and then drop > the --booloption/--no-booloption mechanisms, requiring --booloption=true > or --booloption=false instead. Once they're dropped, allow whitespace > between "--booloption true" and "--booloption false" just like every > other type of option. Or we could just use only --booloption/--no-booloption... jamie. ^ permalink raw reply [flat|nested] 19+ messages in thread
* Re: Inconsistencies in handling command flags: `--flag=value` different than `--flag value` 2020-04-29 15:33 ` Jameson Graef Rollins @ 2020-04-30 16:59 ` Daniel Kahn Gillmor 0 siblings, 0 replies; 19+ messages in thread From: Daniel Kahn Gillmor @ 2020-04-30 16:59 UTC (permalink / raw) To: Jameson Graef Rollins, Ciprian Dorin Craciun, Tomi Ollila; +Cc: notmuch [-- Attachment #1.1: Type: text/plain, Size: 962 bytes --] On Wed 2020-04-29 08:33:24 -0700, Jameson Graef Rollins wrote: > On Tue, Apr 28 2020, Daniel Kahn Gillmor <dkg@fifthhorseman.net> wrote: >> One final way we could normalize everything and make it less >> idiosyncratic, with shorter, simpler man pages: deprecate and then drop >> the --booloption/--no-booloption mechanisms, requiring --booloption=true >> or --booloption=false instead. Once they're dropped, allow whitespace >> between "--booloption true" and "--booloption false" just like every >> other type of option. > > Or we could just use only --booloption/--no-booloption... I'd be sad about that, because it seems like a pretty idiosyncratic thing to have options of a certain type behave so differently from others. we've seen boolean options turn into non-boolean options in the past, and changing the syntax of how they're invoked when that happens feels ugly (though i guess this is at least in part an aesthetic preference). --dkg [-- Attachment #1.2: signature.asc --] [-- Type: application/pgp-signature, Size: 227 bytes --] [-- Attachment #2: Type: text/plain, Size: 0 bytes --] ^ permalink raw reply [flat|nested] 19+ messages in thread
end of thread, other threads:[~2020-05-08 16:10 UTC | newest] Thread overview: 19+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2020-04-24 12:53 Inconsistencies in handling command flags: `--flag=value` different than `--flag value` Ciprian Dorin Craciun 2020-04-27 17:53 ` David Bremner 2020-04-27 18:02 ` Daniel Kahn Gillmor 2020-04-27 18:20 ` Tomi Ollila 2020-04-27 19:21 ` Ciprian Dorin Craciun 2020-04-29 2:16 ` Daniel Kahn Gillmor 2020-04-29 14:18 ` Tomi Ollila 2020-04-29 15:39 ` David Bremner 2020-04-29 15:45 ` Jameson Graef Rollins 2020-04-29 16:28 ` David Bremner 2020-05-05 18:28 ` Carl Worth 2020-05-07 19:26 ` [PATCH] notmuch(1): clarify documentation about --option/value separators Daniel Kahn Gillmor 2020-05-07 23:40 ` Carl Worth 2020-05-08 12:01 ` David Bremner 2020-05-08 16:06 ` Daniel Kahn Gillmor 2020-04-29 15:59 ` Inconsistencies in handling command flags: `--flag=value` different than `--flag value` Ciprian Dorin Craciun 2020-04-29 16:07 ` Jameson Graef Rollins 2020-04-29 15:33 ` Jameson Graef Rollins 2020-04-30 16:59 ` Daniel Kahn Gillmor
Code repositories for project(s) associated with this public inbox https://yhetil.org/notmuch.git/ This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).