cassava-0.5.0.0: A CSV parsing and encoding library

Data.Csv

Description

This module implements encoding and decoding of CSV data. The implementation is RFC 4180 compliant, with the following extensions:

• Empty lines are ignored.
• Non-escaped fields may contain any characters except double-quotes, commas, carriage returns, and newlines.
• Escaped fields may contain any characters (but double-quotes need to be escaped).

Synopsis

# Usage examples

>>> encode [("John" :: Text, 27), ("Jane", 28)]
"John,27\r\nJane,28\r\n"

Since string literals are overloaded we have to supply a type signature as the compiler couldn't deduce which string type (i.e. String or Text) we want to use. In most cases type inference will infer the type from the context and you can omit type signatures.

>>> decode NoHeader "John,27\r\nJane,28\r\n" :: Either String (Vector (Text, Int))
Right [("John",27),("Jane",28)]

We pass NoHeader as the first argument to indicate that the CSV input data isn't preceded by a header.

In practice, the return type of decode rarely needs to be given, as it can often be inferred from the context.

## Encoding and decoding custom data types

To encode and decode your own data types you need to defined instances of either ToRecord and FromRecord or ToNamedRecord and FromNamedRecord. The former is used for encoding/decoding using the column index and the latter using the column name.

There are two ways to to define these instances, either by manually defining them or by using GHC generics to derive them automatically.

### Index-based record conversion

Derived:

