libghc-cassava-doc 0.4.4.0-1build1 / usr / share / doc / libghc-cassava-doc / html / cassava.txt

-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A CSV parsing and encoding library
--   
--   A CSV parsing and encoding library optimized for ease of use and high
--   performance.
@package cassava
@version 0.4.4.0


-- | A CSV parser. The parser defined here is RFC 4180 compliant, with the
--   following extensions:
--   
--   <ul>
--   <li>Empty lines are ignored.</li>
--   <li>Non-escaped fields may contain any characters except
--   double-quotes, commas, carriage returns, and newlines.</li>
--   <li>Escaped fields may contain any characters (but double-quotes need
--   to be escaped).</li>
--   </ul>
--   
--   The functions in this module can be used to implement e.g. a resumable
--   parser that is fed input incrementally.
module Data.Csv.Parser

-- | 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 <a>DecodeOptions</a>, create option records by overriding values in
--   <a>defaultDecodeOptions</a>. Example:
--   
--   <pre>
--   myOptions = defaultDecodeOptions {
--         decDelimiter = fromIntegral (ord '\t')
--       }
--   </pre>
data DecodeOptions
DecodeOptions :: {-# UNPACK #-} !Word8 -> DecodeOptions

-- | Field delimiter.
[decDelimiter] :: DecodeOptions -> {-# UNPACK #-} !Word8

-- | Decoding options for parsing CSV files.
defaultDecodeOptions :: DecodeOptions

-- | Parse a CSV file that does not include a header.
csv :: DecodeOptions -> Parser Csv

-- | Parse a CSV file that includes a header.
csvWithHeader :: DecodeOptions -> Parser (Header, Vector NamedRecord)

-- | Parse a header, including the terminating line separator.
header :: Word8 -> Parser Header

-- | Parse a record, not including the terminating line separator. The
--   terminating line separate is not included as the last record in a CSV
--   file is allowed to not have a terminating line separator. You most
--   likely want to use the <a>endOfLine</a> parser in combination with
--   this parser.
record :: Word8 -> Parser Record

-- | Parse a header name. Header names have the same format as regular
--   <a>field</a>s.
name :: Word8 -> Parser Name

-- | Parse a field. The field may be in either the escaped or non-escaped
--   format. The return value is unescaped.
field :: Word8 -> Parser Field
instance GHC.Show.Show Data.Csv.Parser.DecodeOptions
instance GHC.Classes.Eq Data.Csv.Parser.DecodeOptions


-- | Low-level bytestring builders. Most users want to use the more
--   type-safe <a>Incremental</a> module instead.
module Data.Csv.Builder

-- | Encode a header.
encodeHeader :: Header -> Builder

-- | Encode a single record.
encodeRecord :: ToRecord a => a -> Builder

-- | Encode a single named record, given the field order.
encodeNamedRecord :: ToNamedRecord a => Header -> a -> Builder

-- | Encode a single named record, using the default field order.
encodeDefaultOrderedNamedRecord :: (DefaultOrdered a, ToNamedRecord a) => a -> Builder

-- | Like <a>encodeHeader</a>, but lets you customize how the CSV data is
--   encoded.
encodeHeaderWith :: EncodeOptions -> Header -> Builder

-- | Like <a>encodeRecord</a>, but lets you customize how the CSV data is
--   encoded.
encodeRecordWith :: ToRecord a => EncodeOptions -> a -> Builder

-- | Like <a>encodeNamedRecord</a>, but lets you customize how the CSV data
--   is encoded.
encodeNamedRecordWith :: ToNamedRecord a => EncodeOptions -> Header -> a -> Builder

-- | Like <a>encodeDefaultOrderedNamedRecord</a>, but lets you customize
--   how the CSV data is encoded.
encodeDefaultOrderedNamedRecordWith :: (DefaultOrdered a, ToNamedRecord a) => EncodeOptions -> a -> Builder


-- | This module allows for incremental decoding and encoding 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 example:
--   
--   <pre>
--   main :: IO ()
--   main = withFile "salaries.csv" ReadMode $ \ csvFile -&gt; do
--       let loop !_ (Fail _ errMsg) = putStrLn errMsg &gt;&gt; exitFailure
--           loop acc (Many rs k)    = loop (acc + sumSalaries rs) =&lt;&lt; feed k
--           loop acc (Done rs)      = putStrLn $ "Total salaries: " ++
--                                     show (sumSalaries rs + acc)
--   
--           feed k = do
--               isEof &lt;- hIsEOF csvFile
--               if isEof
--                   then return $ k B.empty
--                   else k `fmap` B.hGetSome csvFile 4096
--       loop 0 (decode NoHeader)
--     where
--       sumSalaries rs = sum [salary | Right (_ :: String, salary :: Int) &lt;- rs]
--   </pre>
--   
--   Encoding example:
--   
--   <pre>
--   data Person = Person { name   :: !String, salary :: !Int }
--       deriving Generic
--   
--   instance FromNamedRecord Person
--   instance ToNamedRecord Person
--   instance DefaultOrdered Person
--   
--   persons :: [Person]
--   persons = [Person "John" 50000, Person "Jane" 60000]
--   
--   main :: IO ()
--   main = putStrLn $ encodeDefaultOrderedByName (go persons)
--     where
--       go (x:xs) = encodeNamedRecord x &lt;&gt; go xs
--   </pre>
module Data.Csv.Incremental

-- | An incremental parser that when fed data eventually returns a parsed
--   <a>Header</a>, or an error.
data HeaderParser a

-- | The input data was malformed. The first field contains any unconsumed
--   input and second field contains information about the parse error.
FailH :: !ByteString -> String -> HeaderParser a

-- | The parser needs more input data before it can produce a result. Use
--   an <a>empty</a> string to indicate that no more input data is
--   available. If fed an 'B.empty string', the continuation is guaranteed
--   to return either <a>FailH</a> or <a>DoneH</a>.
PartialH :: (ByteString -> HeaderParser a) -> HeaderParser a

-- | The parse succeeded and produced the given <a>Header</a>.
DoneH :: !Header -> a -> HeaderParser a

-- | Parse a CSV header in an incremental fashion. When done, the
--   <a>HeaderParser</a> returns any unconsumed input in the second field
--   of the <a>DoneH</a> constructor.
decodeHeader :: HeaderParser ByteString

-- | Like <a>decodeHeader</a>, but lets you customize how the CSV data is
--   parsed.
decodeHeaderWith :: DecodeOptions -> HeaderParser ByteString

-- | 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.
data Parser a

-- | The input data was malformed. The first field contains any unconsumed
--   input and second field contains information about the parse error.
Fail :: !ByteString -> String -> Parser a

-- | The parser parsed and converted zero or more records. Any records that
--   failed type conversion are returned as <tt><a>Left</a> errMsg</tt> and
--   the rest as <tt><a>Right</a> val</tt>. Feed a <a>ByteString</a> to the
--   continuation to continue parsing. Use an <a>empty</a> string to
--   indicate that no more input data is available. If fed an <a>empty</a>
--   string, the continuation is guaranteed to return either <a>Fail</a> or
--   <a>Done</a>.
Many :: [Either String a] -> (ByteString -> Parser a) -> Parser a

-- | The parser parsed and converted some records. Any records that failed
--   type conversion are returned as <tt><a>Left</a> errMsg</tt> and the
--   rest as <tt><a>Right</a> val</tt>.
Done :: [Either String a] -> Parser a

-- | Is the CSV data preceded by a header?
data HasHeader

-- | The CSV data is preceded by a header
HasHeader :: HasHeader

-- | The CSV data is not preceded by a header
NoHeader :: HasHeader

-- | Efficiently deserialize CSV in an incremental fashion. Equivalent to
--   <tt><a>decodeWith</a> <a>defaultDecodeOptions</a></tt>.
decode :: FromRecord a => HasHeader -> Parser a

-- | Like <a>decode</a>, but lets you customize how the CSV data is parsed.
decodeWith :: FromRecord a => DecodeOptions -> HasHeader -> Parser a

-- | Efficiently deserialize CSV in an incremental fashion. The data is
--   assumed to be preceeded by a header. Returns a <a>HeaderParser</a>
--   that when done produces a <a>Parser</a> for parsing the actual
--   records. Equivalent to <tt><a>decodeByNameWith</a>
--   <a>defaultDecodeOptions</a></tt>.
decodeByName :: FromNamedRecord a => HeaderParser (Parser a)

-- | Like <a>decodeByName</a>, but lets you customize how the CSV data is
--   parsed.
decodeByNameWith :: FromNamedRecord a => DecodeOptions -> HeaderParser (Parser a)

-- | Efficiently serialize records in an incremental fashion. Equivalent to
--   <tt><a>encodeWith</a> <tt>defaultEncodeOptions</tt></tt>.
encode :: ToRecord a => Builder a -> ByteString

-- | Like <a>encode</a>, but lets you customize how the CSV data is
--   encoded.
encodeWith :: ToRecord a => EncodeOptions -> Builder a -> ByteString

-- | Encode a single record.
encodeRecord :: ToRecord a => a -> Builder a

-- | A builder for building the CSV data incrementally. Just like the
--   <tt>ByteString</tt> builder, this builder should be used in a
--   right-associative, <a>foldr</a> style. Using <a>&lt;&gt;</a> to
--   compose builders in a left-associative, <tt>foldl'</tt> style makes
--   the building not be incremental.
data Builder a

-- | Efficiently serialize named records in an incremental fashion,
--   including the leading header. Equivalent to <tt><a>encodeWith</a>
--   <tt>defaultEncodeOptions</tt></tt>. The header is written before any
--   records and dictates the field order.
encodeByName :: ToNamedRecord a => Header -> NamedBuilder a -> ByteString

-- | Like <a>encodeByName</a>, but header and field order is dictated by
--   the <a>headerOrder</a> method.
encodeDefaultOrderedByName :: (DefaultOrdered a, ToNamedRecord a) => NamedBuilder a -> ByteString

-- | Like <a>encodeByName</a>, but lets you customize how the CSV data is
--   encoded.
encodeByNameWith :: ToNamedRecord a => EncodeOptions -> Header -> NamedBuilder a -> ByteString

-- | Like <a>encodeDefaultOrderedByName</a>, but lets you customize how the
--   CSV data is encoded.
encodeDefaultOrderedByNameWith :: (DefaultOrdered a, ToNamedRecord a) => EncodeOptions -> NamedBuilder a -> ByteString

-- | Encode a single named record.
encodeNamedRecord :: ToNamedRecord a => a -> NamedBuilder a

-- | A builder for building the CSV data incrementally. Just like the
--   <tt>ByteString</tt> builder, this builder should be used in a
--   right-associative, <a>foldr</a> style. Using <a>&lt;&gt;</a> to
--   compose builders in a left-associative, <tt>foldl'</tt> style makes
--   the building not be incremental.
data NamedBuilder a
instance GHC.Show.Show Data.Csv.Incremental.More
instance GHC.Classes.Eq Data.Csv.Incremental.More
instance GHC.Base.Functor Data.Csv.Incremental.Parser
instance GHC.Base.Functor Data.Csv.Incremental.HeaderParser
instance GHC.Show.Show a => GHC.Show.Show (Data.Csv.Incremental.HeaderParser a)
instance GHC.Show.Show a => GHC.Show.Show (Data.Csv.Incremental.Parser a)
instance GHC.Base.Monoid (Data.Csv.Incremental.Builder a)
instance GHC.Base.Monoid (Data.Csv.Incremental.NamedBuilder a)


-- | This module allows for streaming decoding of CSV data. This is useful
--   if you need to parse large amounts of input in constant space. The API
--   also allows you to ignore type conversion errors on a per-record
--   basis.
module Data.Csv.Streaming

-- | A stream of parsed records. If type conversion failed for the record,
--   the error is returned as <tt><a>Left</a> errMsg</tt>.
data Records a

-- | A record or an error message, followed by more records.
Cons :: (Either String a) -> (Records a) -> Records a

-- | End of stream, potentially due to a parse error. If a parse error
--   occured, the first field contains the error message. The second field
--   contains any unconsumed input.
Nil :: (Maybe String) -> ByteString -> Records a

-- | Is the CSV data preceded by a header?
data HasHeader

-- | The CSV data is preceded by a header
HasHeader :: HasHeader

-- | The CSV data is not preceded by a header
NoHeader :: HasHeader

-- | Efficiently deserialize CSV records in a streaming fashion. Equivalent
--   to <tt><a>decodeWith</a> <a>defaultDecodeOptions</a></tt>.
decode :: FromRecord a => HasHeader -> ByteString -> Records a

-- | Like <a>decode</a>, but lets you customize how the CSV data is parsed.
decodeWith :: FromRecord a => DecodeOptions -> HasHeader -> ByteString -> Records a

-- | Efficiently deserialize CSV in a streaming fashion. The data is
--   assumed to be preceeded by a header. Returns <tt><a>Left</a>
--   errMsg</tt> if parsing the header fails. Equivalent to
--   <tt><a>decodeByNameWith</a> <a>defaultDecodeOptions</a></tt>.
decodeByName :: FromNamedRecord a => ByteString -> Either String (Header, Records a)

-- | Like <a>decodeByName</a>, but lets you customize how the CSV data is
--   parsed.
decodeByNameWith :: FromNamedRecord a => DecodeOptions -> ByteString -> Either String (Header, Records a)
instance GHC.Show.Show a => GHC.Show.Show (Data.Csv.Streaming.Records a)
instance GHC.Base.Functor Data.Csv.Streaming.Records
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Csv.Streaming.Records a)
instance Data.Foldable.Foldable Data.Csv.Streaming.Records
instance Data.Traversable.Traversable Data.Csv.Streaming.Records
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.Csv.Streaming.Records a)


