From: David Bremner <david@tethera.net>
To: guyzmo <guyzmo+notmuch@m0g.net>
Subject: Re: argument parsing refactoring round3
In-Reply-To: <20150408143147.GD5218@vilya.online.net>
References: <871tjws8w8.fsf@qmul.ac.uk>
 <1428435042-16503-1-git-send-email-david@tethera.net>
 <20150408143147.GD5218@vilya.online.net>
User-Agent: Notmuch/0.19+96~g703c8f9 (http://notmuchmail.org) Emacs/24.4.1
 (x86_64-pc-linux-gnu)
Date: Thu, 09 Apr 2015 08:53:56 +0900
Message-ID: <87oamy41nv.fsf@maritornes.cs.unb.ca>
MIME-Version: 1.0
Content-Type: text/plain
Cc: notmuch@notmuchmail.org
Precedence: list

guyzmo <guyzmo+notmuch@m0g.net> writes:

> Hi David,

[...]

> I see you patching and repatching notmuch's CLI to improve it, and I was
> wondering whether you had considered actually using `docopt` to generate
> the CLI parser from the output.
>
> It's possible to chain docopts to create a CLI UI very much alike the
> git command, and it's more easily maintainable, as you're actually
> generating the code from the `--help` page instead of the other way
> around, making you focus on how you want the user to use the CLI only.

[...]

> what do you believe?

It's an interesting idea, and if I was faced with writing CLI parser
from scratch (i.e. 4 years ago) I would investigate it more seriously.
As it stands, I'm not particularly annoyed with the notmuch argument
parsing code, so I mainly see negative issues about your proposal.

- I'm not sure how much this change would ripple through the rest of the
  notmuch code. At least all of the variables set by the current
  argument parsing code would have to be set foo=args.foo, or replaced
  everywhere with args.foo.
   
- It would require modifying the notmuch CLI to conform to the
  conventions of docopt. Of course, you might consider this a feature,
  but I think as many people would be annoyed as would be happy.

- The most dramatic example of an appartently missing feature from
  docopt is keyword arguments of the form
  
    --output=(messages|threads|summary).

  These are the reason we rolled our own parser in the first place,
  rather than using e.g. gnu getopt.  docopt says it doesn't do data
  validation, which is fine philosophically, but by the time we add back
  in validation code, I'm not sure we win very much in the
  maintainability department.
  
- I don't really know about the health of the docopt.c project, compared
  to the python version. It seems somewhat unfinished [1]; in particular
  a lack of positional arguments seems like a showstopper for us.
  arguments. There has never been a release (which is the norm for
  github, but not for dependencies of notmuch), and the last commit was
  in December of 2014.

- Since docopt_c_py is not widely in distros (it isn't in Debian, for
  example), we'd have to emded it the notmuch source.  It's only 217
  lines of fairly simple python, but embedding 3rd party code is
  something we try pretty hard to avoid.

As always, my lack of enthusiasm doesn't prevent someone else from
investigating further, but hopefully the points I listed above give
anyone doing such investigation some hints as to what I (and I suspect
not just I) would object to about any hypothetical patches.

David

[1]: From the README.md "Note, at this point the code generator handles
only options (positional arguments, commands and pattern matching will
follow)."