{-# LANGUAGE DeriveGeneric #-}

data Person = Person { name :: !Text , salary :: !Int }
deriving Generic

instance FromRecord Person
instance ToRecord Person

Manually defined:

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

instance FromRecord Person where
parseRecord v
| length v == 2 = Person <$> v .! 0 <*> v .! 1 | otherwise = mzero instance ToRecord Person where toRecord (Person name age) = record [ toField name, toField age] We can now use e.g. encode and decode to encode and decode our data type. Encoding: >>> encode [Person ("John" :: Text) 27] "John,27\r\n" Decoding: >>> decode NoHeader "John,27\r\n" :: Either String (Vector Person) Right [Person {name = "John", salary = 27}] ### Name-based record conversion Derived: {-# LANGUAGE DeriveGeneric #-} data Person = Person { name :: !Text , salary :: !Int } deriving Generic instance FromNamedRecord Person instance ToNamedRecord Person instance DefaultOrdered Person Manually defined: data Person = Person { name :: !Text , salary :: !Int } instance FromNamedRecord Person where parseNamedRecord m = Person <$> m .: "name" <*> m .: "salary"
instance ToNamedRecord Person where
toNamedRecord (Person name salary) = namedRecord [
"name" .= name, "salary" .= salary]
instance DefaultOrdered Person where

We can now use e.g. encodeDefaultOrderedByName (or encodeByName with an explicit header order) and decodeByName to encode and decode our data type.

Encoding:

>>> encodeDefaultOrderedByName [Person ("John" :: Text) 27]
"name,salary\r\nJohn,27\r\n"

Decoding:

>>> decodeByName "name,salary\r\nJohn,27\r\n" :: Either String (Header, Vector Person)
Right (["name","salary"],[Person {name = "John", salary = 27}])

# Treating CSV data as opaque byte strings

Sometimes you might want to work with a CSV file which contents is unknown to you. For example, you might want remove the second column of a file without knowing anything about its content. To parse a CSV file to a generic representation, just convert each record to a Vector ByteString value, like so:

>>> decode NoHeader "John,27\r\nJane,28\r\n" :: Either String (Vector (Vector ByteString))
Right [["John","27"],["Jane","28"]]

As the example output above shows, all the fields are returned as uninterpreted ByteString values.

# Custom type conversions for fields

Most of the time the existing FromField and ToField instances do what you want. However, if you need to parse a different format (e.g. hex) but use a type (e.g. Int) for which there's already a FromField instance, you need to use a newtype. Example:

newtype Hex = Hex Int

parseHex :: ByteString -> Parser Int
parseHex = ...

instance FromField Hex where
parseField s = Hex <$> parseHex s Other than giving an explicit type signature, you can pattern match on the newtype constructor to indicate which type conversion you want to have the library use: case decode NoHeader "0xff,0xaa\r\n0x11,0x22\r\n" of Left err -> putStrLn err Right v -> forM_ v$ \ (Hex val1, Hex val2) ->
print (val1, val2)

If a field might be in one several different formats, you can use a newtype to normalize the result:

newtype HexOrDecimal = HexOrDecimal Int

instance FromField DefaultToZero where
parseField s = case runParser (parseField s :: Parser Hex) of
Left err -> HexOrDecimal <$> parseField s -- Uses Int instance Right n -> pure$ HexOrDecimal n

You can use the unit type, (), to ignore a column. The parseField method for () doesn't look at the Field and thus always decodes successfully. Note that it lacks a corresponding ToField instance. Example:

Left  err -> putStrLn err
Right n  -> pure $DefaultToZero n # Encoding and decoding Encoding and decoding is a two step process. To encode a value, it is first converted to a generic representation, using either ToRecord or ToNamedRecord. The generic representation is then encoded as CSV data. To decode a value the process is reversed and either FromRecord or FromNamedRecord is used instead. Both these steps are combined in the encode and decode functions. data HasHeader Source # Is the CSV data preceded by a header? Constructors  HasHeader The CSV data is preceded by a header NoHeader The CSV data is not preceded by a header Arguments  :: FromRecord a => HasHeader Data contains header that should be skipped -> ByteString CSV data -> Either String (Vector a) Efficiently deserialize CSV records from a lazy ByteString. If this fails due to incomplete or invalid input, Left msg is returned. Equivalent to decodeWith defaultDecodeOptions. Arguments  :: FromNamedRecord a => ByteString CSV data -> Either String (Header, Vector a) Efficiently deserialize CSV records from a lazy ByteString. If this fails due to incomplete or invalid input, Left msg is returned. The data is assumed to be preceeded by a header. Equivalent to decodeByNameWith defaultDecodeOptions. encode :: ToRecord a => [a] -> ByteString Source # Efficiently serialize CSV records as a lazy ByteString. encodeByName :: ToNamedRecord a => Header -> [a] -> ByteString Source # Efficiently serialize CSV records as a lazy ByteString. The header is written before any records and dictates the field order. encodeDefaultOrderedByName :: (DefaultOrdered a, ToNamedRecord a) => [a] -> ByteString Source # Like encodeByName, but header and field order is dictated by the header method. class DefaultOrdered a where Source # A type that has a default field order when converted to CSV. This class lets you specify how to get the headers to use for a record type that's an instance of ToNamedRecord. To derive an instance, the type is required to only have one constructor and that constructor must have named fields (also known as selectors) for all fields. Right: data Foo = Foo { foo :: !Int } Wrong: data Bar = Bar Int If you try to derive an instance using GHC generics and your type doesn't have named fields, you will get an error along the lines of: <interactive>:9:10: No instance for (DefaultOrdered (M1 S NoSelector (K1 R Char) ())) arising from a use of ‘Data.Csv.Conversion.$gdmheader’
In the expression: Data.Csv.Conversion.$gdmheader In an equation for ‘header’: header = Data.Csv.Conversion.$gdmheader
In the instance declaration for ‘DefaultOrdered Foo’

Methods

The header order for this record. Should include the names used in the NamedRecord returned by toNamedRecord. Pass undefined as the argument, together with a type annotation e.g. headerOrder (undefined :: MyRecord).

The header order for this record. Should include the names used in the NamedRecord returned by toNamedRecord. Pass undefined as the argument, together with a type annotation e.g. headerOrder (undefined :: MyRecord).

## Encoding and decoding options

These functions can be used to control how data is encoded and decoded. For example, they can be used to encode data in a tab-separated format instead of in a comma-separated format.

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')
}

Constructors

 DecodeOptions FieldsdecDelimiter :: !Word8Field delimiter.

Instances

 Source # Methods Source # MethodsshowList :: [DecodeOptions] -> ShowS #

Decoding options for parsing CSV files.

Arguments

 :: FromRecord a => DecodeOptions Decoding options -> HasHeader Data contains header that should be skipped -> ByteString CSV data -> Either String (Vector a)

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

Arguments

 :: FromNamedRecord a => DecodeOptions Decoding options -> ByteString CSV data -> Either String (Header, Vector a)

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

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

Constructors

 EncodeOptions FieldsencDelimiter :: !Word8Field delimiter.encUseCrLf :: !BoolRecord separator selection. True for CRLF (\r\n) and False for LF (\n).encIncludeHeader :: !BoolInclude a header row when encoding ToNamedRecord instances.encQuoting :: !QuotingWhat kind of quoting should be applied to text fields.

Instances

 Source # Methods Source # MethodsshowList :: [EncodeOptions] -> ShowS #

data Quoting Source #

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

