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


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

module Data.CSV.Conduit

-- | Represents types <tt>r</tt> that are CSV-like and can be converted
--   to/from an underlying stream of type <tt>s</tt>.
--   
--   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

-- | Write headers AND the row into the output stream, once. 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

-- | Read the entire contents of a CSV file into memory.
readCSVFile :: CSV ByteString a => CSVSettings -> FilePath -> IO [a]

-- | Write CSV data into file.
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 ()

-- | 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>
type MapRow a = Map a a

-- | A <a>Row</a> is just a list of fields
type Row a = [a]
runResourceT :: MonadBaseControl IO m => ResourceT m a -> m a
instance (CSV s (Row s'), Ord s', IsString s) => CSV s (MapRow s')
instance CSV ByteString (Row String)
instance CSV ByteString (Row Text)
instance CSV Text (Row Text)
instance CSV ByteString (Row ByteString)
