# Cassava Megaparsec

[![All Contributors](https://img.shields.io/badge/all_contributors-8-orange.svg?style=flat-square)](#contributors-)


[![License MIT](https://img.shields.io/badge/license-MIT-brightgreen.svg)](http://opensource.org/licenses/MIT)
[![Hackage](https://img.shields.io/hackage/v/cassava-megaparsec.svg?style=flat)](https://hackage.haskell.org/package/cassava-megaparsec)
[![Stackage Nightly](http://stackage.org/package/cassava-megaparsec/badge/nightly)](http://stackage.org/nightly/package/cassava-megaparsec)
[![Stackage LTS](http://stackage.org/package/cassava-megaparsec/badge/lts)](http://stackage.org/lts/package/cassava-megaparsec)
![Build Status](https://github.com/stackbuilders/cassava-megaparsec/actions/workflows/build.yml/badge.svg)

The package provides alternative parser for the
[Cassava](https://hackage.haskell.org/package/cassava) package written with
[Megaparsec](https://hackage.haskell.org/package/megaparsec) so you can get
better error messages at expense of some speed.

## Quick start

The package works seamlessly with Cassava by replacing the following
functions:

* `decode`
* `decodeWith`
* `decodeByName`
* `decodeByNameWith`

The functions work just the same as Cassava's equivalents, but also take
name of file they parse (to include into error messages) and return typed
high-quality error messages produced by
[Megaparsec](https://hackage.haskell.org/package/megaparsec).

The import section typically looks like this:

```haskell
import Data.Csv hiding (decode, decodeWith, decodeByName, decodeByNameWith)
import Data.Csv.Parser.Megaparsec (decode, decodeWith, decodeByName, decodeByNameWith)
```

Next you call appropriate function and get either result of parsing
identical to that of Cassava or error message. The error message is
well-typed so you can examine it in Haskell code easily. Conversion error
are considered parsing errors by the `cassava-megaparsec` package and are
reported via custom error message component `Cec` supported by Megaparsec 5.
Since Cassava's conversion errors are plain strings, we have no choice but
to represent them as strings too:

```haskell
-- | Custom error component for CSV parsing. It allows typed reporting of
-- conversion errors.

data Cec
  = CecFail String
  | CecIndentation Ordering Pos Pos
  | CecConversionError String
  deriving (Eq, Data, Typeable, Ord, Read, Show)
```

To pretty print a error message use the `parseErrorPretty` function from
`Text.Megaparsec`.

This should be enough to start using the package, please consult Haddocks
for detailed per-function documentation.

## Contributors ✨

Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

       Mark Karpov
Mark Karpov (https://markkarpov.com/)
💻 (https://github.com/stackbuilders/cassava-megaparsec/commits?author=mrkkrp)
       William R. Arellano
William R. Arellano (https://github.com/cptrodolfox)
💻 (https://github.com/stackbuilders/cassava-megaparsec/commits?author=cptrodolfox)
       Cristhian Motoche
Cristhian Motoche (https://cristhianmotoche.github.io/)
💻 (https://github.com/stackbuilders/cassava-megaparsec/commits?author=CristhianMotoche)
       Andrés Martínez
Andrés Martínez (https://github.com/aemartinez37)
💻 (https://github.com/stackbuilders/cassava-megaparsec/commits?author=aemartinez37)
       ˌbodʲɪˈɡrʲim
ˌbodʲɪˈɡrʲim (https://github.com/Bodigrim)
💻 (https://github.com/stackbuilders/cassava-megaparsec/commits?author=Bodigrim)
       Felix Yan
Felix Yan (https://g0v.social/@felixonmars)
💻 (https://github.com/stackbuilders/cassava-megaparsec/commits?author=felixonmars)
       Jorge Guerra Landázuri
Jorge Guerra Landázuri (https://github.com/Jagl257)
💻 (https://github.com/stackbuilders/cassava-megaparsec/commits?author=Jagl257)

       Justin S. Leitgeb
Justin S. Leitgeb (https://www.stackbuilders.com/news/author/justin-leitgeb)
💻 (https://github.com/stackbuilders/cassava-megaparsec/commits?author=jsl)

This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!

## License

MIT, see [the LICENSE file](LICENSE).

## Contributing

Do you want to contribute to this project? Please take a look at our [contributing guideline](/docs/CONTRIBUTING.md) to know how you can help us build it.

---
Stack Builders  
[Check out our libraries](https://github.com/stackbuilders/) | [Join our team](https://www.stackbuilders.com/join-us/)
