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


-- | A flexible, fast, conduit-based CSV parser library for Haskell.
--   
--   CSV files are the de-facto standard in many situations involving data
--   transfer, particularly when dealing with enterprise application or
--   disparate database systems.
--   
--   While there are a number of CSV libraries in Haskell, at the time of
--   this project's start in 2010, there wasn't one that provided all of
--   the following:
--   
--   <ul>
--   <li>Full flexibility in quote characters, separators,
--   input/output</li>
--   <li>Constant space operation</li>
--   <li>Robust parsing, correctness and error resiliency</li>
--   <li>Convenient interface that supports a variety of use cases</li>
--   <li>Fast operation</li>
--   </ul>
--   
--   This library is an attempt to close these gaps. Please note that this
--   library started its life based on the enumerator package and has
--   recently been ported to work with conduits instead. In the process, it
--   has been greatly simplified thanks to the modular nature of the
--   conduits library.
--   
--   Following the port to conduits, the library has also gained the
--   ability to parameterize on the stream type and work both with
--   ByteString and Text.
--   
--   For more documentation and examples, check out the README at:
--   
--   <a>http://github.com/ozataman/csv-conduit</a>
@package csv-conduit
@version 0.6.3

module Data.CSV.Conduit.Types

-- | Settings for a CSV file. This library is intended to be flexible and
--   offer a way to process the majority of text data files out there.
data CSVSettings
CSVSettings :: !Char -> !(Maybe Char) -> CSVSettings

-- | Separator character to be used in between fields
csvSep :: CSVSettings -> !Char

-- | Quote character that may sometimes be present around fields. If
--   <a>Nothing</a> is given, the library will never expect quotation even
--   if it is present.
csvQuoteChar :: CSVSettings -> !(Maybe Char)

-- | Default settings for a CSV file.
--   
--   <pre>
--   csvSep = ','
--   csvQuoteChar = Just '"'
--   </pre>
defCSVSettings :: CSVSettings

-- | A <a>Row</a> is just a list of fields
type Row a = [a]

-- | A <a>MapRow</a> is a dictionary based on <a>Map</a> where column names
--   are keys and row's individual cell values are the values of the
--   <tt>Map</tt>.
type MapRow a = Map a a
instance Read CSVSettings
instance Show CSVSettings
instance Eq CSVSettings
instance Default CSVSettings


-- | This module exports the underlying Attoparsec row parser. This is
--   helpful if you want to do some ad-hoc CSV string parsing.
module Data.CSV.Conduit.Parser.Text

-- | Try to parse given string as CSV
parseCSV :: CSVSettings -> Text -> Either String [Row Text]

-- | Try to parse given string as 'Row Text'
parseRow :: CSVSettings -> Text -> Either String (Maybe (Row Text))

-- | Parse a CSV row
row :: CSVSettings -> Parser (Maybe (Row Text))

-- | Parse CSV
csv :: CSVSettings -> Parser [Row Text]


-- | This module exports the underlying Attoparsec row parser. This is
--   helpful if you want to do some ad-hoc CSV string parsing.
module Data.CSV.Conduit.Parser.ByteString

-- | Try to parse given string as CSV
parseCSV :: CSVSettings -> ByteString -> Either String [Row ByteString]

-- | Try to parse given string as 'Row ByteString'
parseRow :: CSVSettings -> ByteString -> Either String (Maybe (Row ByteString))

-- | Parse a CSV row
row :: CSVSettings -> Parser (Maybe (Row ByteString))

-- | Parse CSV
csv :: CSVSettings -> Parser [Row ByteString]


-- | This module has been shamelessly taken from Johan Tibell's nicely put
--   together cassava package, which itself borrows the approach from Bryan
--   O<tt>Sullivan</tt>s widely used aeson package.
--   
--   We make the necessary adjustments and some simplifications here to
--   bolt this parsing interface onto our underlying <a>CSV</a> typeclass.
module Data.CSV.Conduit.Conversion