Constructors

 QuoteNone No quotes. QuoteMinimal Quotes according to RFC 4180. QuoteAll Always quote.

Instances

 Source # Methods(==) :: Quoting -> Quoting -> Bool #(/=) :: Quoting -> Quoting -> Bool # Source # MethodsshowList :: [Quoting] -> ShowS #

Encoding options for CSV files.

encodeWith :: ToRecord a => EncodeOptions -> [a] -> ByteString Source #

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

encodeByNameWith :: ToNamedRecord a => EncodeOptions -> Header -> [a] -> ByteString Source #

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

encodeDefaultOrderedByNameWith :: forall a. (DefaultOrdered a, ToNamedRecord a) => EncodeOptions -> [a] -> ByteString Source #

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

# Core CSV types

CSV data represented as a Haskell vector of vector of bytestrings.

A record corresponds to a single line in a CSV file.

A single field within a record.

The header corresponds to the first line a CSV file. Not all CSV files have a header.

A header has one or more names, describing the data in the column following the name.

A record corresponds to a single line in a CSV file, indexed by the column name rather than the column index.

# Type conversion

There are two ways to convert CSV records to and from and user-defined data types: index-based conversion and name-based conversion.

## Index-based record conversion

Index-based conversion lets you convert CSV records to and from user-defined data types by referring to a field's position (its index) in the record. The first column in a CSV file is given index 0, the second index 1, and so on.

class FromRecord a where Source #

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 Methods parseRecord :: (Generic a, GFromRecord (Rep a)) => Record -> Parser a Source # Instances  FromField a => FromRecord [a] Source # Methods FromField a => FromRecord (Only a) Source # Methods FromField a => FromRecord (Vector a) Source # Methods (FromField a, Unbox a) => FromRecord (Vector a) Source # Methods (FromField a, FromField b) => FromRecord (a, b) Source # MethodsparseRecord :: Record -> Parser (a, b) Source # (FromField a, FromField b, FromField c) => FromRecord (a, b, c) Source # MethodsparseRecord :: Record -> Parser (a, b, c) Source # (FromField a, FromField b, FromField c, FromField d) => FromRecord (a, b, c, d) Source # MethodsparseRecord :: Record -> Parser (a, b, c, d) Source # (FromField a, FromField b, FromField c, FromField d, FromField e) => FromRecord (a, b, c, d, e) Source # MethodsparseRecord :: Record -> Parser (a, b, c, d, e) Source # (FromField a, FromField b, FromField c, FromField d, FromField e, FromField f) => FromRecord (a, b, c, d, e, f) Source # MethodsparseRecord :: Record -> Parser (a, b, c, d, e, f) Source # (FromField a, FromField b, FromField c, FromField d, FromField e, FromField f, FromField g) => FromRecord (a, b, c, d, e, f, g) Source # MethodsparseRecord :: Record -> Parser (a, b, c, d, e, f, g) Source # (FromField a, FromField b, FromField c, FromField d, FromField e, FromField f, FromField g, FromField h) => FromRecord (a, b, c, d, e, f, g, h) Source # MethodsparseRecord :: Record -> Parser (a, b, c, d, e, f, g, h) Source # (FromField a, FromField b, FromField c, FromField d, FromField e, FromField f, FromField g, FromField h, FromField i) => FromRecord (a, b, c, d, e, f, g, h, i) Source # MethodsparseRecord :: Record -> Parser (a, b, c, d, e, f, g, h, i) Source # (FromField a, FromField b, FromField c, FromField d, FromField e, FromField f, FromField g, FromField h, FromField i, FromField j) => FromRecord (a, b, c, d, e, f, g, h, i, j) Source # MethodsparseRecord :: Record -> Parser (a, b, c, d, e, f, g, h, i, j) Source # (FromField a, FromField b, FromField c, FromField d, FromField e, FromField f, FromField g, FromField h, FromField i, FromField j, FromField k) => FromRecord (a, b, c, d, e, f, g, h, i, j, k) Source # MethodsparseRecord :: Record -> Parser (a, b, c, d, e, f, g, h, i, j, k) Source # (FromField a, FromField b, FromField c, FromField d, FromField e, FromField f, FromField g, FromField h, FromField i, FromField j, FromField k, FromField l) => FromRecord (a, b, c, d, e, f, g, h, i, j, k, l) Source # MethodsparseRecord :: Record -> Parser (a, b, c, d, e, f, g, h, i, j, k, l) Source # (FromField a, FromField b, FromField c, FromField d, FromField e, FromField f, FromField g, FromField h, FromField i, FromField j, FromField k, FromField l, FromField m) => FromRecord (a, b, c, d, e, f, g, h, i, j, k, l, m) Source # MethodsparseRecord :: Record -> Parser (a, b, c, d, e, f, g, h, i, j, k, l, m) Source # (FromField a, FromField b, FromField c, FromField d, FromField e, FromField f, FromField g, FromField h, FromField i, FromField j, FromField k, FromField l, FromField m, FromField n) => FromRecord (a, b, c, d, e, f, g, h, i, j, k, l, m, n) Source # MethodsparseRecord :: Record -> Parser (a, b, c, d, e, f, g, h, i, j, k, l, m, n) Source # (FromField a, FromField b, FromField c, FromField d, FromField e, FromField f, FromField g, FromField h, FromField i, FromField j, FromField k, FromField l, FromField m, FromField n, FromField o) => FromRecord (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o) Source # MethodsparseRecord :: Record -> Parser (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o) Source # data Parser a Source # 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. Instances  Source # Methods(>>=) :: Parser a -> (a -> Parser b) -> Parser b #(>>) :: Parser a -> Parser b -> Parser b #return :: a -> Parser a #fail :: String -> Parser a # Source # Methodsfmap :: (a -> b) -> Parser a -> Parser b #(<$) :: a -> Parser b -> Parser a # Source # Methodsfail :: String -> Parser a # Source # Methodspure :: a -> Parser a #(<*>) :: Parser (a -> b) -> Parser a -> Parser b #(*>) :: Parser a -> Parser b -> Parser b #(<*) :: Parser a -> Parser b -> Parser a # Source # Methodsempty :: Parser a #(<|>) :: Parser a -> Parser a -> Parser a #some :: Parser a -> Parser [a] #many :: Parser a -> Parser [a] # Source # Methodsmzero :: Parser a #mplus :: Parser a -> Parser a -> Parser a # Source # Methods(<>) :: Parser a -> Parser a -> Parser a #sconcat :: NonEmpty (Parser a) -> Parser a #stimes :: Integral b => b -> Parser a -> Parser a # Monoid (Parser a) Source # Methodsmappend :: Parser a -> Parser a -> Parser a #mconcat :: [Parser a] -> Parser a #

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.

