typo: than -> then
[packages/parsec.git] / README.md
1 Parsec [![Build Status](https://travis-ci.org/haskell/parsec.svg?branch=master)](https://travis-ci.org/haskell/parsec)
2 ======
3
4 A monadic parser combinator library, written by Daan Leijen. Parsec is designed
5 from scratch as an industrial-strength parser library. It is simple, safe, well
6 documented, has extensive libraries, good error messages, and is fast.
7
8 Some links:
9
10 * [Parsec on Hackage](https://hackage.haskell.org/package/parsec),
11   contains the generated documentation.
12 * The 2001 paper written by Daan Leijen, some what outdated
13   ([PDF](https://web.archive.org/web/20140528151730/http://legacy.cs.uu.nl/daan/download/parsec/parsec.pdf),
14   [HTML](https://web.archive.org/web/20140528151730/http://legacy.cs.uu.nl/daan/download/parsec/parsec.html),
15   thanks to [archive.org](http://web.archive.org);
16   and [PDF](https://research.microsoft.com/en-us/um/people/daan/download/parsec/parsec.pdf),
17   thanks to Microsoft Research).
18 * [Using Parsec](http://book.realworldhaskell.org/read/using-parsec.html),
19   chapter 16 of [Real World Haskell](http://book.realworldhaskell.org/).
20 * [An introduction to the Parsec library](http://kunigami.wordpress.com/2014/01/21/an-introduction-to-the-parsec-library)
21   on Kunigami's blog.
22 * [An introduction to parsing text in Haskell with Parsec](http://unbui.lt/#!/post/haskell-parsec-basics) on Wilson's blog.
23 * Differences between Parsec and
24   [Attoparsec](http://hackage.haskell.org/package/attoparsec)
25   (Haskell's other prominent parser library) as explained in
26   [an answer on StackExchange](http://stackoverflow.com/a/19213247).
27 * Differences between Parsec and [Happy](http://www.haskell.org/happy)
28   (Haskell's parser generator) as explained in two
29   answers on separate StackExchange questions
30   ([1](http://stackoverflow.com/a/7270904),
31   [2](http://stackoverflow.com/a/14775331)).
32 * Differences between Parsec and
33   [Megaparsec](http://hackage.haskell.org/package/megaparsec)
34   (an advanced fork of Parsec) as explained in
35   [Megaparsec's README](https://github.com/mrkkrp/megaparsec#megaparsec-vs-parsec).
36
37
38 By analyzing [Parsec's reverse dependencies on Hackage](http://packdeps.haskellers.com/reverse/parsec)
39 we can find open source project that make use of Parsec.  For example
40 [bibtex](http://hackage.haskell.org/package/bibtex),
41 [ConfigFile](http://hackage.haskell.org/package/ConfigFile),
42 [csv](http://hackage.haskell.org/package/csv) and
43 [hjson](http://hackage.haskell.org/package/hjson).
44
45
46 ## Getting started
47
48 This requires a working version of `cabal` and `ghci`, which are part of
49 any modern installation of Haskell, such as
50 [Haskell Platform](https://www.haskell.org/platform).
51
52 First install Parsec.
53
54     cabal install parsec
55
56 Below we show how a very simple parser that tests matching parentheses
57 was made from GHCI (the interactive GHC environment), which we started
58 with the `ghci` command).
59
60 ```
61 Prelude> :m +Text.Parsec
62 Prelude Text.Parsec> let parenSet = char '(' >> many parenSet >> char ')' :: Parsec String () Char
63 Loading package transformers-0.3.0.0 ... linking ... done.
64 Loading package array-0.5.0.0 ... linking ... done.
65 Loading package deepseq-1.3.0.2 ... linking ... done.
66 Loading package bytestring-0.10.4.0 ... linking ... done.
67 Loading package mtl-2.1.3.1 ... linking ... done.
68 Loading package text-1.1.1.3 ... linking ... done.
69 Loading package parsec-3.1.5 ... linking ... done.
70 Prelude Text.Parsec> let parens = (many parenSet >> eof) <|> eof
71 Prelude Text.Parsec> parse parens "" "()"
72 Right ()
73 Prelude Text.Parsec> parse parens "" "()(())"
74 Right ()
75 Prelude Text.Parsec> parse parens "" "("
76 Left (line 1, column 2):
77 unexpected end of input
78 expecting "(" or ")"
79 ```
80
81 The `Right ()` results indicate successes: the parentheses matched.
82 The `Left [...]` result indicates a parse failure, and is detailed
83 with an error message.
84
85 For a more thorough introduction to Parsec we recommend the links at
86 the top of this README file.
87
88
89 ## Contributing
90
91 Issues (bugs, feature requests or otherwise feedback) may be reported in
92 [the Github issue tracker for this project](https://github.com/haskell/parsec/issues).
93
94 Pull-requests are also welcome.
95
96
97 ## License
98
99 See the [LICENSE](https://github.com/haskell/parsec/blob/master/LICENSE)
100 file in the repository.