-- | 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 wrapper around custom haskell types that can directly be
--   converted/parsed from an incoming CSV stream.
--   
--   We define this wrapper to stop GHC from complaining about overlapping
--   instances. Just use <a>getNamed</a> to get your object out of the
--   wrapper.
newtype Named a
Named :: a -> Named a
getNamed :: Named a -> a

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

-- | A shorthand for the ByteString case of <tt>MapRow</tt>
type NamedRecord = Map 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

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

-- | 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
--       toNamedRecord (Person name age) = namedRecord [
--           "name" .= name, "age" .= age]
--   </pre>
class ToNamedRecord a where toNamedRecord = namedRecord . gtoRecord . from
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 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
toRecord :: ToRecord a => a -> Record

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

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

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

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

-- | 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
instance Eq a => Eq (Named a)
instance Show a => Show (Named a)
instance Read a => Read (Named a)
instance Ord a => Ord (Named a)
instance Eq a => Eq (Only a)
instance Ord a => Ord (Only a)
instance Read a => Read (Only a)
instance Show a => Show (Only a)
instance (ToField a, Selector s) => GToRecord (M1 S s (K1 i a)) (ByteString, ByteString)
instance ToField a => GToRecord (K1 i a) Field
instance GToRecord a Field => GToRecord (M1 S c a) Field
instance GToRecord a f => GToRecord (M1 C c a) f
instance GToRecord a f => GToRecord (M1 D c a) f
instance (GToRecord a f, GToRecord b f) => GToRecord (a :+: b) f
instance (GToRecord a f, GToRecord b f) => GToRecord (a :*: b) f
instance GToRecord U1 f
instance (FromField a, Selector s) => GFromRecordProd (M1 S s (K1 i a)) NamedRecord
instance FromField a => GFromRecordProd (K1 i a) Record
instance GFromRecordProd f Record => GFromRecordProd (M1 i n f) Record
instance (GFromRecordProd a r, GFromRecordProd b r) => GFromRecordProd (a :*: b) r
instance GFromRecordProd U1 r
instance GFromRecordProd f r => GFromRecordSum (M1 i n f) r
instance (GFromRecordSum a r, GFromRecordSum b r) => GFromRecordSum (a :+: b) r
instance GFromRecordSum f NamedRecord => GFromNamedRecord (M1 i n f)
instance GFromRecordSum f Record => GFromRecord (M1 i n f)
instance Monoid (Parser a)
instance MonadPlus Parser
instance Alternative Parser
instance Applicative Parser
instance Functor Parser
instance Monad Parser
instance ToField [Char]
instance FromField [Char]
instance ToField Text
instance FromField Text
instance ToField Text
instance FromField Text
instance ToField ByteString
instance FromField ByteString
instance ToField ByteString
instance FromField ByteString
instance ToField Word64
instance FromField Word64
instance ToField Word32
instance FromField Word32
instance ToField Word16
instance FromField Word16
instance ToField Word8
instance FromField Word8
instance ToField Word
instance FromField Word
instance ToField Int64
instance FromField Int64
instance ToField Int32
instance FromField Int32
instance ToField Int16
instance FromField Int16
instance ToField Int8
instance FromField Int8
instance ToField Integer
instance FromField Integer
instance ToField Int
instance FromField Int
instance ToField Float
instance FromField Float
instance ToField Double
instance FromField Double
instance ToField Char
instance FromField Char
instance FromField ()
instance ToField a => ToField (Maybe a)
instance FromField a => FromField (Maybe a)
instance ToField a => ToNamedRecord (Map ByteString a)
instance FromField a => FromNamedRecord (Map ByteString a)
instance (ToField a, Unbox a) => ToRecord (Vector a)
instance (FromField a, Unbox a) => FromRecord (Vector a)
instance ToField a => ToRecord (Vector a)
instance FromField a => FromRecord (Vector a)
instance ToField a => ToRecord [a]
instance FromField a => FromRecord [a]
instance (ToField a, ToField b, ToField c, ToField d, ToField e, ToField f, ToField g) => ToRecord (a, b, c, d, e, f, g)
instance (FromField a, FromField b, FromField c, FromField d, FromField e, FromField f, FromField g) => FromRecord (a, b, c, d, e, f, g)
instance (ToField a, ToField b, ToField c, ToField d, ToField e, ToField f) => ToRecord (a, b, c, d, e, f)
instance (FromField a, FromField b, FromField c, FromField d, FromField e, FromField f) => FromRecord (a, b, c, d, e, f)
instance (ToField a, ToField b, ToField c, ToField d, ToField e) => ToRecord (a, b, c, d, e)
instance (FromField a, FromField b, FromField c, FromField d, FromField e) => FromRecord (a, b, c, d, e)
instance (ToField a, ToField b, ToField c, ToField d) => ToRecord (a, b, c, d)
instance (FromField a, FromField b, FromField c, FromField d) => FromRecord (a, b, c, d)
instance (ToField a, ToField b, ToField c) => ToRecord (a, b, c)
instance (FromField a, FromField b, FromField c) => FromRecord (a, b, c)
instance (ToField a, ToField b) => ToRecord (a, b)
instance (FromField a, FromField b) => FromRecord (a, b)
instance ToField a => ToRecord (Only a)
instance FromField a => FromRecord (Only a)