index :: FromField a => Record -> Int -> Parser a Source #

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.

(.!) :: FromField a => Record -> Int -> Parser a infixl 9 Source #

Alias for index.

unsafeIndex :: FromField a => Record -> Int -> Parser a Source #

Like index but without bounds checking.

class ToRecord a where Source #

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

Methods

toRecord :: a -> Record Source #

Convert a value to a record.

toRecord :: (Generic a, GToRecord (Rep a) Field) => a -> Record Source #

Convert a value to a record.

Instances

 ToField a => ToRecord [a] Source # MethodstoRecord :: [a] -> Record Source # ToField a => ToRecord (Only a) Source # Methods ToField a => ToRecord (Vector a) Source # Methods (ToField a, Unbox a) => ToRecord (Vector a) Source # Methods (ToField a, ToField b) => ToRecord (a, b) Source # MethodstoRecord :: (a, b) -> Record Source # (ToField a, ToField b, ToField c) => ToRecord (a, b, c) Source # MethodstoRecord :: (a, b, c) -> Record Source # (ToField a, ToField b, ToField c, ToField d) => ToRecord (a, b, c, d) Source # MethodstoRecord :: (a, b, c, d) -> Record Source # (ToField a, ToField b, ToField c, ToField d, ToField e) => ToRecord (a, b, c, d, e) Source # MethodstoRecord :: (a, b, c, d, e) -> Record Source # (ToField a, ToField b, ToField c, ToField d, ToField e, ToField f) => ToRecord (a, b, c, d, e, f) Source # MethodstoRecord :: (a, b, c, d, e, f) -> Record Source # (ToField a, ToField b, ToField c, ToField d, ToField e, ToField f, ToField g) => ToRecord (a, b, c, d, e, f, g) Source # MethodstoRecord :: (a, b, c, d, e, f, g) -> Record Source # (ToField a, ToField b, ToField c, ToField d, ToField e, ToField f, ToField g, ToField h) => ToRecord (a, b, c, d, e, f, g, h) Source # MethodstoRecord :: (a, b, c, d, e, f, g, h) -> Record Source # (ToField a, ToField b, ToField c, ToField d, ToField e, ToField f, ToField g, ToField h, ToField i) => ToRecord (a, b, c, d, e, f, g, h, i) Source # MethodstoRecord :: (a, b, c, d, e, f, g, h, i) -> Record Source # (ToField a, ToField b, ToField c, ToField d, ToField e, ToField f, ToField g, ToField h, ToField i, ToField j) => ToRecord (a, b, c, d, e, f, g, h, i, j) Source # MethodstoRecord :: (a, b, c, d, e, f, g, h, i, j) -> Record Source # (ToField a, ToField b, ToField c, ToField d, ToField e, ToField f, ToField g, ToField h, ToField i, ToField j, ToField k) => ToRecord (a, b, c, d, e, f, g, h, i, j, k) Source # MethodstoRecord :: (a, b, c, d, e, f, g, h, i, j, k) -> Record Source # (ToField a, ToField b, ToField c, ToField d, ToField e, ToField f, ToField g, ToField h, ToField i, ToField j, ToField k, ToField l) => ToRecord (a, b, c, d, e, f, g, h, i, j, k, l) Source # MethodstoRecord :: (a, b, c, d, e, f, g, h, i, j, k, l) -> Record Source # (ToField a, ToField b, ToField c, ToField d, ToField e, ToField f, ToField g, ToField h, ToField i, ToField j, ToField k, ToField l, ToField m) => ToRecord (a, b, c, d, e, f, g, h, i, j, k, l, m) Source # MethodstoRecord :: (a, b, c, d, e, f, g, h, i, j, k, l, m) -> Record Source # (ToField a, ToField b, ToField c, ToField d, ToField e, ToField f, ToField g, ToField h, ToField i, ToField j, ToField k, ToField l, ToField m, ToField n) => ToRecord (a, b, c, d, e, f, g, h, i, j, k, l, m, n) Source # MethodstoRecord :: (a, b, c, d, e, f, g, h, i, j, k, l, m, n) -> Record Source # (ToField a, ToField b, ToField c, ToField d, ToField e, ToField f, ToField g, ToField h, ToField i, ToField j, ToField k, ToField l, ToField m, ToField n, ToField o) => ToRecord (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o) Source # MethodstoRecord :: (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o) -> Record Source #