-- | This module implements encoding and decoding of CSV data. The
--   implementation is RFC 4180 compliant, with the following extensions:
--   
--   <ul>
--   <li>Empty lines are ignored.</li>
--   <li>Non-escaped fields may contain any characters except
--   double-quotes, commas, carriage returns, and newlines.</li>
--   <li>Escaped fields may contain any characters (but double-quotes need
--   to be escaped).</li>
--   </ul>
module Data.Csv

-- | Is the CSV data preceded by a header?
data HasHeader

-- | The CSV data is preceded by a header
HasHeader :: HasHeader

-- | The CSV data is not preceded by a header
NoHeader :: HasHeader

-- | Efficiently deserialize CSV records from a lazy <a>ByteString</a>. If
--   this fails due to incomplete or invalid input, <tt><a>Left</a>
--   msg</tt> is returned. Equivalent to <tt><a>decodeWith</a>
--   <a>defaultDecodeOptions</a></tt>.
decode :: FromRecord a => HasHeader -> ByteString -> Either String (Vector a)

-- | Efficiently deserialize CSV records from a lazy <a>ByteString</a>. If
--   this fails due to incomplete or invalid input, <tt><a>Left</a>
--   msg</tt> is returned. The data is assumed to be preceeded by a header.
--   Equivalent to <tt><a>decodeByNameWith</a>
--   <a>defaultDecodeOptions</a></tt>.
decodeByName :: FromNamedRecord a => ByteString -> Either String (Header, Vector a)