module Data.CSV.Conduit

-- | A simple way to decode a CSV string. Don't be alarmed by the
--   polymorphic nature of the signature. <tt>s</tt> is the type for the
--   string and <tt>v</tt> is a kind of <tt>Vector</tt> here.
--   
--   For example for <a>ByteString</a>:
--   
--   <pre>
--   &gt;&gt;&gt; s &lt;- LB.readFile "my.csv"
--   
--   &gt;&gt;&gt; decodeCSV 'def' s :: Vector (Vector ByteString)
--   </pre>
--   
--   will just work.
decodeCSV :: (Vector v a, CSV s a) => CSVSettings -> s -> Either SomeException (v a)

-- | Read the entire contents of a CSV file into memory. readCSVFile ::
--   (GV.Vector v a, CSV ByteString a) =&gt; CSVSettings -- ^ Settings to
--   use in deciphering stream -&gt; FilePath -- ^ Input file -&gt; IO (v
--   a)
readCSVFile :: (MonadIO m, CSV ByteString a) => CSVSettings -> FilePath -> m (Vector a)

-- | Write CSV data into file. As we use a <a>ByteString</a> sink, you'll
--   need to get your data into a <a>ByteString</a> stream type.
writeCSVFile :: CSV ByteString a => CSVSettings -> FilePath -> IOMode -> [a] -> IO ()