record :: [ByteString] -> Record Source #

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

newtype Only a :: * -> * #

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) -> {- ... -} Constructors  Only FieldsfromOnly :: a Instances  Methodsfmap :: (a -> b) -> Only a -> Only b #(<$) :: a -> Only b -> Only a # Eq a => Eq (Only a) Methods(==) :: Only a -> Only a -> Bool #(/=) :: Only a -> Only a -> Bool # Data a => Data (Only a) Methodsgfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Only a -> c (Only a) #gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (Only a) #toConstr :: Only a -> Constr #dataTypeOf :: Only a -> DataType #dataCast1 :: Typeable (* -> *) t => (forall d. Data d => c (t d)) -> Maybe (c (Only a)) #dataCast2 :: Typeable (* -> * -> *) t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c (Only a)) #gmapT :: (forall b. Data b => b -> b) -> Only a -> Only a #gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Only a -> r #gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Only a -> r #gmapQ :: (forall d. Data d => d -> u) -> Only a -> [u] #gmapQi :: Int -> (forall d. Data d => d -> u) -> Only a -> u #gmapM :: Monad m => (forall d. Data d => d -> m d) -> Only a -> m (Only a) #gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Only a -> m (Only a) #gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Only a -> m (Only a) # Ord a => Ord (Only a) Methodscompare :: Only a -> Only a -> Ordering #(<) :: Only a -> Only a -> Bool #(<=) :: Only a -> Only a -> Bool #(>) :: Only a -> Only a -> Bool #(>=) :: Only a -> Only a -> Bool #max :: Only a -> Only a -> Only a #min :: Only a -> Only a -> Only a # Read a => Read (Only a) MethodsreadsPrec :: Int -> ReadS (Only a) #readList :: ReadS [Only a] # Show a => Show (Only a) MethodsshowsPrec :: Int -> Only a -> ShowS #show :: Only a -> String #showList :: [Only a] -> ShowS # Generic (Only a) Associated Typestype Rep (Only a) :: * -> * # Methodsfrom :: Only a -> Rep (Only a) x #to :: Rep (Only a) x -> Only a # NFData a => NFData (Only a) Methodsrnf :: Only a -> () # ToField a => ToRecord (Only a) Source # Methods FromField a => FromRecord (Only a) Source # Methods type Rep (Only a) type Rep (Only a) = D1 (MetaData "Only" "Data.Tuple.Only" "Only-0.1-1dkiXHtbc8zGqo2Q6b73I6" True) (C1 (MetaCons "Only" PrefixI True) (S1 (MetaSel (Just Symbol "fromOnly") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 a)))

