cassava

https://www.stackage.org/package/cassava
Admin
cassava is a Haskell CSV parsing and encoding library that provides fast and efficient CSV handling...
Tokens:4,191
Snippets:60
Trust Score:9.5
Update:5 months ago
Show doc for...
Tokens:
Raw
### Building the examples project with Cabal

Source: https://www.stackage.org/package/cassava-conduit

Instructions for setting up and building the example project using Cabal, including initializing a sandbox, adding the local package, and installing dependencies.

```bash
$ cd examples
$ cabal sandbox init
$ cabal sandbox add-source ../
$ cabal install --only-dependencies
$ cabal build

```

--------------------------------

### Building the project with Mafia

Source: https://www.stackage.org/package/cassava-conduit

Command to build the project using the 'mafia' build tool.

```bash
./mafia build

```

--------------------------------

### Running Unit Tests with Mafia

Source: https://www.stackage.org/package/cassava-conduit

Command to execute unit tests for the project using the 'mafia' tool.

```bash
./mafia test

```

--------------------------------

### Importing Cassava-Megaparsec Parsers

Source: https://www.stackage.org/package/cassava-megaparsec

To use the Megaparsec-based parsers, import them from `Data.Csv.Parser.Megaparsec` while hiding the original Cassava functions to avoid name clashes.

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

--------------------------------

### Basic CSV Parsing Functions

Source: https://www.stackage.org/package/cassava-conduit

Provides basic functions for parsing CSV data. `fromNamedCsv` parses named records, while `fromNamedCsvStreamError` handles stream errors for named records. These are foundational for CSV processing with Cassava.

```haskell
fromNamedCsv :: (Show a, Monad m, FromNamedRecord a, MonadError CsvParseError m) => DecodeOptions -> Conduit BS.ByteString m a
fromNamedCsvStreamError :: (Monad m, FromNamedRecord a) => DecodeOptions -> Conduit BS.ByteString m (Either CsvParseError a)


```

--------------------------------

### Parse CSV Records With Header

Source: https://www.stackage.org/package/cassava

Use `decodeByName` to parse CSV data when a header row is present. This requires defining a data type with a `FromNamedRecord` instance to map header fields to record fields.

```haskell
{-# LANGUAGE OverloadedStrings #-}

import Control.Applicative
import qualified Data.ByteString.Lazy as BL
import Data.Csv
import qualified Data.Vector as V

data Person = Person
    {
      name   :: !String
    , salary :: !Int
    }

instance FromNamedRecord Person where
    parseNamedRecord r = Person <$> r .: "name" <*> r .: "salary"

main :: IO ()
main = do
    csvData <- BL.readFile "salaries.csv"
    case decodeByName csvData of
        Left err -> putStrLn err
        Right (_, v) -> V.forM_ v $ \ p ->
            putStrLn $ name p ++ " earns " ++ show (salary p) ++ " dollars"
```

--------------------------------

### Parse CSV Records Without Header

Source: https://www.stackage.org/package/cassava

Use `decode` to parse CSV data record by record when no header is present. Ensure the data types in the record match the expected types for parsing.

```haskell
{-# LANGUAGE ScopedTypeVariables #-}

import qualified Data.ByteString.Lazy as BL
import Data.Csv
import qualified Data.Vector as V

main :: IO ()
main = do
    csvData <- BL.readFile "salaries.csv"
    case decode NoHeader csvData of
        Left err -> putStrLn err
        Right v -> V.forM_ v $ \ (name, salary :: Int) ->
            putStrLn $ name ++ " earns " ++ show salary ++ " dollars"
```

--------------------------------

### CSV Stream Parsing with Error Handling

Source: https://www.stackage.org/package/cassava-conduit

Provides functions for parsing CSV data from a stream, allowing for custom error handling. `fromCsvStreamError` handles stream-halting errors, while `fromNamedCsvStreamError` is for named records. Both require a function to convert `CsvStreamHaltParseError` into a monad's error type.