-- | General purpose CSV transformer. Apply a list-like processing function
--   from <a>List</a> to the rows of a CSV stream. You need to provide a
--   stream data source, a transformer and a stream data sink.
--   
--   An easy way to run this function would be <a>runResourceT</a> after
--   feeding it all the arguments.
--   
--   Example - map a function over the rows of a CSV file:
--   
--   <pre>
--   transformCSV set (sourceFile inFile) (C.map f) (sinkFile outFile)
--   </pre>
transformCSV :: (MonadThrow m, CSV s a, CSV s' b) => CSVSettings -> Source m s -> Conduit a m b -> Sink s' m () -> m ()

-- | Map over the rows of a CSV file. Provided for convenience for
--   historical reasons.
--   
--   An easy way to run this function would be <a>runResourceT</a> after
--   feeding it all the arguments.
mapCSVFile :: (MonadResource m, MonadThrow m, CSV ByteString a, CSV ByteString b) => CSVSettings -> (a -> [b]) -> FilePath -> FilePath -> m ()

-- | Write headers AND the row into the output stream, once. If you don't
--   call this while using <a>MapRow</a> family of row types, then your
--   resulting output will NOT have any headers in it.
--   
--   Usage: Just chain this using the <a>Monad</a> instance in your
--   pipeline:
--   
--   <pre>
--   ... =$= writeHeaders settings &gt;&gt; fromCSV settings $$ sinkFile "..."
--   </pre>
writeHeaders :: (Monad m, CSV s (Row r), IsString s) => CSVSettings -> Conduit (MapRow r) m s

-- | Represents types <tt>r</tt> that are CSV-like and can be converted
--   to/from an underlying stream of type <tt>s</tt>. There is nothing
--   scary about the type:
--   
--   <tt>s</tt> represents stream types that can be converted to/from CSV
--   rows. Examples are <a>ByteString</a>, <a>Text</a> and <a>String</a>.
--   
--   <tt>r</tt> represents the target CSV row representations that this
--   library can work with. Examples are the <a>Row</a> types, the
--   <tt>Record</tt> type and the <a>MapRow</a> family of types. We can
--   also convert directly to complex Haskell types using the
--   <a>Conversion</a> module that was borrowed from the cassava package,
--   which was itself inspired by the aeson package.
--   
--   Example #1: Basics Using Convenience API
--   
--   <pre>
--   import Data.Conduit
--   import Data.Conduit.Binary
--   import Data.Conduit.List as CL
--   import Data.CSV.Conduit
--   
--   myProcessor :: Conduit (Row Text) m (Row Text)
--   myProcessor = CL.map reverse
--   
--   test = runResourceT $
--     transformCSV defCSVSettings
--                  (sourceFile "input.csv")
--                  myProcessor
--                  (sinkFile "output.csv")
--   </pre>
--   
--   Example #2: Basics Using Conduit API
--   
--   <pre>
--   import Data.Conduit
--   import Data.Conduit.Binary
--   import Data.CSV.Conduit
--   
--   myProcessor :: Conduit (MapRow Text) m (MapRow Text)
--   myProcessor = undefined
--   
--   test = runResourceT $
--     sourceFile "test/BigFile.csv" $=
--     intoCSV defCSVSettings $=
--     myProcessor $=
--     (writeHeaders defCSVSettings &gt;&gt; fromCSV defCSVSettings) $$
--     sinkFile "test/BigFileOut.csv"
--   </pre>
class CSV s r
rowToStr :: CSV s r => CSVSettings -> r -> s
intoCSV :: (CSV s r, MonadThrow m) => CSVSettings -> Conduit s m r
fromCSV :: (CSV s r, Monad m) => CSVSettings -> Conduit r m s

-- | Settings for a CSV file. This library is intended to be flexible and
--   offer a way to process the majority of text data files out there.
data CSVSettings
CSVSettings :: !Char -> !(Maybe Char) -> CSVSettings

-- | Separator character to be used in between fields
csvSep :: CSVSettings -> !Char

-- | Quote character that may sometimes be present around fields. If
--   <a>Nothing</a> is given, the library will never expect quotation even
--   if it is present.
csvQuoteChar :: CSVSettings -> !(Maybe Char)

-- | Default settings for a CSV file.
--   
--   <pre>
--   csvSep = ','
--   csvQuoteChar = Just '"'
--   </pre>
defCSVSettings :: CSVSettings

-- | A <a>MapRow</a> is a dictionary based on <a>Map</a> where column names
--   are keys and row's individual cell values are the values of the
--   <tt>Map</tt>.
type MapRow a = Map a a

-- | A <a>Row</a> is just a list of fields
type Row a = [a]

-- | Unwrap a <a>ResourceT</a> transformer, and call all registered release
--   actions.
--   
--   Note that there is some reference counting involved due to
--   <a>resourceForkIO</a>. If multiple threads are sharing the same
--   collection of resources, only the last call to <tt>runResourceT</tt>
--   will deallocate the resources.
--   
--   Since 0.3.0
runResourceT :: MonadBaseControl IO m => ResourceT m a -> m a
instance (FromNamedRecord a, ToNamedRecord a, CSV s (MapRow ByteString)) => CSV s (Named a)
instance (CSV s (Row s'), Ord s', IsString s) => CSV s (MapRow s')
instance CSV s (Row s) => CSV s (Vector s)
instance CSV ByteString (Row String)
instance CSV ByteString (Row Text)
instance CSV Text (Row Text)
instance CSV ByteString (Row ByteString)
