summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authormrkkrp <>2018-11-08 14:54:00 (GMT)
committerhdiff <hdiff@hdiff.luite.com>2018-11-08 14:54:00 (GMT)
commit81518f41f30fda2aa06803a6e30cfc00c2fa4e90 (patch)
tree90a7ba292e9a8996d0c324f16297fdb9180b9cae
parent5323724a17004abc3d4ab07de160e82a54c1b83d (diff)
version 7.0.4HEAD7.0.4master
-rw-r--r--CHANGELOG.md6
-rw-r--r--README.md215
-rw-r--r--Text/Megaparsec.hs32
-rw-r--r--Text/Megaparsec/Byte/Lexer.hs2
-rw-r--r--Text/Megaparsec/Char/Lexer.hs15
-rw-r--r--Text/Megaparsec/Class.hs19
-rw-r--r--Text/Megaparsec/Debug.hs3
-rw-r--r--Text/Megaparsec/Error.hs3
-rw-r--r--Text/Megaparsec/Internal.hs11
-rw-r--r--Text/Megaparsec/Lexer.hs4
-rw-r--r--Text/Megaparsec/Pos.hs10
-rw-r--r--Text/Megaparsec/Stream.hs2
-rw-r--r--megaparsec.cabal4
13 files changed, 159 insertions, 167 deletions
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8d0e334..33160fe 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,7 @@
+## Megaparsec 7.0.4
+
+* Numerous documentation corrections.
+
## Megaparsec 7.0.3
* Fixed the build with `mtl` older than `2.2.2`.
@@ -10,7 +14,7 @@
* More descriptive error messages when `elabel` or `ulabel` from
`Text.Megaparsec.Error.Builder` are used with empty strings.
-* Typos fixes in the docs.
+* Typo fixes in the docs.
## Megaparsec 7.0.1
diff --git a/README.md b/README.md
index 6b5781f..04aca6e 100644
--- a/README.md
+++ b/README.md
@@ -40,65 +40,65 @@ documentation, see the [section about documentation](#documentation).
### Core features
The package is built around `MonadParsec`, an MTL-style monad transformer.
-All tools and features work with all instances of `MonadParsec`. You can
-achieve various effects combining monad transformers, i.e. building a
-monadic stack. Since the common monad transformers like `WriterT`, `StateT`,
-`ReaderT` and others are instances of the `MonadParsec` type class, you can
-wrap `ParsecT` *in* these monads, achieving, for example, backtracking
-state.
+Most features work with all instances of `MonadParsec`. One can achieve
+various effects combining monad transformers, i.e. building a monadic stack.
+Since the common monad transformers like `WriterT`, `StateT`, `ReaderT` and
+others are instances of the `MonadParsec` type class, one can also wrap
+`ParsecT` *in* these monads, achieving, for example, backtracking state.
On the other hand `ParsecT` is an instance of many type classes as well. The
most useful ones are `Monad`, `Applicative`, `Alternative`, and
`MonadParsec`.
-Megaparsec includes all functionality that is available in Parsec plus
-features some combinators that are missing in other parsing libraries:
+Megaparsec includes all functionality that is typically available in
+Parsec-like libraries and also features some combinators that are quite
+unique to it:
-* `failure` allows to fail reporting a parse error with unexpected and
- expected items.
-* `fancyFailure` allows to fail reporting custom error messages.
-* `withRecovery` allows to recover from parse errors “on-the-fly” and
+* `failure` allows us to report a parse error with unexpected and expected
+ items.
+* `fancyFailure` provides a way to report custom parse errors.
+* `withRecovery` can be used to recover from parse errors “on-the-fly” and
continue parsing. Once parsing is finished, several parse errors may be
reported or ignored altogether.
-* `observing` allows to “observe” parse errors without ending parsing (they
- are returned in `Left`, while normal results are wrapped in `Right`).
+* `observing` makes it possible to “observe” parse errors without ending
+ parsing (they are returned in `Left`, while normal results are wrapped in
+ `Right`).
In addition to that, Megaparsec features high-performance combinators
-similar to those found in Attoparsec:
+similar to those found in [Attoparsec][attoparsec]:
* `tokens` makes it easy to parse several tokens in a row (`string` and
`string'` are built on top of this primitive). This is about 100 times
faster than matching a string token by token. `tokens` returns “chunk” of
original input, meaning that if you parse `Text`, it'll return `Text`
- without any repacking.
+ without repacking.
* `takeWhile` and `takeWhile1` are about 150 times faster than approaches
involving `many`, `manyTill` and other similar combinators.
-* `takeP` allows to grab n tokens from the stream and returns them as a
+* `takeP` allows us to grab n tokens from the stream and returns them as a
“chunk” of the stream.
Megaparsec is about as fast as Attoparsec if you write your parser carefully
(see also [the section about performance](#performance)).
-Megaparsec can currently work with the following types of input stream
+The library can currently work with the following types of input stream
out-of-the-box:
-* `String` = `[Char]`
+* `String = [Char]`
* `ByteString` (strict and lazy)
* `Text` (strict and lazy)
-It's also simple to make it work with custom token streams, and Megaparsec
-users have done so many times.
+It's also possible to make it work with custom token streams by making them
+an instance of the `Stream` type class.
### Error messages
-Megaparsec has well-typed error messages and the ability to use custom data
-types to adjust the library to specific domain of interest. No need to use a
-shapeless bunch of strings.
+Megaparsec has well-typed error messages and the ability to signal custom
+parse errors to better work in user's domain of interest.
Megaparsec 7 introduced the `ParseErrorBundle` data type that helps to
manage multi-error messages and pretty-print them easily and efficiently.
That version of the library also made the practice of displaying offending
-line the default.
+line the default, similar to how recent versions of GHC do it.
### Alex support
@@ -110,53 +110,45 @@ without problems.
### Character and binary parsing
Megaparsec has decent support for Unicode-aware character parsing. Functions
-for character parsing live in the
-[`Text.Megaparsec.Char`](https://hackage.haskell.org/package/megaparsec/docs/Text-Megaparsec-Char.html)
-module. Similarly, there is
-[`Text.Megaparsec.Byte`](https://hackage.haskell.org/package/megaparsec/docs/Text-Megaparsec-Byte.html)
-module for parsing streams of bytes.
+for character parsing live in the [`Text.Megaparsec.Char`][tm-char] module.
+Similarly, there is [`Text.Megaparsec.Byte`][tm-byte] module for parsing
+streams of bytes.
### Lexer
-[`Text.Megaparsec.Char.Lexer`](https://hackage.haskell.org/package/megaparsec/docs/Text-Megaparsec-Char-Lexer.html)
-is a module that should help you write your lexer. If you have used `Parsec`
-in the past, this module “fixes” its particularly inflexible
-`Text.Parsec.Token`.
+[`Text.Megaparsec.Char.Lexer`][tm-char-lexer] is a module that should help
+you write your lexer. If you have used `Parsec` in the past, this module
+“fixes” its particularly inflexible `Text.Parsec.Token`.
-`Text.Megaparsec.Char.Lexer` is intended to be imported using a qualified
-import, it's not included in `Text.Megaparsec`. The module doesn't impose
-how you should write your parser, but certain approaches may be more elegant
-than others. An especially important theme is parsing of white space,
-comments, and indentation.
+[`Text.Megaparsec.Char.Lexer`][tm-char-lexer] is intended to be imported
+using a qualified import, it's not included in [`Text.Megaparsec`][tm]. The
+module doesn't impose how you should write your parser, but certain
+approaches may be more elegant than others. An especially important theme is
+parsing of white space, comments, and indentation.
-The design of the module allows you quickly solve simple tasks and doesn't
-get in your way when you want to implement something less standard.
+The design of the module allows one quickly solve simple tasks and doesn't
+get in the way when the need to implement something less standard arises.
-Since Megaparsec 5, all tools for indentation-sensitive parsing are
-available in `Text.Megaparsec.Char.Lexer` module—no third party packages
-required.
-
-`Text.Megaparsec.Byte.Lexer` is also available for users who wish to parse
-binary data.
+[`Text.Megaparsec.Byte.Lexer`][tm-byte-lexer] is also available for users
+who wish to parse binary data.
## Documentation
Megaparsec is well-documented. See the [current version of Megaparsec
-documentation on Hackage](https://hackage.haskell.org/package/megaparsec).
+documentation on Hackage][hackage].
## Tutorials
-You can find Megaparsec tutorials
-[here](https://markkarpov.com/learn-haskell.html#megaparsec-tutorials). They
-should provide sufficient guidance to help you to start with your parsing
-tasks. The site also has instructions and tips for Parsec users who decide
-to migrate to Megaparsec.
+You can find Megaparsec tutorials [here][tutorials]. They should provide
+sufficient guidance to help you start with your parsing tasks. The site also
+has instructions and tips for Parsec users who decide to migrate to
+Megaparsec.
## Performance
Despite being flexible, Megaparsec is also fast. Here is how Megaparsec
-7.0.0 compares to Attoparsec 0.13.2.2 (the fastest widely used parsing
-library in the Haskell ecosystem):
+7.0.0 compares to [Attoparsec][attoparsec] 0.13.2.2 (the fastest widely used
+parsing library in the Haskell ecosystem):
Test case | Execution time | Allocated | Max residency
------------------|---------------:|----------:|-------------:
@@ -168,11 +160,10 @@ JSON (Attoparsec) | 18.20 μs | 128,368 | 9,032
JSON (Megaparsec) | 25.45 μs | 203,824 | 9,176
The benchmarks were created to guide development of Megaparsec 6 and can be
-found [here](https://github.com/mrkkrp/parsers-bench).
+found [here][parsers-bench].
If you think your Megaparsec parser is not efficient enough, take a look at
-[these
-instructions](https://markkarpov.com/megaparsec/writing-a-fast-parser.html).
+[these instructions][fast-parser].
## Comparison with other solutions
@@ -181,10 +172,9 @@ let's compare Megaparsec with some of them.
### Megaparsec vs Attoparsec
-[Attoparsec](https://hackage.haskell.org/package/attoparsec) is another
-prominent Haskell library for parsing. Although the both libraries deal with
-parsing, it's usually easy to decide which you will need in particular
-project:
+[Attoparsec][attoparsec] is another prominent Haskell library for parsing.
+Although both libraries deal with parsing, it's usually easy to decide which
+you will need in particular project:
* *Attoparsec* is sometimes faster but not that feature-rich. It should be
used when you want to process large amounts of data where performance
@@ -195,56 +185,35 @@ project:
transformer.
So, if you work with something human-readable where size of input data is
-usually not huge, just go with Megaparsec, otherwise Attoparsec may be a
-better choice.
-
-Since version 6, Megaparsec features the same fast primitives that
-Attoparsec has, so in many cases the difference in speed is not that big.
-Megaparsec now aims to be “one size fits all” ultimate solution to parsing,
-so it can be used even to parse low-level binary formats.
+moderate, just go with Megaparsec, otherwise Attoparsec may be a better
+choice.
### Megaparsec vs Parsec
-Since Megaparsec is a fork of
-[Parsec](https://hackage.haskell.org/package/parsec), we are bound to list
-the main differences between the two libraries:
+Since Megaparsec is a fork of [Parsec][parsec], we are bound to list the
+main differences between the two libraries:
-* Better error messages. We test our error messages using numerous
- QuickCheck (generative) tests. Good error messages are just as important
- for us as correct return values of our parsers. Megaparsec will be
- especially useful if you write a compiler or an interpreter for some
- language.
+* Better error messages. Megaparsec has well-typed error messages and custom
+ error messages.
-* Megaparsec 6 can show the line on which parse error happened as part of
+* Megaparsec can show the line on which parse error happened as part of
parse error. This makes it a lot easier to figure out where the error
happened.
* Some quirks and “buggy features” (as well as plain bugs) of original
Parsec are fixed. There is no undocumented surprising stuff in Megaparsec.
-* Better support for Unicode parsing in `Text.Megaparsec.Char`.
+* Better support for Unicode parsing in [`Text.Megaparsec.Char`][tm-char].
* Megaparsec has more powerful combinators and can parse languages where
indentation matters out-of-the-box.
-* Comprehensive test suite covering nearly 100% of our code. Compare that to
- absence
-
-* We have benchmarks to detect performance regressions.
-
-* Better documentation, with 100% of functions covered, without typos and
- obsolete information, with working examples. Megaparsec's documentation is
- well-structured and doesn't contain things useless to end users.
-
-* Megaparsec's code is clearer and doesn't contain “magic” found in original
- Parsec.
-
-* Megaparsec has well-typed error messages and custom error messages.
+* Better documentation.
* Megaparsec can recover from parse errors “on the fly” and continue
parsing.
-* Megaparsec allows to conditionally process parse errors *inside your
+* Megaparsec allows us to conditionally process parse errors *inside your
parser* before parsing is finished. In particular, it's possible to define
regions in which parse errors, should they happen, will get a “context
tag”, e.g. we could build a context stack like “in function definition
@@ -254,17 +223,14 @@ the main differences between the two libraries:
`takeWhileP`, `takeWhile1P`, `takeP` like Attoparsec.
If you want to see a detailed change log, `CHANGELOG.md` may be helpful.
-Also see [this original
-announcement](https://mail.haskell.org/pipermail/haskell-cafe/2015-September/121530.html)
-for another comparison.
+Also see [this original announcement][original-announcement] for another
+comparison.
### Megaparsec vs Trifecta
-[Trifecta](https://hackage.haskell.org/package/trifecta) is another Haskell
-library featuring good error messages. It's probably good, but also
-under-documented, and has unfixed [bugs and
-flaws](https://github.com/ekmett/trifecta/issues). Other reasons one may
-question choice of Trifecta is his/her parsing library:
+[Trifecta][trifecta] is another Haskell library featuring good error
+messages. Some reasons one may question choice of Trifecta is his/her
+parsing library:
* Complicated, doesn't have any tutorials available, and documentation
doesn't help at all.
@@ -279,23 +245,23 @@ question choice of Trifecta is his/her parsing library:
dependencies. Also if you're not into `lens` and would like to keep your
code “vanilla”, you may not like the API.
-[Idris](https://www.idris-lang.org/) has recently switched from Trifecta to
-Megaparsec which allowed it to [have better error messages and fewer
-dependencies](https://twitter.com/edwinbrady/status/950084043282010117?s=09).
+[Idris][idris] has recently switched from Trifecta to Megaparsec which
+allowed it to [have better error messages and fewer
+dependencies][idris-testimony].
### Megaparsec vs Earley
-[Earley](https://hackage.haskell.org/package/Earley) is a newer library that
-allows to safely (it your code compiles, then it probably works) parse
-context-free grammars (CFG). Megaparsec is a lower-level library compared to
-Earley, but there are still enough reasons to choose it over Earley:
+[Earley][earley] is a newer library that allows us to safely (it your code
+compiles, then it probably works) parse context-free grammars (CFG).
+Megaparsec is a lower-level library compared to Earley, but there are still
+enough reasons to choose it:
* Megaparsec is faster.
* Your grammar may be not context-free or you may want introduce some sort
of state to the parsing process. Almost all non-trivial parsers require
something of this sort. Even if your grammar is context-free, state may
- allow to add some additional niceties. Earley does not support that.
+ allow us to add some additional niceties. Earley does not support that.
* Megaparsec's error messages are more flexible allowing to include
arbitrary data in them, return multiple error messages, mark regions that
@@ -306,7 +272,7 @@ Earley, but there are still enough reasons to choose it over Earley:
much more productive with libraries taking more traditional path to
parsing like Megaparsec.
-IOW, Megaparsec is less safe but also more powerful.
+In other words, Megaparsec is less safe but also more powerful.
## Related packages
@@ -326,7 +292,7 @@ you want to add something to the list):
## Prominent projects that use Megaparsec
-The following are some prominent projects that use Megaparsec:
+Some prominent projects that use Megaparsec:
* [Idris](https://github.com/idris-lang/Idris-dev)—a general-purpose
functional programming language with dependent types
@@ -349,7 +315,7 @@ describing what sort of things are now possible:
* [Latest additions to Megaparsec](https://markkarpov.com/post/latest-additions-to-megaparsec.html)
* [Announcing Megaparsec 5](https://markkarpov.com/post/announcing-megaparsec-5.html)
* [Megaparsec 4 and 5](https://markkarpov.com/post/megaparsec-4-and-5.html)
-* [The original Megaparsec 4.0.0 announcement](https://mail.haskell.org/pipermail/haskell-cafe/2015-September/121530.html)
+* [The original Megaparsec 4.0.0 announcement][original-announcement]
## Authors
@@ -357,15 +323,14 @@ The project was started and is currently maintained by Mark Karpov. You can
find the complete list of contributors in the `AUTHORS.md` file in the
official repository of the project. Thanks to all the people who propose
features and ideas, although they are not in `AUTHORS.md`, without them
-Megaparsec would not be that good.
+Megaparsec would not be so good.
## Contribution
Issues (bugs, feature requests or otherwise feedback) may be reported in
[the GitHub issue tracker for this project](https://github.com/mrkkrp/megaparsec/issues).
-Pull requests are also welcome (and yes, they will get attention and will be
-merged quickly if they are good).
+Pull requests are also welcome.
## License
@@ -374,3 +339,23 @@ Copyright © 2007 Paolo Martini\
Copyright © 1999–2000 Daan Leijen
Distributed under FreeBSD license.
+
+[hackage]: https://hackage.haskell.org/package/megaparsec
+[tutorials]: https://markkarpov.com/learn-haskell.html#megaparsec-tutorials
+
+[tm]: https://hackage.haskell.org/package/megaparsec/docs/Text-Megaparsec.html
+[tm-char]: https://hackage.haskell.org/package/megaparsec/docs/Text-Megaparsec-Char.html
+[tm-byte]: https://hackage.haskell.org/package/megaparsec/docs/Text-Megaparsec-Byte.html
+[tm-char-lexer]: https://hackage.haskell.org/package/megaparsec/docs/Text-Megaparsec-Char-Lexer.html
+[tm-byte-lexer]: https://hackage.haskell.org/package/megaparsec/docs/Text-Megaparsec-Byte-Lexer.html
+
+[attoparsec]: https://hackage.haskell.org/package/attoparsec
+[parsec]: https://hackage.haskell.org/package/parsec
+[trifecta]: https://hackage.haskell.org/package/trifecta
+[earley]: https://hackage.haskell.org/package/Earley
+[idris]: https://www.idris-lang.org/
+[idris-testimony]: https://twitter.com/edwinbrady/status/950084043282010117?s=09
+
+[parsers-bench]: https://github.com/mrkkrp/parsers-bench
+[fast-parser]: https://markkarpov.com/megaparsec/writing-a-fast-parser.html
+[original-announcement]: https://mail.haskell.org/pipermail/haskell-cafe/2015-September/121530.html
diff --git a/Text/Megaparsec.hs b/Text/Megaparsec.hs
index 3628a2a..d24357d 100644
--- a/Text/Megaparsec.hs
+++ b/Text/Megaparsec.hs
@@ -11,7 +11,8 @@
--
-- This module includes everything you need to get started writing a parser.
-- If you are new to Megaparsec and don't know where to begin, take a look
--- at the tutorials <https://markkarpov.com/learn-haskell.html#megaparsec-tutorials>.
+-- at the tutorials
+-- <https://markkarpov.com/learn-haskell.html#megaparsec-tutorials>.
--
-- In addition to the "Text.Megaparsec" module, which exports and re-exports
-- most everything that you may need, we advise to import
@@ -39,7 +40,7 @@
--
-- Megaparsec uses some type-level machinery to provide flexibility without
-- compromising on type safety. Thus type signatures are sometimes necessary
--- to avoid ambiguous types. If you're seeing a error message that reads
+-- to avoid ambiguous types. If you're seeing an error message that reads
-- like “Type variable @e0@ is ambiguous …”, you need to give an explicit
-- signature to your parser to resolve the ambiguity. It's a good idea to
-- provide type signatures for all top-level definitions.
@@ -173,7 +174,7 @@ parse = runParser
-- will fail.
--
-- The function is supposed to be useful for lightweight parsing, where
--- error messages (and thus file name) are not important and entire input
+-- error messages (and thus file names) are not important and entire input
-- should be parsed. For example, it can be used when parsing of a single
-- number according to a specification of its format is desired.
@@ -183,7 +184,7 @@ parseMaybe p s =
Left _ -> Nothing
Right x -> Just x
--- | The expression @'parseTest' p input@ applies the parser @p@ against
+-- | The expression @'parseTest' p input@ applies the parser @p@ against the
-- input @input@ and prints the result to stdout. Useful for testing.
parseTest :: ( ShowErrorComponent e
@@ -200,8 +201,8 @@ parseTest p input =
-- | @'runParser' p file input@ runs parser @p@ on the input stream of
-- tokens @input@, obtained from source @file@. The @file@ is only used in
--- error messages and may be the empty string. Returns either a 'ParseError'
--- ('Left') or a value of type @a@ ('Right').
+-- error messages and may be the empty string. Returns either a
+-- 'ParseErrorBundle' ('Left') or a value of type @a@ ('Right').
--
-- > parseFromFile p file = runParser p file <$> readFile file
@@ -228,8 +229,8 @@ runParser' p = runIdentity . runParserT' p
-- | @'runParserT' p file input@ runs parser @p@ on the input list of tokens
-- @input@, obtained from source @file@. The @file@ is only used in error
-- messages and may be the empty string. Returns a computation in the
--- underlying monad @m@ that returns either a 'ParseError' ('Left') or a
--- value of type @a@ ('Right').
+-- underlying monad @m@ that returns either a 'ParseErrorBundle' ('Left') or
+-- a value of type @a@ ('Right').
runParserT :: Monad m
=> ParsecT e s m a -- ^ Parser to run
@@ -296,8 +297,7 @@ single t = token testToken expected
{-# INLINE single #-}
-- | The parser @'satisfy' f@ succeeds for any token for which the supplied
--- function @f@ returns 'True'. Returns the character that is actually
--- parsed.
+-- function @f@ returns 'True'.
--
-- > digitChar = satisfy isDigit <?> "digit"
-- > oneOf cs = satisfy (`elem` cs)
@@ -315,7 +315,7 @@ satisfy f = token testChar E.empty
{-# INLINE satisfy #-}
-- | Parse and return a single token. It's a good idea to attach a 'label'
--- to this parser manually.
+-- to this parser.
--
-- > anySingle = satisfy (const True)
--
@@ -328,7 +328,7 @@ anySingle = satisfy (const True)
{-# INLINE anySingle #-}
-- | Match any token but the given one. It's a good idea to attach a 'label'
--- to this parser manually.
+-- to this parser.
--
-- > anySingleBut t = satisfy (/= t)
--
@@ -377,7 +377,7 @@ oneOf cs = satisfy (`elem` cs)
--
-- See also: 'satisfy'.
--
--- __Performance note__: prefer 'satisfy' and 'singleBut' when you can
+-- __Performance note__: prefer 'satisfy' and 'anySingleBut' when you can
-- because it's faster.
--
-- @since 7.0.0
@@ -520,9 +520,9 @@ setInput s = updateParserState (\(State _ o pst) -> State s o pst)
-- not call it e.g. on matching of every token, that's a bad idea. Still you
-- can use it to get 'SourcePos' to attach to things that you parse.
--
--- The function works under the assumption that we move in input stream only
--- forward and never backward, which is always true unless the user abuses
--- the library on purpose.
+-- The function works under the assumption that we move in the input stream
+-- only forwards and never backwards, which is always true unless the user
+-- abuses the library.
--
-- @since 7.0.0
diff --git a/Text/Megaparsec/Byte/Lexer.hs b/Text/Megaparsec/Byte/Lexer.hs
index b4fc4dd..d62e235 100644
--- a/Text/Megaparsec/Byte/Lexer.hs
+++ b/Text/Megaparsec/Byte/Lexer.hs
@@ -97,7 +97,7 @@ skipBlockCommentNested start end = p >> void (manyTill e n)
-- | Parse an integer in decimal representation according to the format of
-- integer literals described in the Haskell report.
--
--- If you need to parse signed integers, see 'signed' combinator.
+-- If you need to parse signed integers, see the 'signed' combinator.
decimal
:: forall e s m a. (MonadParsec e s m, Token s ~ Word8, Integral a)
diff --git a/Text/Megaparsec/Char/Lexer.hs b/Text/Megaparsec/Char/Lexer.hs
index 0066467..f228c5a 100644
--- a/Text/Megaparsec/Char/Lexer.hs
+++ b/Text/Megaparsec/Char/Lexer.hs
@@ -11,8 +11,7 @@
--
-- High-level parsers to help you write your lexer. The module doesn't
-- impose how you should write your parser, but certain approaches may be
--- more elegant than others. Especially important theme is parsing of white
--- space, comments, and indentation.
+-- more elegant than others.
--
-- Parsing of white space is an important part of any parser. We propose a
-- convention where __every lexeme parser assumes no spaces before the__
@@ -190,8 +189,8 @@ nonIndented :: MonadParsec e s m
nonIndented sc p = indentGuard sc EQ pos1 *> p
{-# INLINEABLE nonIndented #-}
--- | The data type represents available behaviors for parsing of indented
--- tokens. This is used in 'indentBlock', which see.
+-- | Behaviors for parsing of indented tokens. This is used in
+-- 'indentBlock', which see.
--
-- @since 4.3.0
@@ -269,9 +268,9 @@ indentedItems ref lvl sc p = go
-- | Create a parser that supports line-folding. The first argument is used
-- to consume white space between components of line fold, thus it /must/
-- consume newlines in order to work properly. The second argument is a
--- callback that receives a custom space-consuming parser as argument. This
--- parser should be used after separate components of line fold that can be
--- put on different lines.
+-- callback that receives a custom space-consuming parser as an argument.
+-- This parser should be used after separate components of line fold that
+-- can be put on different lines.
--
-- An example should clarify the usage pattern:
--
@@ -328,7 +327,7 @@ charLiteral = label "literal character" $ do
-- | Parse an integer in decimal representation according to the format of
-- integer literals described in the Haskell report.
--
--- If you need to parse signed integers, see 'signed' combinator.
+-- If you need to parse signed integers, see the 'signed' combinator.
--
-- __Note__: before version 6.0.0 the function returned 'Integer', i.e. it
-- wasn't polymorphic in its return type.
diff --git a/Text/Megaparsec/Class.hs b/Text/Megaparsec/Class.hs
index c95461f..6cb5edc 100644
--- a/Text/Megaparsec/Class.hs
+++ b/Text/Megaparsec/Class.hs
@@ -120,11 +120,12 @@ class (Stream s, MonadPlus m) => MonadParsec e s m | m -> e s where
-- unexpected "le"
-- expecting "let" or "lexical"
--
- -- __Please note__ that as of Megaparsec 4.4.0, 'string' backtracks
- -- automatically (see 'tokens'), so it does not need 'try'. However, the
- -- examples above demonstrate the idea behind 'try' so well that it was
- -- decided to keep them. You still need to use 'try' when your
- -- alternatives are complex, composite parsers.
+ -- __Please note__ that as of Megaparsec 4.4.0,
+ -- 'Text.Megaparsec.Char.string' backtracks automatically (see 'tokens'),
+ -- so it does not need 'try'. However, the examples above demonstrate the
+ -- idea behind 'try' so well that it was decided to keep them. You still
+ -- need to use 'try' when your alternatives are complex, composite
+ -- parsers.
try :: m a -> m a
@@ -160,7 +161,7 @@ class (Stream s, MonadPlus m) => MonadParsec e s m | m -> e s where
-> m a -- ^ Parser that can recover from failures
-- | @'observing' p@ allows to “observe” failure of the @p@ parser, should
- -- it happen, without actually ending parsing, but instead getting the
+ -- it happen, without actually ending parsing but instead getting the
-- 'ParseError' in 'Left'. On success parsed value is returned in 'Right'
-- as usual. Note that this primitive just allows you to observe parse
-- errors as they happen, it does not backtrack or change how the @p@
@@ -172,7 +173,7 @@ class (Stream s, MonadPlus m) => MonadParsec e s m | m -> e s where
:: m a -- ^ The parser to run
-> m (Either (ParseError s e) a)
- -- | This parser only succeeds at the end of the input.
+ -- | This parser only succeeds at the end of input.
eof :: m ()
@@ -231,8 +232,8 @@ class (Stream s, MonadPlus m) => MonadParsec e s m | m -> e s where
-- | Parse /zero/ or more tokens for which the supplied predicate holds.
-- Try to use this as much as possible because for many streams the
- -- combinator is much faster than parsers built with 'many' and
- -- 'Text.Megaparsec.Char.satisfy'.
+ -- combinator is much faster than parsers built with
+ -- 'Control.Monad.Combinators.many' and 'Text.Megaparsec.satisfy'.
--
-- The following equations should clarify the behavior:
--
diff --git a/Text/Megaparsec/Debug.hs b/Text/Megaparsec/Debug.hs
index 4791fbf..9860bdd 100644
--- a/Text/Megaparsec/Debug.hs
+++ b/Text/Megaparsec/Debug.hs
@@ -52,7 +52,8 @@ import qualified Data.List.NonEmpty as NE
-- transformers without introducing surprising behavior (e.g. unexpected
-- state backtracking) or adding otherwise redundant constraints (e.g.
-- 'Show' instance for state), so this helper is only available for
--- 'ParsecT' monad, not any instance of 'MonadParsec' in general.
+-- 'ParsecT' monad, not any instance of 'Text.Megaparsec.MonadParsec' in
+-- general.
dbg :: forall e s m a.
( Stream s
diff --git a/Text/Megaparsec/Error.hs b/Text/Megaparsec/Error.hs
index 16eedcf..221ceed 100644
--- a/Text/Megaparsec/Error.hs
+++ b/Text/Megaparsec/Error.hs
@@ -96,8 +96,7 @@ data ErrorFancy e
-- level and actual level, reference indentation level, actual
-- indentation level
| ErrorCustom e
- -- ^ Custom error data, can be conveniently disabled by indexing
- -- 'ErrorFancy' by 'Void'
+ -- ^ Custom error data
deriving (Show, Read, Eq, Ord, Data, Typeable, Generic, Functor)
instance NFData a => NFData (ErrorFancy a) where
diff --git a/Text/Megaparsec/Internal.hs b/Text/Megaparsec/Internal.hs
index 89ac159..ca03684 100644
--- a/Text/Megaparsec/Internal.hs
+++ b/Text/Megaparsec/Internal.hs
@@ -100,7 +100,7 @@ newtype Hints t = Hints [Set (ErrorItem t)]
data Reply e s a = Reply (State s) Consumption (Result s e a)
--- | This data structure represents an aspect of result of parser's work.
+-- | Whether the input has been consumed or not.
--
-- See also: 'Result', 'Reply'.
@@ -108,7 +108,8 @@ data Consumption
= Consumed -- ^ Some part of input stream was consumed
| Virgin -- ^ No input was consumed
--- | This data structure represents an aspect of result of parser's work.
+-- | Whether the parser has failed or not. On success we include the
+-- resulting value, on failure we include a 'ParseError'.
--
-- See also: 'Consumption', 'Reply'.
@@ -540,7 +541,7 @@ nes x = x :| []
----------------------------------------------------------------------------
-- Helper functions
--- | Convert 'ParseError' record into 'Hints'.
+-- | Convert 'ParseError' record to 'Hints'.
toHints
:: Stream s
@@ -588,8 +589,8 @@ accHints hs1 c x s hs2 = c x s (hs1 <> hs2)
{-# INLINE accHints #-}
-- | Replace the most recent group of hints (if any) with the given
--- 'ErrorItem' (or delete it if 'Nothing' is given). This is used in 'label'
--- primitive.
+-- 'ErrorItem' (or delete it if 'Nothing' is given). This is used in the
+-- 'label' primitive.
refreshLastHint :: Hints t -> Maybe (ErrorItem t) -> Hints t
refreshLastHint (Hints []) _ = Hints []
diff --git a/Text/Megaparsec/Lexer.hs b/Text/Megaparsec/Lexer.hs
index 74591bd..b9c0069 100644
--- a/Text/Megaparsec/Lexer.hs
+++ b/Text/Megaparsec/Lexer.hs
@@ -43,10 +43,10 @@ import qualified Data.CaseInsensitive as CI
-- 'takeWhile1P' are preferred because of their speed.
--
-- @lineComment@ is used to parse line comments. You can use
--- 'skipLineComment' if you don't need anything special.
+-- @skipLineComment@ if you don't need anything special.
--
-- @blockComment@ is used to parse block (multi-line) comments. You can use
--- 'skipBlockComment' or 'skipBlockCommentNested' if you don't need anything
+-- @skipBlockComment@ or @skipBlockCommentNested@ if you don't need anything
-- special.
--
-- If you don't want to allow a kind of comment, simply pass 'empty' which
diff --git a/Text/Megaparsec/Pos.hs b/Text/Megaparsec/Pos.hs
index d445d0a..453c4e6 100644
--- a/Text/Megaparsec/Pos.hs
+++ b/Text/Megaparsec/Pos.hs
@@ -8,8 +8,7 @@
-- Portability : portable
--
-- Textual source position. The position includes name of file, line number,
--- and column number. A non-empty list of such positions can be used to
--- model a stack of include files.
+-- and column number.
--
-- You probably do not want to import this module directly because
-- "Text.Megaparsec" re-exports it anyway.
@@ -87,6 +86,10 @@ pos1 = mkPos 1
-- you want to refer to the default tab width because actual value /may/
-- change in future.
--
+-- Currently:
+--
+-- > defaultTabWidth = mkPos 8
+--
-- @since 5.0.0
defaultTabWidth :: Pos
@@ -109,8 +112,7 @@ instance Read Pos where
-- @since 5.0.0
newtype InvalidPosException = InvalidPosException Int
- -- ^ The first value is the minimal allowed value, the second value is the
- -- actual value that was passed to 'mkPos'.
+ -- ^ Contains the actual value that was passed to 'mkPos'
deriving (Eq, Show, Data, Typeable, Generic)
instance Exception InvalidPosException
diff --git a/Text/Megaparsec/Stream.hs b/Text/Megaparsec/Stream.hs
index 04b3610..1d07894 100644
--- a/Text/Megaparsec/Stream.hs
+++ b/Text/Megaparsec/Stream.hs
@@ -166,7 +166,7 @@ class (Ord (Token s), Ord (Tokens s)) => Stream s where
reachOffset
:: Int -- ^ Offset to reach
-> PosState s -- ^ Initial 'PosState' to use
- -> (SourcePos, String, PosState s) -- ^ (See above)
+ -> (SourcePos, String, PosState s) -- ^ (See below)
-- | A version of 'reachOffset' that may be faster because it doesn't need
-- to fetch the line at which the given offset in located.
diff --git a/megaparsec.cabal b/megaparsec.cabal
index 5145c07..531f0a2 100644
--- a/megaparsec.cabal
+++ b/megaparsec.cabal
@@ -1,7 +1,7 @@
name: megaparsec
-version: 7.0.3
+version: 7.0.4
cabal-version: 1.18
-tested-with: GHC==7.10.3, GHC==8.0.2, GHC==8.2.2, GHC==8.4.4, GHC==8.6.1
+tested-with: GHC==7.10.3, GHC==8.0.2, GHC==8.2.2, GHC==8.4.4, GHC==8.6.2
license: BSD2
license-file: LICENSE.md
author: Megaparsec contributors,