## Name-based record conversion

Name-based conversion lets you convert CSV records to and from user-defined data types by referring to a field's name. The names of the fields are defined by the first line in the file, also known as the header. Name-based conversion is more robust to changes in the file structure e.g. to reording or addition of columns, but can be a bit slower.

class FromNamedRecord a where Source #

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:

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.

Methods

parseNamedRecord :: (Generic a, GFromNamedRecord (Rep a)) => NamedRecord -> Parser a Source #

Instances

 (FromField a, FromField b, Ord a) => FromNamedRecord (Map a b) Source # Methods (Eq a, FromField a, FromField b, Hashable a) => FromNamedRecord (HashMap a b) Source # Methods

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.

class ToNamedRecord a where Source #

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]

Methods

Convert a value to a named record.

toNamedRecord :: (Generic a, GToRecord (Rep a) (ByteString, ByteString)) => a -> NamedRecord Source #

Convert a value to a named record.

Instances

 (ToField a, ToField b, Ord a) => ToNamedRecord (Map a b) Source # Methods (Eq a, ToField a, ToField b, Hashable a) => ToNamedRecord (HashMap a b) Source # Methods

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

namedField :: ToField a => ByteString -> a -> (ByteString, ByteString) Source #

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

Construct a header from a list of ByteStrings.

## Field conversion

The FromField and ToField classes define how to convert between Fields and values you care about (e.g. Ints). Most of the time you don't need to write your own instances as the standard ones cover most use cases.

class FromField a where Source #

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:

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

Minimal complete definition

parseField

Methods

Instances

 Source # Assumes UTF-8 encoding. Methods Source # Accepts same syntax as rational. Ignores whitespace. Methods Source # Accepts same syntax as rational. Ignores whitespace. Methods Source # Accepts a signed decimal number. Ignores whitespace. Methods Source # Accepts a signed decimal number. Ignores whitespace. Methods Source # Accepts a signed decimal number. Ignores whitespace. Methods Source # Accepts a signed decimal number. Ignores whitespace. Methods Source # Accepts a signed decimal number. Ignores whitespace. Methods Source # Accepts a signed decimal number. Ignores whitespace. Methods Source # Accepts an unsigned decimal number. Ignores whitespace. Methods Source # Accepts an unsigned decimal number. Ignores whitespace. Methods Source # Accepts an unsigned decimal number. Ignores whitespace. Methods Source # Accepts an unsigned decimal number. Ignores whitespace. Methods Source # Accepts an unsigned decimal number. Ignores whitespace. Methods Source # Ignores the Field. Always succeeds. Methods Source # Methods Source # Methods Source # Assumes UTF-8 encoding. Fails on invalid byte sequences. Methods Source # Assumes UTF-8 encoding. Fails on invalid byte sequences. Methods Source # Methods Source # Methods Source # Assumes UTF-8 encoding. Fails on invalid byte sequences. Methods FromField a => FromField (Maybe a) Source # Nothing if the Field is empty, Just otherwise. Methods Source # Left field if conversion failed, Right otherwise. Methods

class ToField a where Source #

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

Example type and instance:

data Color = Red | Green | Blue

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

Minimal complete definition

toField

Methods

toField :: a -> Field Source #

Instances

 Source # Uses UTF-8 encoding. Methods Source # Uses decimal notation or scientific notation, depending on the number. Methods Source # Uses decimal notation or scientific notation, depending on the number. Methods Source # Uses decimal encoding with optional sign. Methods Source # Uses decimal encoding with optional sign. Methods Source # Uses decimal encoding with optional sign. Methods Source # Uses decimal encoding with optional sign. Methods Source # Uses decimal encoding with optional sign. Methods Source # Uses decimal encoding with optional sign. Methods Source # Uses decimal encoding. Methods Source # Uses decimal encoding. Methods Source # Uses decimal encoding. Methods Source # Uses decimal encoding. Methods Source # Uses decimal encoding. Methods Source # Methods Source # Methods Source # Uses UTF-8 encoding. Methods Source # Uses UTF-8 encoding. Methods Source # Methods Source # Methods Source # Uses UTF-8 encoding. MethodstoField :: [Char] -> Field Source # ToField a => ToField (Maybe a) Source # Nothing is encoded as an empty field. MethodstoField :: Maybe a -> Field Source #