-- | Should quoting be applied to fields, and at which level
data Quoting

-- | No quotes
QuoteNone :: Quoting

-- | Quotes according to RFC 4180
QuoteMinimal :: Quoting

-- | Always quote
QuoteAll :: Quoting

-- | Efficiently serialize CSV records as a lazy <a>ByteString</a>.
encode :: ToRecord a => [a] -> ByteString

-- | Efficiently serialize CSV records as a lazy <a>ByteString</a>. The
--   header is written before any records and dictates the field order.
encodeByName :: ToNamedRecord a => Header -> [a] -> ByteString

-- | Like <a>encodeByName</a>, but header and field order is dictated by
--   the <a>header</a> method.
encodeDefaultOrderedByName :: (DefaultOrdered a, ToNamedRecord a) => [a] -> ByteString

-- | 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 <a>ToNamedRecord</a>.
--   
--   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: <tt>data Foo = Foo { foo :: !Int }</tt>
--   
--   Wrong: <tt>data Bar = Bar Int</tt>
--   
--   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:
--   
--   <pre>
--   &lt;interactive&gt;: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’
--   </pre>
class DefaultOrdered a where headerOrder = fromList . gtoNamedRecordHeader . from

-- | The header order for this record. Should include the names used in the
--   <a>NamedRecord</a> returned by <a>toNamedRecord</a>. Pass
--   <a>undefined</a> as the argument, together with a type annotation e.g.
--   <tt><a>headerOrder</a> (<a>undefined</a> :: MyRecord)</tt>.
headerOrder :: DefaultOrdered a => a -> Header

