<|>, etc should be reexports about megaparsec

[mrkkrp]

@neongreen, currently only (<|>) can be reexported without changes. many
should be defined as part of Alternative instance (it's currently not),
and optional is just different thing in original Parsec (see signature).

So, please correct me if I'm wrong, you want the following changes:

• Reexport (<|>) «as is».
• Make many part of Alternative instance of ParsecT and reexport it.
• Remove optional from Text.MegaParsec.Combinator and instead reexport
  Control.Applicative.optional. I'm looking at implementation of
  Control.Applicative.optional and I think there won't be any performance
  degradation, we will be able to extract Maybe a from it, that's better
  than unit, I think.
• What about some? We could rename many1 → some, and make it part of
  Alternative instance, than reexport it. What do you think?

---

I'm wondering if we should reexport the stuff. User could just import
Control.Applicative and use it along with Text.MegaParsec.

Although for the sake of convenience we probably should.

---

A note to self: it also may be a good idea to replace many1 part of parser
names with some.

[neongreen]

optional is just different thing in original Parsec (see signature)

Oops, right.

Remove optional from Text.MegaParsec.Combinator and instead reexport
Control.Applicative.optional

I would welcome that (as an aside, I'm also glad/surprised that you're willing to do it).

What about some? We could rename many1 → some, and make it part of
Alternative instance, than reexport it.

Yep (and I didn't propose it because you're the first person I see who even acknowledged the existence of some – I considered it a lost case).

---

I'm wondering if we should reexport the stuff.

For the sake of convenience, yes. There also should be a note documenting them, because in my experience Alternative is a class that people never hear about and so they wouldn't guess that <|> actually comes from there if you won't tell them.

[mrkkrp]

@neongreen, OK, I think I will do these changes in short time, thank you for your interest and contribution.

[mrkkrp]

@neongreen, Hmm, it seems it's not possible to re-export something and add another documentation string at the same time. The main problem now is how to document these functions. They certainly should have more detailed documentation than default doc-strings of (<|>) and friends. Any idea?

[neongreen]

You can use floating documentation strings:

module Foo
(
  foo,
  -- $foo
  bar,
  -- $bar
 )
where

-- | This is foo. It does whatever.
foo :: [[[[a]]]] -> Maybe a -> b
foo = undefined

-- | This is bar. & is a reverse application operator. 
-- This provides notational convenience. Its precedence
-- is one higher than that of the forward application 
-- operator $, which allows & to be nested in $. Blah blah text.
bar :: [[[[a]]]] -> Maybe a -> b
bar = undefined

-- notes

{- $foo

In publishing and graphic design, lorem ipsum (derived from Latin
dolorem ipsum, translated as "pain itself") is a filler text 
commonly used to demonstrate ...
-}

{- $bar

A bar (also known as a saloon or a tavern or sometimes a pub or 
club, referring to the actual establishment, as in pub bar or club
bar etc.) is a retail business ...
-}

It's going to look like this:

(Sorry, I just used whatever pieces of text I had around for the example. Also, here foo and bar aren't reexports, but it doesn't matter for Haddock.)

[mrkkrp]

@neongreen, this works, although these notes should be inserted in every file, so I need to put them in Text.MegaParsec.Prim as well as Text.MegaParsec. The duplication is not very good thing.

[mrkkrp]

@neongreen, just discovered that Parsec's (<|>) is right-associative (1) while alternative's (<|>) is left-associative with different precedence (3). I wonder what implications this may have for already existing code…

Now I need to rewrite choice which should use foldl — not a big deal though.

[neongreen]

 alternative's (<|>) is left-associative with different precedence (3)

Oh, I should've mentioned that (I knew about it). Sorry.

Can you explain why choice should use foldl, tho?

[mrkkrp]

@neongreen, intuitive understanding of choice is that it transforms list
of alternatives into parser that uses these alternatives with help of
(<|>):

choice [a,b,c,d] ≡ a <|> b <|> c <|> d

Since we work now with left-associative (<|>), we need to use left fold
for the left part of the equation to be equal to the right part of the
equation.

a <|> b <|> c <|> d ≡ (a <|> (b <|> (c <|> d))) ≡ foldr (<|>) mzero
-- ↑ Parsec
a <|> b <|> c <|> d ≡ (((a <|> b) <|> c) <|> d) ≡ foldl (<|>) mzero
-- ↑ Megaparsec

It may seem that there is no difference how to combine the operators, but
this is wrong impression. When I wanted to rewrite a part of
makeExprParser (called buildExpressionParser in Parsec), I had the
following transformation in mind:

termP >>= \x -> rasP x <|> lasP x <|> nasP x <|> return x <?> "operator"
⇒
termP >>= \x -> choice [rasP x, lasP x, nasP x, return x] <?> "operator"

To my surprise this didn't work, test for bug number 9 from old tests
failed. I was perplexed for a while because I knew that this choice
variant should be the same as literal chain of (<|>). Then I checked
associativity of Parsec's (<|>) and alternative's (<|>) and found out
that they behave differently when chained.

Once I changed implementation of choice, the new code passed the test.

[neongreen]

Hm, that's surprising. It hasn't occurred to me previously that in other libraries choice [a,b,c] isn't equivalent to a <|> b <|> c (where “other libraries” are attoparsec and parsers).

[mrkkrp]

Are you sure that choice in those libraries uses foldr while (<|>) is left-associative? Note that difference is not in result, but in error message actually.

[mrkkrp]

I should admit that I don't understand why <?> "operator" is ever executed, since return x should never fail. This is strange. I need to return to this later.

[neongreen]

choice in both those libraries is an alias for asum, which uses foldr. <|> is reexported from Control.Applicative.

[neongreen]

Update: no, choice isn't an alias for asum in attoparsec, but it's implemented the same way.

[neongreen]

I should admit that I don't understand why <?> "operator" is ever executed

Me neither. Could it be merely a mistake in original Pandoc?

[mrkkrp]

@neongreen, initially I thought the same, but it makes difference, without
it error message is different! Well, test for bug number 9 deals with
Text.Megaparsec.Token too, this makes the situation more complex.

And after all foldr and foldl should result in the same error messages
and results, it should not matter how parsers are grouped, it should
“short-circuit” pretty much the same and most importantly with the same
results. I need to find out what is going on…

[mrkkrp]

@neongreen, OK I've reverted that last change, I think choice should be
indeed synonym for asum. I'll need to isolate the phenomenon and find out
what happens. But this will be a bit later, right now I need some rest :-D

[mrkkrp]

@neongreen, OK, <?> "operator" thing is clear. Labels are used not only in case of errors but also when parser succeeds without consuming input. This allows to print better error messages, in Megaparsec this is done via hints.

[mrkkrp]

This is addressed in #25 (fixed).