Data.Csv

Options that controls how data is decoded. These options can be used to e.g. decode tab-separated data instead of comma-separated data.

To avoid having your program stop compiling when new fields are added to DecodeOptions, create option records by overriding values in defaultDecodeOptions. Example:

myOptions = defaultDecodeOptions {
      decDelimiter = fromIntegral (ord '\t')
    }

Decoding options for parsing CSV files.

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

Like decodeWith', but lets you specify a parser function.

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

Like decodeByNameWith, but lets you specify a parser function.

Options that controls how data is encoded. These options can be used to e.g. encode data in a tab-separated format instead of in a comma-separated format.

To avoid having your program stop compiling when new fields are added to EncodeOptions, create option records by overriding values in defaultEncodeOptions. Example:

myOptions = defaultEncodeOptions {
      encDelimiter = fromIntegral (ord '\t')
    }

N.B. The encDelimiter must not be the quote character (i.e. ") or one of the record separator characters (i.e. \n or \r).

Should quoting be applied to fields, and at which level?

Encoding options for CSV files.

Like encode, but lets you customize how the CSV data is encoded.

Like encodeByName, but lets you customize how the CSV data is encoded.

Like encodeDefaultOrderedByNameWith, but lets you customize how the CSV data is encoded.

A type that can be converted from a single CSV record, with the possibility of failure.

When writing an instance, use empty, mzero, or fail to make a conversion fail, e.g. if a Record has the wrong number of columns.

Given this example data:

John,56
Jane,55

here's an example type and instance:

data Person = Person { name :: !Text, age :: !Int }

instance FromRecord Person where
    parseRecord v
        | length v == 2 = Person <$>
                          v .! 0 <*>
                          v .! 1
        | otherwise     = mzero

Conversion of a field to a value might fail e.g. if the field is malformed. This possibility is captured by the Parser type, which lets you compose several field conversions together in such a way that if any of them fail, the whole record conversion fails.

Run a Parser, returning either Left errMsg or Right result. Forces the value in the Left or Right constructors to weak head normal form.

You most likely won't need to use this function directly, but it's included for completeness.

Retrieve the nth field in the given record. The result is empty if the value cannot be converted to the desired type. Raises an exception if the index is out of bounds.

index is a simple convenience function that is equivalent to parseField (v ! idx). If you're certain that the index is not out of bounds, using unsafeIndex is somewhat faster.

Alias for index.

Like index but without bounds checking.

A type that can be converted to a single CSV record.

An example type and instance:

data Person = Person { name :: !Text, age :: !Int }

instance ToRecord Person where
    toRecord (Person name age) = record [
        toField name, toField age]

Outputs data on this form:

John,56
Jane,55

Construct a record from a list of ByteStrings. Use toField to convert values to ByteStrings for use with record.

The 1-tuple type or single-value "collection".

This type is structurally equivalent to the Identity type, but its intent is more about serving as the anonymous 1-tuple type missing from Haskell for attaching typeclass instances.

Parameter usage example:

encodeSomething (Only (42::Int))

Result usage example:

xs <- decodeSomething
forM_ xs $ \(Only id) -> {- ... -}

A type that can be converted from a single CSV record, with the possibility of failure.

When writing an instance, use empty, mzero, or fail to make a conversion fail, e.g. if a Record has the wrong number of columns.

Given this example data:

name,age
John,56
Jane,55

here's an example type and instance:

{-# LANGUAGE OverloadedStrings #-}

data Person = Person { name :: !Text, age :: !Int }

instance FromNamedRecord Person where
    parseNamedRecord m = Person <$>
                         m .: "name" <*>
                         m .: "age"

Note the use of the OverloadedStrings language extension which enables ByteString values to be written as string literals.

Retrieve a field in the given record by name. The result is empty if the field is missing or if the value cannot be converted to the desired type.

Alias for lookup.

A type that can be converted to a single CSV record.

An example type and instance:

data Person = Person { name :: !Text, age :: !Int }

instance ToNamedRecord Person where
    toNamedRecord (Person name age) = namedRecord [
        "name" .= name, "age" .= age]

Construct a named record from a list of name-value ByteString pairs. Use .= to construct such a pair from a name and a value.

Construct a pair from a name and a value. For use with namedRecord.

Alias for namedField.

Construct a header from a list of ByteStrings.

A type that can be converted from a single CSV field, with the possibility of failure.

When writing an instance, use empty, mzero, or fail to make a conversion fail, e.g. if a Field can't be converted to the given type.

Example type and instance:

{-# LANGUAGE OverloadedStrings #-}

data Color = Red | Green | Blue

instance FromField Color where
    parseField s
        | s == "R"  = pure Red
        | s == "G"  = pure Green
        | s == "B"  = pure Blue
        | otherwise = mzero

A type that can be converted to a single CSV field.

Example type and instance:

{-# LANGUAGE OverloadedStrings #-}

data Color = Red | Green | Blue

instance ToField Color where
    toField Red   = "R"
    toField Green = "G"
    toField Blue  = "B"

A configurable CSV record parser. This function applied to defaultOptions is used as the default for parseRecord when the type is an instance of Generic.

A configurable CSV record creator. This function applied to defaultOptions is used as the default for toRecord when the type is an instance of Generic.

A configurable CSV named record parser. This function applied to defaultOptions is used as the default for parseNamedRecord when the type is an instance of Generic.

A configurable CSV named record creator. This function applied to defaultOptions is used as the default for toNamedRecord when the type is an instance of Generic.

A configurable CSV header record generator. This function applied to defaultOptions is used as the default for headerOrder when the type is an instance of Generic.

Options to customise how to generically encode/decode your datatype to/from CSV.

Default conversion options.

  Options
  { fieldLabelModifier = id
  }
  

How to convert Haskell field labels to CSV fields.