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


-- | Comma-separated-value (CSV) read, show and write routines
--   
--   This modules provides conversion routines to and from the infamous
--   <a>comma separated value</a> (CSV) format. It attempts to adhere to
--   the spirit and (mostly) to the letter of RFC 4180, which defines the
--   'text/csv' MIME type.
@package ssv
@version 0.1


-- | This modules provides conversion routines to and from various
--   "something-separated value" (SSV) formats. In particular, it converts
--   the infamous "comma separated value" (CSV) format.
module Text.SSV

-- | Formatting information for a particular SSV variant.
data SSVFormat

-- | Quote format.
SSVFormat :: String -> Char -> Char -> Maybe Char -> Bool -> Maybe SSVFormatQuote -> SSVFormat
ssvFormatName :: SSVFormat -> String

-- | End of row.
ssvFormatTerminator :: SSVFormat -> Char

-- | Field separator.
ssvFormatSeparator :: SSVFormat -> Char

-- | Escape character outside of quotes.
ssvFormatEscape :: SSVFormat -> Maybe Char

-- | Strip <a>extraneous</a> spaces and tabs.
ssvFormatStripWhite :: SSVFormat -> Bool
ssvFormatQuote :: SSVFormat -> Maybe SSVFormatQuote

-- | Formatting information for quoted strings for a particular SSV
--   variant.
data SSVFormatQuote
SSVFormatQuote :: Maybe Char -> Char -> Char -> SSVFormatQuote
ssvFormatQuoteEscape :: SSVFormatQuote -> Maybe Char
ssvFormatQuoteLeft :: SSVFormatQuote -> Char
ssvFormatQuoteRight :: SSVFormatQuote -> Char

-- | Read using an arbitrary <a>SSVFormat</a>. The input is not cleaned
--   with <a>toNL</a>; if you want this, do it yourself. The standard SSV
--   formats <a>csvFormat</a> and <a>pwfFormat</a> are provided.
readSSV :: SSVFormat -> String -> [[String]]

-- | Show using an arbitrary <a>SSVFormat</a>. The standard SSV formats
--   <a>csvFormat</a> and <a>pwfFormat</a> are provided. Some effort is
--   made to "intelligently" quote the fields; in the worst case an
--   <a>SSVShowException</a> will be thrown to indicate that a field had
--   characters that could not be quoted.
showSSV :: SSVFormat -> [[String]] -> String

-- | Put a representation of the given SSV input out on a file handle using
--   the given <a>SSVFormat</a>. Uses CRLF as the line terminator
--   character, as recommended by RFC 4180 for CSV. Otherwise, this
--   function behaves as writing the output of <a>showSSV</a> to the
--   <a>Handle</a>; if you want native line terminators, this latter method
--   works for that.
hPutSSV :: SSVFormat -> Handle -> [[String]] -> IO ()

-- | Write an SSV representation of the given input into a new file located
--   at the given path, using the given <a>SSVFormat</a>. As with
--   <a>hPutCSV</a>, CRLF will be used as the line terminator.
writeSSVFile :: SSVFormat -> String -> [[String]] -> IO ()

-- | Convert a <a>String</a> representing a CSV file into a properly-parsed
--   list of rows, each a list of <a>String</a> fields. Adheres to the
--   spirit and (mostly) to the letter of RFC 4180, which defines the
--   `text/csv` MIME type.
--   
--   <a>toNL</a> is used on the input string to clean up the various line
--   endings that might appear. Note that this may result in irreversible,
--   undesired manglings of CRs and LFs.
--   
--   Fields are expected to be separated by commas. Per RFC 4180, fields
--   may be double-quoted: only whitespace, which is discarded, may appear
--   outside the double-quotes of a quoted field. For unquoted fields,
--   whitespace to the left of the field is discarded, but whitespace to
--   the right is retained; this is convenient for the parser, and probably
--   corresponds to the typical intent of CSV authors. Whitespace on both
--   sides of a quoted field is discarded. If a double-quoted fields
--   contains two double-quotes in a row, these are treated as an escaped
--   encoding of a single double-quote.
--   
--   The final line of the input may end with a line terminator, which will
--   be ignored, or without one.
readCSV :: String -> [[String]]

-- | Convert a list of rows, each a list of <a>String</a> fields, to a
--   single <a>String</a> CSV representation. Adheres to the spirit and
--   (mostly) to the letter of RFC 4180, which defines the `text/csv` MIME
--   type.
--   
--   Newline will be used as the end-of-line character, and no discardable
--   whitespace will appear in fields. Fields that need to be quoted
--   because they contain a special character or line terminator will be
--   quoted; all other fields will be left unquoted. The final row of CSV
--   will end with a newline.
showCSV :: [[String]] -> String

-- | Perform <a>hPutSSV</a> with <a>csvFormat</a>.
hPutCSV :: Handle -> [[String]] -> IO ()

-- | Perform <a>writeSSVFile</a> with <a>csvFormat</a>.
writeCSVFile :: String -> [[String]] -> IO ()

-- | Convert CR / LF sequences on input to LF (NL). Also convert other CRs
--   to LF. This is probably the right way to handle CSV data.
toNL :: String -> String

-- | Indicates format name, line and column and gives an error message.
data SSVReadException
SSVReadException :: String -> (Int, Int) -> String -> SSVReadException

-- | Indicates format name and failed field and gives an error message.
--   This should probably just be an <a>error</a>, as the calling program
--   is really responsible for passing something formattable to the show
--   routines.
data SSVShowException
SSVShowException :: String -> String -> String -> SSVShowException

-- | <a>SSVFormat</a> for CSV data. Closely follows RFC 4180.
csvFormat :: SSVFormat

-- | <a>SSVFormat</a> for UNIX "password file" data, i.e. colon-separated
--   fields with no escape convention.
pwfFormat :: SSVFormat
instance Typeable SSVReadException
instance Typeable SSVShowException
instance Exception SSVShowException
instance Exception SSVReadException
instance Show SSVShowException
instance Show SSVReadException