Data.Csv.Incremental

This module allows for incremental decoding of CSV data. This is useful if you e.g. want to interleave I/O with parsing or if you want finer grained control over how you deal with type conversion errors.

Decoding headers

data HeaderParser a

An incremental parser that when fed data eventually returns a parsed Header, or an error.

Constructors

FailH !ByteString String

The input data was malformed. The first field contains any unconsumed input and second field contains information about the parse error.

PartialH (ByteString -> HeaderParser a)

The parser needs more input data before it can produce a result. Use an empty string to indicate that no more input data is available. If fed an 'B.empty string', the continuation is guaranteed to return either FailH or DoneH.

DoneH !Header a

The parse succeeded and produced the given Header.

Instances

Functor HeaderParser

Show a => Show (HeaderParser a)

decodeHeader :: HeaderParser ByteString

Parse a CSV header in an incremental fashion. When done, the HeaderParser returns any unconsumed input in the second field of the DoneH constructor.

decodeHeaderWith :: DecodeOptions -> HeaderParser ByteString

Like decodeHeader, but lets you customize how the CSV data is parsed.

Providing input

These functions are sometimes convenient when working with HeaderParser, but don't let you do anything you couldn't already do using the HeaderParser constructors directly.

feedChunkH :: HeaderParser a -> ByteString -> HeaderParser a

Feed a HeaderParser with more input. If the HeaderParser is FailH it will add the input to ByteString of unconsumed input. If the HeaderParser is DoneH it will drop the extra input on the floor.

feedEndOfInputH :: HeaderParser a -> HeaderParser a

Tell a HeaderParser that there is no more input. This passes empty to a PartialH parser, otherwise returns the parser unchanged.

Decoding records

Just like in the case of non-incremental decoding, there are two ways to convert CSV records to and from and user-defined data types: index-based conversion and name-based conversion.

data Parser a

An incremental parser that when fed data eventually produces some parsed records, converted to the desired type, or an error in case of malformed input data.

Constructors

Fail !ByteString String

The input data was malformed. The first field contains any unconsumed input and second field contains information about the parse error.

Partial (ByteString -> Parser a)

The parser needs more input data before it can produce a result. Use an empty string to indicate that no more input data is available. If fed an empty string, the continuation is guaranteed to return either Fail or Done.

Some [Either String a] (ByteString -> Parser a)

The parser parsed and converted some records. Any records that failed type conversion are returned as Left errMsg and the rest as Right val. Feed a ByteString to the continuation to continue parsing. Use an empty string to indicate that no more input data is available. If fed an empty string, the continuation is guaranteed to return either Fail or Done.

Done [Either String a]

The parser parsed and converted some records. Any records that failed type conversion are returned as Left errMsg and the rest as Right val.

Instances

Functor Parser

Show a => Show (Parser a)

Index-based record conversion

See documentation on index-based conversion in Data.Csv for more information.

decode

Arguments

:: FromRecord a

=> Bool

Data contains header that should be skipped

-> Parser a

Efficiently deserialize CSV in an incremental fashion. Equivalent to decodeWith defaultDecodeOptions.

decodeWith

Arguments

:: FromRecord a

=> DecodeOptions

Decoding options

-> Bool

Data contains header that should be skipped

-> Parser a

Like decode, but lets you customize how the CSV data is parsed.

Name-based record conversion

See documentation on name-based conversion in Data.Csv for more information.

decodeByName :: FromNamedRecord a => HeaderParser (Parser a)

Efficiently deserialize CSV in an incremental fashion. The data is assumed to be preceeded by a header. Returns a HeaderParser that when done produces a Parser for parsing the actual records. Equivalent to decodeByNameWith defaultDecodeOptions.

decodeByNameWith

Arguments

:: FromNamedRecord a

=> DecodeOptions

Decoding options

-> HeaderParser (Parser a)

Like decodeByName, but lets you customize how the CSV data is parsed.

Providing input

These functions are sometimes convenient when working with Parser, but don't let you do anything you couldn't already do using the Parser constructors directly.

feedChunk :: Parser a -> ByteString -> Parser a

Feed a Parser with more input. If the Parser is Fail it will add the input to ByteString of unconsumed input. If the Parser is Done it will drop the extra input on the floor.

feedEndOfInput :: Parser a -> Parser a

Tell a Parser that there is no more input. This passes empty to a Partial parser, otherwise returns the parser unchanged.