Documentation?

[zepalmer]

This is sort of low priority, but the example documentation doesn't really mention that the Parser type doesn't require the arguments in the order in which they are specified. It would be helpful if the examples demonstrate this; it would also be nice if the behavior of "many" on Parser was explained in more detail. The following is an explanation of my request; I hope it's helpful to search engines as well. :)

I had thought this would be similar in some way to Parsec and so wrote

switch (short 'z')

thinking that I would get a parser which can parse a "-z" flag once. So then I wrote

many $ switch (short 'z')

in an attempt to get a parser which can parse many "-z" flags. But when I run

execParser $ info (many $ switch $ short 'z') fullDesc

I get a stack overflow. It was not obvious to me why this was the case. For any reader who may be confused, the answer is that optparse does not work like Parsec; each parser is essentially responsible for generating one argument to a function which will handle the command-line parameters. So

MyRecord <$> switch (short 'x') <*> switch (short 'y')

will parse the arguments "-y -x" but then send them to the right places in the record. So in a sense,

switch (short 'x')

simultaneously means "the argument -x is valid" and "this is where the result of parsing the argument -x will go". Unfortunately, I have no intuition for what the following would mean:

many $ switch (short 'x')

Thanks!

[pcapriotti]

I agree that there should be a more comprehensive documentation (patches are welcome :)).

In the particular case of many (switch (short 'x')), the problem is that, if p is a parser that always succeeds, many p will not work as you expect, because it will try to succeed with an infinite string, which means that in practice it will stack overflow.

So, if you want to parse a finite list of switches, you should use flag', which is a parser that can fail. For example, something like length <$> many (flag' () (short 'x')) will give you the number of times that -x appears on the command line.

[shoooe]

I think the documentation examples should be more split up into separate functions with explicit types. I'm having some troubles unwrapping each piece of code and understanding what does what.

[HuwCampbell]

We have quite a few doc improvements in now, including on the haddocks that switch can't be used in a many. I might close this issue.