{"id":13821336,"url":"https://github.com/mrkkrp/megaparsec","last_synced_at":"2025-04-29T18:22:41.383Z","repository":{"id":35470664,"uuid":"39738971","full_name":"mrkkrp/megaparsec","owner":"mrkkrp","description":"Industrial-strength monadic parser combinator library","archived":false,"fork":false,"pushed_at":"2025-01-31T14:08:11.000Z","size":2617,"stargazers_count":941,"open_issues_count":20,"forks_count":91,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-04-22T04:38:15.615Z","etag":null,"topics":["haskell","megaparsec","parser-library"],"latest_commit_sha":null,"homepage":"","language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mrkkrp.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-07-26T19:33:53.000Z","updated_at":"2025-04-15T13:07:32.000Z","dependencies_parsed_at":"2024-04-26T13:28:49.436Z","dependency_job_id":"376a5607-441b-45b9-8cc8-2bb40d5d7ed6","html_url":"https://github.com/mrkkrp/megaparsec","commit_stats":{"total_commits":917,"total_committers":74,"mean_commits":"12.391891891891891","dds":0.4994547437295529,"last_synced_commit":"8d1f5cc35e317b57d67dab0914713741d6cefe0b"},"previous_names":[],"tags_count":55,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrkkrp%2Fmegaparsec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrkkrp%2Fmegaparsec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrkkrp%2Fmegaparsec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrkkrp%2Fmegaparsec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mrkkrp","download_url":"https://codeload.github.com/mrkkrp/megaparsec/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251556917,"owners_count":21608543,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["haskell","megaparsec","parser-library"],"created_at":"2024-08-04T08:01:20.230Z","updated_at":"2025-04-29T18:22:41.364Z","avatar_url":"https://github.com/mrkkrp.png","language":"Haskell","funding_links":[],"categories":["Haskell"],"sub_categories":[],"readme":"# Megaparsec\n\n[![License FreeBSD](https://img.shields.io/badge/license-FreeBSD-brightgreen.svg)](http://opensource.org/licenses/BSD-2-Clause)\n[![Hackage](https://img.shields.io/hackage/v/megaparsec.svg?style=flat)](https://hackage.haskell.org/package/megaparsec)\n[![Stackage Nightly](http://stackage.org/package/megaparsec/badge/nightly)](http://stackage.org/nightly/package/megaparsec)\n[![Stackage LTS](http://stackage.org/package/megaparsec/badge/lts)](http://stackage.org/lts/package/megaparsec)\n[![CI](https://github.com/mrkkrp/megaparsec/actions/workflows/ci.yaml/badge.svg)](https://github.com/mrkkrp/megaparsec/actions/workflows/ci.yaml)\n\n* [Features](#features)\n    * [Core features](#core-features)\n    * [Error messages](#error-messages)\n    * [External lexers](#external-lexers)\n    * [Character and binary parsing](#character-and-binary-parsing)\n    * [Lexer](#lexer)\n* [Documentation](#documentation)\n* [Tutorials](#tutorials)\n* [Performance](#performance)\n* [Comparison with other solutions](#comparison-with-other-solutions)\n    * [Megaparsec vs Attoparsec](#megaparsec-vs-attoparsec)\n    * [Megaparsec vs Parsec](#megaparsec-vs-parsec)\n    * [Megaparsec vs Trifecta](#megaparsec-vs-trifecta)\n    * [Megaparsec vs Earley](#megaparsec-vs-earley)\n* [Related packages](#related-packages)\n* [Prominent projects that use Megaparsec](#prominent-projects-that-use-megaparsec)\n* [Links to announcements and blog posts](#links-to-announcements-and-blog-posts)\n* [Contribution](#contribution)\n* [License](#license)\n\nThis is an industrial-strength monadic parser combinator library. Megaparsec\nis a feature-rich package that tries to find a nice balance between speed,\nflexibility, and quality of parse errors.\n\n## Features\n\nThe project provides flexible solutions to satisfy common parsing needs. The\nsection describes them shortly. If you're looking for comprehensive\ndocumentation, see the [section about documentation](#documentation).\n\n### Core features\n\nThe package is built around `MonadParsec`, an MTL-style monad transformer.\nMost features work with all instances of `MonadParsec`. One can achieve\nvarious effects combining monad transformers, i.e. building a monadic stack.\nSince the common monad transformers like `WriterT`, `StateT`, `ReaderT` and\nothers are instances of the `MonadParsec` type class, one can also wrap\n`ParsecT` *in* these monads, achieving, for example, backtracking state.\n\nOn the other hand `ParsecT` is an instance of many type classes as well. The\nmost useful ones are `Monad`, `Applicative`, `Alternative`, and\n`MonadParsec`.\n\nMegaparsec includes all functionality that is typically available in\nParsec-like libraries and also features some special combinators:\n\n* `parseError` allows us to end parsing and report an arbitrary parse error.\n* `withRecovery` can be used to recover from parse errors “on-the-fly” and\n  continue parsing. Once parsing is finished, several parse errors may be\n  reported or ignored altogether.\n* `observing` makes it possible to “observe” parse errors without ending\n  parsing.\n\nIn addition to that, Megaparsec features high-performance combinators\nsimilar to those found in [Attoparsec][attoparsec]:\n\n* `tokens` makes it easy to parse several tokens in a row (`string` and\n  `string'` are built on top of this primitive). This is about 100 times\n  faster than matching a string token by token. `tokens` returns “chunk” of\n  original input, meaning that if you parse `Text`, it'll return `Text`\n  without repacking.\n* `takeWhile` and `takeWhile1` are about 150 times faster than approaches\n  involving `many`, `manyTill` and other similar combinators.\n* `takeP` allows us to grab n tokens from the stream and returns them as a\n  “chunk” of the stream.\n\nMegaparsec is about as fast as Attoparsec if you write your parser carefully\n(see also [the section about performance](#performance)).\n\nThe library can currently work with the following types of input stream\nout-of-the-box:\n\n* `String = [Char]`\n* `ByteString` (strict and lazy)\n* `Text` (strict and lazy)\n\nIt's also possible to make it work with custom token streams by making them\nan instance of the `Stream` type class.\n\n### Error messages\n\n* Megaparsec has typed error messages and the ability to signal custom parse\n  errors that better suit the user's domain of interest.\n\n* Since version 8, the location of parse errors can independent of current\n  offset in the input stream. It is useful when you want a parse error to\n  point to a particular position after performing some checks.\n\n* Instead of a single parse error Megaparsec produces so-called\n  `ParseErrorBundle` data type that helps to manage multi-error messages and\n  pretty-print them. Since version 8, reporting multiple parse errors at\n  once has become easier.\n\n### External lexers\n\nMegaparsec works well with streams of tokens produced by tools like Alex.\nThe design of the `Stream` type class has been changed significantly in the\nrecent versions, but user can still work with custom streams of tokens.\n\n### Character and binary parsing\n\nMegaparsec has decent support for Unicode-aware character parsing. Functions\nfor character parsing live in the [`Text.Megaparsec.Char`][tm-char] module.\nSimilarly, there is [`Text.Megaparsec.Byte`][tm-byte] module for parsing\nstreams of bytes.\n\n### Lexer\n\n[`Text.Megaparsec.Char.Lexer`][tm-char-lexer] is a module that should help\nyou write your lexer. If you have used `Parsec` in the past, this module\n“fixes” its particularly inflexible `Text.Parsec.Token`.\n\n[`Text.Megaparsec.Char.Lexer`][tm-char-lexer] is intended to be imported\nusing a qualified import, it's not included in [`Text.Megaparsec`][tm]. The\nmodule doesn't impose how you should write your parser, but certain\napproaches may be more elegant than others. An especially important theme is\nparsing of white space, comments, and indentation.\n\nThe design of the module allows one quickly solve simple tasks and doesn't\nget in the way when the need to implement something less standard arises.\n\n[`Text.Megaparsec.Byte.Lexer`][tm-byte-lexer] is also available for users\nwho wish to parse binary data.\n\n## Documentation\n\nMegaparsec is well-documented. See the [current version of Megaparsec\ndocumentation on Hackage][hackage].\n\n## Tutorials\n\nYou can find the most complete Megaparsec tutorial [here][the-tutorial]. It\nshould provide sufficient guidance to help you start with your parsing\ntasks.\n\n## Performance\n\nDespite being flexible, Megaparsec is also fast. Here is how Megaparsec\ncompares to [Attoparsec][attoparsec] (the fastest widely used parsing\nlibrary in the Haskell ecosystem):\n\nTest case         | Execution time | Allocated | Max residency\n------------------|---------------:|----------:|-------------:\nCSV (Attoparsec)  |       76.50 μs |   397,784 |        10,544\nCSV (Megaparsec)  |       64.69 μs |   352,408 |         9,104\nLog (Attoparsec)  |       302.8 μs | 1,150,032 |        10,912\nLog (Megaparsec)  |       337.8 μs | 1,246,496 |        10,912\nJSON (Attoparsec) |       18.20 μs |   128,368 |         9,032\nJSON (Megaparsec) |       25.45 μs |   203,824 |         9,176\n\nYou can run the benchmarks yourself by executing:\n\n```\n$ nix-build -A benches.parsers-bench\n$ cd result/bench\n$ ./bench-memory\n$ ./bench-speed\n```\n\nMore information about benchmarking and development can be found\n[here][hacking].\n\n## Comparison with other solutions\n\nThere are quite a few libraries that can be used for parsing in Haskell,\nlet's compare Megaparsec with some of them.\n\n### Megaparsec vs Attoparsec\n\n[Attoparsec][attoparsec] is another prominent Haskell library for parsing.\nAlthough both libraries deal with parsing, it's usually easy to decide which\nyou will need in particular project:\n\n* *Attoparsec* is sometimes faster but not that feature-rich. It should be\n  used when you want to process large amounts of data where performance\n  matters more than quality of error messages.\n\n* *Megaparsec* is good for parsing of source code or other human-readable\n  texts. It has better error messages and it's implemented as a monad\n  transformer.\n\nSo, if you work with something human-readable where the size of input data\nis moderate, it makes sense to go with Megaparsec, otherwise Attoparsec may\nbe a better choice.\n\n### Megaparsec vs Parsec\n\nSince Megaparsec is a fork of [Parsec][parsec], we are bound to list the\nmain differences between the two libraries:\n\n* Better error messages. Megaparsec has typed error messages and custom\n  error messages, it can also report multiple parse errors at once.\n\n* Megaparsec can show the line on which parse error happened as part of\n  parse error. This makes it a lot easier to figure out where the error\n  happened.\n\n* Some quirks and bugs of Parsec are fixed.\n\n* Better support for Unicode parsing in [`Text.Megaparsec.Char`][tm-char].\n\n* Megaparsec has more powerful combinators and can parse languages where\n  indentation matters.\n\n* Better documentation.\n\n* Megaparsec can recover from parse errors “on the fly” and continue\n  parsing.\n\n* Megaparsec allows us to conditionally process parse errors inside a\n  running parser. In particular, it's possible to define regions in which\n  parse errors, should they happen, will get a “context tag”, e.g. we could\n  build a context stack like “in function definition foo”, “in expression\n  x”, etc.\n\n* Megaparsec is faster and supports efficient operations `tokens`,\n  `takeWhileP`, `takeWhile1P`, `takeP`, like Attoparsec.\n\nIf you want to see a detailed change log, `CHANGELOG.md` may be helpful.\nAlso see [this original announcement][original-announcement] for another\ncomparison.\n\n### Megaparsec vs Trifecta\n\n[Trifecta][trifecta] is another Haskell library featuring good error\nmessages. These are the common reasons why Trifecta may be problematic to\nuse:\n\n* Complicated, doesn't have any tutorials available, and documentation\n  doesn't help much.\n\n* Trifecta can parse `String` and `ByteString` natively, but not `Text`.\n\n* Depends on `lens`, which is a very heavy dependency. If you're not into\n  `lens`, you may not like the API.\n\n[Idris][idris] has switched from Trifecta to Megaparsec which allowed it to\n[have better error messages and fewer dependencies][idris-testimony].\n\n### Megaparsec vs Earley\n\n[Earley][earley] is a newer library that allows us to safely parse\ncontext-free grammars (CFG). Megaparsec is a lower-level library compared to\nEarley, but there are still enough reasons to choose it:\n\n* Megaparsec is faster.\n\n* Your grammar may be not context-free or you may want introduce some sort\n  of state to the parsing process. Almost all non-trivial parsers require\n  state. Even if your grammar is context-free, state may allow for\n  additional niceties. Earley does not support that.\n\n* Megaparsec's error messages are more flexible allowing to include\n  arbitrary data in them, return multiple error messages, mark regions that\n  affect any error that happens in those regions, etc.\n\nIn other words, Megaparsec is less safe but also more powerful.\n\n## Related packages\n\nThe following packages are designed to be used with Megaparsec (open a PR if\nyou want to add something to the list):\n\n* [`hspec-megaparsec`](https://hackage.haskell.org/package/hspec-megaparsec)—utilities\n  for testing Megaparsec parsers with with\n  [Hspec](https://hackage.haskell.org/package/hspec).\n* [`replace-megaparsec`](https://hackage.haskell.org/package/replace-megaparsec)—Stream\n  editing and find-and-replace with Megaparsec.\n* [`cassava-megaparsec`](https://hackage.haskell.org/package/cassava-megaparsec)—Megaparsec\n  parser of CSV files that plays nicely with\n  [Cassava](https://hackage.haskell.org/package/cassava).\n* [`tagsoup-megaparsec`](https://hackage.haskell.org/package/tagsoup-megaparsec)—a\n  library for easily using\n  [TagSoup](https://hackage.haskell.org/package/tagsoup) as a token type in\n  Megaparsec.\n* [`parser-combinators`](https://hackage.haskell.org/package/parser-combinators)—provides permutation and expression parsers [previously bundled with Megaparsec](https://markkarpov.com/post/megaparsec-7.html#parsercombinators-grows-megaparsec-shrinks).\n* [`faster-megaparsec`](https://hackage.haskell.org/package/faster-megaparsec)—speeds up parsing\n  by trying a simple `MonadParsec` instance and falls back to `ParsecT` to report errors.\n\n## Prominent projects that use Megaparsec\n\nSome prominent projects that use Megaparsec:\n\n* [Idris](https://github.com/idris-lang/Idris-dev)—a general-purpose\n  functional programming language with dependent types\n* [Dhall](https://github.com/dhall-lang/dhall-haskell)—an advanced\n  configuration language\n* [hnix](https://github.com/haskell-nix/hnix)—re-implementation of the Nix\n  language in Haskell\n* [Hledger](https://github.com/simonmichael/hledger)—an accounting tool\n* [MMark](https://github.com/mmark-md/mmark)—strict markdown processor for\n  writers\n\n## Links to announcements and blog posts\n\nHere are some blog posts mainly announcing new features of the project and\ndescribing what sort of things are now possible:\n\n* [Megaparsec 8](https://markkarpov.com/post/megaparsec-8.html)\n* [Megaparsec 7](https://markkarpov.com/post/megaparsec-7.html)\n* [Evolution of error messages](https://markkarpov.com/post/evolution-of-error-messages.html)\n* [A major upgrade to Megaparsec: more speed, more power](https://markkarpov.com/post/megaparsec-more-speed-more-power.html)\n* [Latest additions to Megaparsec](https://markkarpov.com/post/latest-additions-to-megaparsec.html)\n* [Announcing Megaparsec 5](https://markkarpov.com/post/announcing-megaparsec-5.html)\n* [Megaparsec 4 and 5](https://markkarpov.com/post/megaparsec-4-and-5.html)\n* [The original Megaparsec 4.0.0 announcement][original-announcement]\n\n## Contribution\n\nIssues (bugs, feature requests or otherwise feedback) may be reported in\n[the GitHub issue tracker for this\nproject](https://github.com/mrkkrp/megaparsec/issues).\n\nPull requests are also welcome. If you would like to contribute to the\nproject, you may find [this document][hacking] helpful.\n\n## License\n\nCopyright © 2015–present Megaparsec contributors\\\nCopyright © 2007 Paolo Martini\\\nCopyright © 1999–2000 Daan Leijen\n\nDistributed under FreeBSD license.\n\n[hackage]: https://hackage.haskell.org/package/megaparsec\n[the-tutorial]: https://markkarpov.com/tutorial/megaparsec.html\n[hacking]: ./HACKING.md\n\n[tm]: https://hackage.haskell.org/package/megaparsec/docs/Text-Megaparsec.html\n[tm-char]: https://hackage.haskell.org/package/megaparsec/docs/Text-Megaparsec-Char.html\n[tm-byte]: https://hackage.haskell.org/package/megaparsec/docs/Text-Megaparsec-Byte.html\n[tm-char-lexer]: https://hackage.haskell.org/package/megaparsec/docs/Text-Megaparsec-Char-Lexer.html\n[tm-byte-lexer]: https://hackage.haskell.org/package/megaparsec/docs/Text-Megaparsec-Byte-Lexer.html\n\n[attoparsec]: https://hackage.haskell.org/package/attoparsec\n[parsec]: https://hackage.haskell.org/package/parsec\n[trifecta]: https://hackage.haskell.org/package/trifecta\n[earley]: https://hackage.haskell.org/package/Earley\n[idris]: https://www.idris-lang.org/\n[idris-testimony]: https://twitter.com/edwinbrady/status/950084043282010117?s=09\n\n[parsers-bench]: https://github.com/mrkkrp/parsers-bench\n[fast-parser]: https://markkarpov.com/megaparsec/writing-a-fast-parser.html\n[original-announcement]: https://mail.haskell.org/pipermail/haskell-cafe/2015-September/121530.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrkkrp%2Fmegaparsec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmrkkrp%2Fmegaparsec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrkkrp%2Fmegaparsec/lists"}