```haskell
-- |
-- Same as `fromCsv` but allows for errors to be handled in the pipeline instead
--
fromCsvStreamError :: (FromRecord a, MonadError e m) => DecodeOptions -> HasHeader -> (CsvStreamHaltParseError -> e) -> Conduit BS.ByteString m (Either CsvStreamRecordParseError a)
fromCsvStreamError opts h f = {-# SCC fromCsvStreamError_p #-} streamParser f $ decodeWith opts h

-- |
-- Like `fromNamedCsvStream` but allows for errors to be handled in the pipeline itself.
--
fromNamedCsvStreamError :: (FromNamedRecord a, MonadError e m) => DecodeOptions -> (CsvStreamHaltParseError -> e) -> Conduit BS.ByteString m (Either CsvStreamRecordParseError a)
fromNamedCsvStreamError opts f = {-# SCC fromCsvStreamError_p #-} streamHeaderParser f $ decodeByNameWith opts


```

--------------------------------

### CSV Processing Conduit Pipeline

Source: https://www.stackage.org/package/cassava-conduit

This pipeline streams data from a pipe-separated file, decodes it, processes each record, encodes it back to pipe-separated format, and saves it to another file. It stops on the first parse error, dropping records from that batch.

```haskell
import Data.Csv
import Data.Conduit
import Data.Csv.Conduit

data InputRecord = ...

instance FromRecord InputRecord where
    ...

data OutputRecord = ...

instance ToRecord OutputRecord where
    ...

decodeOpts :: Word8 -> DecodeOptions

encodeOpts :: Word8 -> EncodeOptions

processInput :: InputRecord -> OutputRecord

-- |
--  A Conduit pipeline that streams from '../exampledata/sampleinput.psv', decodes it from a pipe seperated format,
--  processes it with 'processInput' and the encodes it to pipe seperated format and streams it out to '../exampledata/sampleoutput.psv'
--  The first time it encounters a parse error, it will stop streaming and return the error, dropping any decoded records that came through in that batch also...
--
conduitPipeline :: (MonadError CsvParseError m, MonadResource m) => m ()
conduitPipeline = sourceFile "../exampledata/sampleinput.psv" $$ fromCsv (decodeOpts $ fromIntegral $ ord '|') HasHeader =$= map processInput =$= toCsv (encodeOpts $ fromIntegral $ ord '|') =$= sinkFile "../exampledata/sampleoutput.psv"

main :: IO ()
main = do
    res <- runEitherT $ bimapEitherT showError id $ runResourceT conduitPipeline
    either putStrLn return res

```

--------------------------------

### Lift CSV Parse Errors into Monad

Source: https://www.stackage.org/package/cassava-conduit

Functions to lift `CsvParseError` into a monad's error type. Use `fromCsvLiftError` for standard records and `fromNamedCsvLiftError` for named records. These are useful when integrating Cassava parsing with existing monadic error handling.

```haskell
fromCsvLiftError :: (FromRecord a, MonadError e m) => (CsvParseError -> e) -> DecodeOptions -> HasHeader -> Conduit BS.ByteString m a
fromNamedCsvLiftError :: (FromNamedRecord a, MonadError e m) => (CsvParseError -> e) -> DecodeOptions -> Conduit BS.ByteString m a


```

--------------------------------

### Custom Error Component for CSV Parsing

Source: https://www.stackage.org/package/cassava-megaparsec

Defines a custom error component `Cec` for typed reporting of conversion errors in CSV parsing. This includes specific error types like `CecFail`, `CecIndentation`, and `CecConversionError`.

```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)
```

--------------------------------

### Define Cassava CSV Parse Error Types

Source: https://www.stackage.org/package/cassava-conduit

Defines custom data types for CSV parsing errors, distinguishing between errors that halt the entire stream and those that affect individual records. Use these when implementing custom error handling for CSV processing.

```haskell
data CsvParseError =
        CsvParseError BS.ByteString T.Text
    |   IncrementalError T.Text
        deriving (Show, Eq)

-- | When you want to include errors in the stream, this error type represents errors that halt the stream.
-- They do not appear inside the conduit and will instead get returned from running the conduit.
--
data CsvStreamHaltParseError = HaltingCsvParseError BS.ByteString T.Text -- ^ the remaining bytestring that was read in but not parsed yet, and the stringy error msg describing the fail.
    deriving (Show, Eq)

-- | When you want to include errors in the stream, these are the errors that can be included in the stream,
-- they are usually problems restricted to individual records, and streaming can resume from the next record
-- you just have to decide on something sensible to do with the per record errors.
--
data CsvStreamRecordParseError = CsvStreamRecordParseError T.Text deriving (Show, Eq) -- ^ The stringy error describing why this record could not be parsed.


```
Tokens:
Raw