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


-- | A flexible, fast, enumerator-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.
--   
--   For more documentation and examples, check out the README at:
--   
--   <a>http://github.com/ozataman/csv-enumerator</a>
--   
--   The API is fairly well documented and I would encourage you to keep
--   your haddocks handy. If you run into problems, just email me or holler
--   over at #haskell.
@package csv-enumerator
@version 0.9.0

module Data.CSV.Enumerator
type Row = [Field]
type Field = ByteString
type MapRow = Map ByteString ByteString
class CSVeable r
rowToStr :: CSVeable r => CSVSettings -> r -> ByteString
fileHeaders :: CSVeable r => [r] -> Maybe Row
iterCSV :: CSVeable r => CSVSettings -> CSVAction r a -> a -> Iteratee ByteString IO a
fileSink :: CSVeable r => CSVSettings -> FilePath -> (Maybe Handle, Int) -> ParsedRow r -> Iteratee ByteString IO (Maybe Handle, Int)
mapCSVFiles :: CSVeable r => [FilePath] -> CSVSettings -> (r -> [r]) -> FilePath -> IO (Either SomeException Int)

-- | A datatype that incorporates the signaling of parsing status to the
--   user-developed iteratee.
--   
--   We need this because some iteratees do interleaved IO (such as
--   outputting to a file via a handle inside the accumulator) and some
--   final actions may need to be taken upon encountering EOF (such as
--   closing the interleaved handle).
--   
--   Use this datatype when developing iteratees for use with fold* family
--   of functions (Row enumarators).
data CSVeable r => ParsedRow r
ParsedRow :: (Maybe r) -> ParsedRow r
EOF :: ParsedRow r

-- | 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
CSVS :: Char -> Maybe Char -> Maybe Char -> 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

-- | Quote character that should be used in the output.
csvOutputQuoteChar :: CSVSettings -> Maybe Char

-- | Field separator that should be used in the output.
csvOutputColSep :: CSVSettings -> Char

-- | Default settings for a CSV file.
--   
--   <pre>
--   csvSep = ','
--   csvQuoteChar = Just '"'
--   csvOutputQuoteChar = Just '"'
--   csvOutputColSep = ','
--   </pre>
defCSVSettings :: CSVSettings
readCSVFile :: CSVeable r => CSVSettings -> FilePath -> IO (Either SomeException [r])
writeCSVFile :: CSVeable r => CSVSettings -> FilePath -> [r] -> IO Int
appendCSVFile :: CSVeable r => CSVSettings -> FilePath -> [r] -> IO Int

-- | Open &amp; fold over the CSV file.
--   
--   Processing starts on row 2 for MapRow instance to use first row as
--   column headers.
foldCSVFile :: CSVeable r => FilePath -> CSVSettings -> CSVAction r a -> a -> IO (Either SomeException a)

-- | An iteratee that processes each row of a CSV file and updates the
--   accumulator.
--   
--   You would implement one of these to use with the <a>foldCSVFile</a>
--   function.
type CSVAction r a = a -> ParsedRow r -> Iteratee ByteString IO a

-- | Convenience converter for fold step functions that are pure.
--   
--   Use this if you don't want to deal with Iteratees when writing your
--   fold functions.
funToIter :: CSVeable r => (a -> ParsedRow r -> a) -> CSVAction r a

-- | Convenience converter for fold step functions that live in the IO
--   monad.
--   
--   Use this if you don't want to deal with Iteratees when writing your
--   fold functions.
funToIterIO :: CSVeable r => (a -> ParsedRow r -> IO a) -> CSVAction r a

-- | Take a CSV file, apply function to each of its rows and save the
--   resulting rows into a new file.
--   
--   Each row is simply a list of fields.
mapCSVFile :: CSVeable r => FilePath -> CSVSettings -> (r -> [r]) -> FilePath -> IO (Either SomeException Int)

-- | Create an iteratee that can map over a CSV stream and output results
--   to a handle in an interleaved fashion.
--   
--   Example use: Let's map over a CSV file coming in through <a>stdin</a>
--   and push results to <a>stdout</a>.
--   
--   <pre>
--   f r = return [r] -- a function that just returns the given row
--   </pre>
--   
--   <pre>
--   E.run (E.enumHandle 4096 stdin $$ mapIntoHandle defCSVSettings True stdout f)
--   </pre>
--   
--   This nicely allows us to do things like (assuming you have pv
--   installed):
--   
--   <pre>
--   pv inputFile.csv | myApp &gt; output.CSV
--   </pre>
--   
--   And monitor the ongoing progress of processing.
mapIntoHandle :: CSVeable r => CSVSettings -> Bool -> Handle -> (r -> IO [r]) -> Iteratee ByteString IO Int

-- | Just collect all rows into an array. This will cancel out the
--   incremental nature of this library.
collectRows :: CSVeable r => CSVAction r [r]
outputRowIter :: CSVeable r => CSVSettings -> Handle -> r -> Iteratee ByteString IO ()
outputRowsIter :: CSVeable r => CSVSettings -> Handle -> [r] -> Iteratee ByteString IO ()

-- | Output given row into given handle
outputRow :: CSVeable r => CSVSettings -> Handle -> r -> IO ()
outputRows :: CSVeable r => CSVSettings -> Handle -> [r] -> IO ()

-- | Expand or contract the given <a>MapRow</a> to contain exactly the
--   given set of columns and then write the row into the given
--   <a>Handle</a>.
--   
--   This is helpful in filtering the columns or perhaps combining a number
--   of files that don't have the same columns.
--   
--   Missing columns will be left empty.
outputColumns :: CSVSettings -> Handle -> [ByteString] -> MapRow -> IO ()
writeHeaders :: CSVeable r => CSVSettings -> Handle -> [r] -> IO ()
instance CSVeable MapRow
instance CSVeable Row