-- | 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 <a>DecodeOptions</a>, create option records by overriding values in
--   <a>defaultDecodeOptions</a>. Example:
--   
--   <pre>
--   myOptions = defaultDecodeOptions {
--         decDelimiter = fromIntegral (ord '\t')
--       }
--   </pre>
data DecodeOptions
DecodeOptions :: {-# UNPACK #-} !Word8 -> DecodeOptions

-- | Field delimiter.
[decDelimiter] :: DecodeOptions -> {-# UNPACK #-} !Word8

-- | Decoding options for parsing CSV files.
defaultDecodeOptions :: DecodeOptions

-- | Like <a>decode</a>, but lets you customize how the CSV data is parsed.
decodeWith :: FromRecord a => DecodeOptions -> HasHeader -> ByteString -> Either String (Vector a)

-- | Like <a>decodeByName</a>, but lets you customize how the CSV data is
--   parsed.
decodeByNameWith :: FromNamedRecord a => DecodeOptions -> ByteString -> Either String (Header, Vector a)

-- | 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 <a>EncodeOptions</a>, create option records by overriding values in
--   <a>defaultEncodeOptions</a>. Example:
--   
--   <pre>
--   myOptions = defaultEncodeOptions {
--         encDelimiter = fromIntegral (ord '\t')
--       }
--   </pre>
--   
--   <i>N.B.</i> The <a>encDelimiter</a> must <i>not</i> be the quote
--   character (i.e. <tt>"</tt>) or one of the record separator characters
--   (i.e. <tt>\n</tt> or <tt>\r</tt>).
data EncodeOptions
EncodeOptions :: {-# UNPACK #-} !Word8 -> !Bool -> !Bool -> !Quoting -> EncodeOptions

-- | Field delimiter.
[encDelimiter] :: EncodeOptions -> {-# UNPACK #-} !Word8

-- | Record separator selection. <tt>True</tt> for CRLF (<tt>\r\n</tt>) and
--   <tt>False</tt> for LF (<tt>\n</tt>).
[encUseCrLf] :: EncodeOptions -> !Bool

-- | Include a header row when encoding <tt>ToNamedRecord</tt> instances.
[encIncludeHeader] :: EncodeOptions -> !Bool

-- | What kind of quoting should be applied to text fields.
[encQuoting] :: EncodeOptions -> !Quoting

-- | Encoding options for CSV files.
defaultEncodeOptions :: EncodeOptions

-- | Like <a>encode</a>, but lets you customize how the CSV data is
--   encoded.
encodeWith :: ToRecord a => EncodeOptions -> [a] -> ByteString

-- | Like <a>encodeByName</a>, but lets you customize how the CSV data is
--   encoded.
encodeByNameWith :: ToNamedRecord a => EncodeOptions -> Header -> [a] -> ByteString

-- | Like <a>encodeDefaultOrderedByNameWith</a>, but lets you customize how
--   the CSV data is encoded.
encodeDefaultOrderedByNameWith :: (DefaultOrdered a, ToNamedRecord a) => EncodeOptions -> [a] -> ByteString

-- | CSV data represented as a Haskell vector of vector of bytestrings.
type Csv = Vector Record

-- | A record corresponds to a single line in a CSV file.
type Record = Vector Field

-- | A single field within a record.
type Field = ByteString

-- | The header corresponds to the first line a CSV file. Not all CSV files
--   have a header.
type Header = Vector Name

-- | A header has one or more names, describing the data in the column
--   following the name.
type Name = ByteString

-- | A record corresponds to a single line in a CSV file, indexed by the
--   column name rather than the column index.
type NamedRecord = HashMap ByteString ByteString

-- | A type that can be converted from a single CSV record, with the
--   possibility of failure.
--   
--   When writing an instance, use <a>empty</a>, <a>mzero</a>, or
--   <a>fail</a> to make a conversion fail, e.g. if a <a>Record</a> has the
--   wrong number of columns.
--   
--   Given this example data:
--   
--   <pre>
--   John,56
--   Jane,55
--   </pre>
--   
--   here's an example type and instance:
--   
--   <pre>
--   data Person = Person { name :: !Text, age :: !Int }
--   
--   instance FromRecord Person where
--       parseRecord v
--           | length v == 2 = Person &lt;$&gt;
--                             v .! 0 &lt;*&gt;
--                             v .! 1
--           | otherwise     = mzero
--   </pre>
class FromRecord a where parseRecord r = to <$> gparseRecord r
parseRecord :: FromRecord a => Record -> Parser a

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

-- | Run a <a>Parser</a>, returning either <tt><a>Left</a> errMsg</tt> or
--   <tt><a>Right</a> result</tt>. Forces the value in the <a>Left</a> or
--   <a>Right</a> constructors to weak head normal form.
--   
--   You most likely won't need to use this function directly, but it's
--   included for completeness.
runParser :: Parser a -> Either String a

-- | Retrieve the <i>n</i>th field in the given record. The result is
--   <a>empty</a> if the value cannot be converted to the desired type.
--   Raises an exception if the index is out of bounds.
--   
--   <a>index</a> is a simple convenience function that is equivalent to
--   <tt><a>parseField</a> (v <a>!</a> idx)</tt>. If you're certain that
--   the index is not out of bounds, using <a>unsafeIndex</a> is somewhat
--   faster.
index :: FromField a => Record -> Int -> Parser a

-- | Alias for <a>index</a>.
(.!) :: FromField a => Record -> Int -> Parser a

-- | Like <a>index</a> but without bounds checking.
unsafeIndex :: FromField a => Record -> Int -> Parser a

-- | A type that can be converted to a single CSV record.
--   
--   An example type and instance:
--   
--   <pre>
--   data Person = Person { name :: !Text, age :: !Int }
--   
--   instance ToRecord Person where
--       toRecord (Person name age) = record [
--           toField name, toField age]
--   </pre>
--   
--   Outputs data on this form:
--   
--   <pre>
--   John,56
--   Jane,55
--   </pre>
class ToRecord a where toRecord = fromList . gtoRecord . from

-- | Convert a value to a record.
toRecord :: ToRecord a => a -> Record

-- | Construct a record from a list of <a>ByteString</a>s. Use
--   <a>toField</a> to convert values to <a>ByteString</a>s for use with
--   <a>record</a>.
record :: [ByteString] -> Record

-- | Haskell lacks a single-element tuple type, so if you CSV data with
--   just one column you can use the <a>Only</a> type to represent a
--   single-column result.
newtype Only a
Only :: a -> Only a
[fromOnly] :: Only a -> a

-- | A type that can be converted from a single CSV record, with the
--   possibility of failure.
--   
--   When writing an instance, use <a>empty</a>, <a>mzero</a>, or
--   <a>fail</a> to make a conversion fail, e.g. if a <a>Record</a> has the
--   wrong number of columns.
--   
--   Given this example data:
--   
--   <pre>
--   name,age
--   John,56
--   Jane,55
--   </pre>
--   
--   here's an example type and instance:
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   data Person = Person { name :: !Text, age :: !Int }
--   
--   instance FromNamedRecord Person where
--       parseNamedRecord m = Person &lt;$&gt;
--                            m .: "name" &lt;*&gt;
--                            m .: "age"
--   </pre>
--   
--   Note the use of the <tt>OverloadedStrings</tt> language extension
--   which enables <a>ByteString</a> values to be written as string
--   literals.
class FromNamedRecord a where parseNamedRecord r = to <$> gparseNamedRecord r
parseNamedRecord :: FromNamedRecord a => NamedRecord -> Parser a

-- | Retrieve a field in the given record by name. The result is
--   <a>empty</a> if the field is missing or if the value cannot be
--   converted to the desired type.
lookup :: FromField a => NamedRecord -> ByteString -> Parser a

-- | Alias for <a>lookup</a>.
(.:) :: FromField a => NamedRecord -> ByteString -> Parser a

-- | A type that can be converted to a single CSV record.
--   
--   An example type and instance:
--   
--   <pre>
--   data Person = Person { name :: !Text, age :: !Int }
--   
--   instance ToNamedRecord Person where
--       toNamedRecord (Person name age) = namedRecord [
--           "name" .= name, "age" .= age]
--   </pre>
class ToNamedRecord a where toNamedRecord = namedRecord . gtoRecord . from

-- | Convert a value to a named record.
toNamedRecord :: ToNamedRecord a => a -> NamedRecord

-- | Construct a named record from a list of name-value <a>ByteString</a>
--   pairs. Use <a>.=</a> to construct such a pair from a name and a value.
namedRecord :: [(ByteString, ByteString)] -> NamedRecord

-- | Construct a pair from a name and a value. For use with
--   <a>namedRecord</a>.
namedField :: ToField a => ByteString -> a -> (ByteString, ByteString)

-- | Alias for <a>namedField</a>.
(.=) :: ToField a => ByteString -> a -> (ByteString, ByteString)

-- | Construct a header from a list of <a>ByteString</a>s.
header :: [ByteString] -> Header

-- | A type that can be converted from a single CSV field, with the
--   possibility of failure.
--   
--   When writing an instance, use <a>empty</a>, <a>mzero</a>, or
--   <a>fail</a> to make a conversion fail, e.g. if a <a>Field</a> can't be
--   converted to the given type.
--   
--   Example type and instance:
--   
--   <pre>
--   {-# 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
--   </pre>
class FromField a
parseField :: FromField a => Field -> Parser a

-- | A type that can be converted to a single CSV field.
--   
--   Example type and instance:
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   data Color = Red | Green | Blue
--   
--   instance ToField Color where
--       toField Red   = "R"
--       toField Green = "G"
--       toField Blue  = "B"
--   </pre>
class ToField a
toField :: ToField a => a -> Field