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


-- | Fast, streaming csv parser
--   
--   `pipes-csv` is a streaming csv parser built on top of <a>cassava</a>
--   and <a>pipes</a>
@package pipes-csv
@version 1.4.3


-- | This module contains a couple functions copied from Data.Csv.Encoding
--   that weren't exported. This file can be removed once they are.
module Pipes.Csv.Encoding
encodeRecord :: Word8 -> Record -> Builder
namedRecordToRecord :: Header -> NamedRecord -> Record


-- | This module allows constant-space CSV parsing.
--   
--   It feeds <a>ByteString</a>s into cassavas incremental CSV parser to
--   attain true constant-space record streaming.
module Pipes.Csv

-- | Equivalent to <tt><a>decodeWith</a> <a>defaultDecodeOptions</a></tt>.
decode :: (Monad m, FromRecord a) => HasHeader -> Producer ByteString m () -> Producer (Either String a) m ()

-- | Create a <a>Producer</a> that takes a <a>ByteString</a>
--   <a>Producer</a> as input, producing either errors or
--   <a>FromRecord</a>s.
decodeWith :: (Monad m, FromRecord a) => DecodeOptions -> HasHeader -> Producer ByteString m () -> Producer (Either String a) m ()

-- | Equivalent to <tt><a>decodeByNameWith</a>
--   <a>defaultDecodeOptions</a></tt>.
decodeByName :: (Monad m, FromNamedRecord a) => Producer ByteString m () -> Producer (Either String a) m ()

-- | Create a <a>Producer</a> that takes a <a>ByteString</a>
--   <a>Producer</a> as input, producing either errors or
--   <a>FromNamedRecord</a>s.
decodeByNameWith :: (Monad m, FromNamedRecord a) => DecodeOptions -> Producer ByteString m () -> Producer (Either String a) m ()

-- | Create a Record <a>Producer</a> by feeding <a>ByteString</a>s into a
--   <a>Parser</a>
feedParser :: Monad m => Parser a -> Producer ByteString m () -> Producer (Either String a) m ()

-- | Create a NamedRecord <a>Producer</a> by feeding <a>ByteString</a>s
--   into a <a>Parser</a>
feedHeaderParser :: Monad m => HeaderParser (Parser a) -> Producer ByteString m () -> Producer (Either String a) m ()

-- | Encode records as strict <a>ByteString</a>s
encode :: (Monad m, ToRecord a) => Pipe a ByteString m r

-- | Encode records as strict <a>ByteString</a>s
encodeWith :: (Monad m, ToRecord a) => EncodeOptions -> Pipe a ByteString m r

-- | Encode named records as strict <a>ByteString</a>s
encodeByName :: (Monad m, ToNamedRecord a) => Header -> Pipe a ByteString m r

-- | Encode named records as strict <a>ByteString</a>s
encodeByNameWith :: (Monad m, ToNamedRecord a) => EncodeOptions -> Header -> Pipe a ByteString m r

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

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

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

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

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

-- | 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
parseRecord :: FromRecord a => Record -> 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

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

-- | 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
parseNamedRecord :: FromNamedRecord a => NamedRecord -> 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

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

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

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

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

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

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

-- | 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 single field within a record.
type Field = ByteString

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