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


-- | Build records from lists of strings, as from CSV files.
--   
--   Given rows of <tt>String</tt> data with column headings, this library
--   will create values of user-defined record types. Records can contain
--   mandatory or optional fields of any type, subject to a class
--   constraint. Heading names and and record construction code are derived
--   using Template Haskell.
--   
--   One use case for this library is parsing records from a CSV file. A
--   parser from CSV to <tt>[[String]]</tt> is not included, but there are
--   several suitable packages on Hackage.
--   
--   The emphasis of this library is on simplicity of use rather than
--   performance. It is likely to be suitable for a hundred thousand rows,
--   but not many millions. A future version may support packed input
--   formats like <tt>ByteString</tt> or <tt>Text</tt>. Suggestions and
--   patches are welcome.
@package rowrecord
@version 0.1


-- | Convert lists of strings to records.
module Text.RowRecord

-- | Identifies a column.
type Column = String

-- | A row of <tt><a>String</a></tt> data.
type Row = Map Column String

-- | A table.
type Table = [Row]

-- | Convert a list of <tt><a>String</a></tt> rows into a
--   <tt><a>Table</a></tt>. Uses the first row as column names.
fromStrings :: [[String]] -> Result Table

-- | A parse result.
data Result a
Success :: a -> Result a
Failure :: RowError -> Result a

-- | Possible errors from parsing a row.
data RowError
MissingField :: Column -> RowError
NoParse :: Column -> String -> RowError

-- | Class of field types which can be decoded from <tt><a>String</a></tt>.
--   
--   The input can be <tt><a>Nothing</a></tt> to represent a missing field.
--   The instance <tt>Field a =&gt; Field (Maybe a)</tt> models optional
--   fields.
--   
--   If your record contains custom types, you must create a
--   <tt><a>Field</a></tt> instance for each. If you have base types but
--   need different parsing behavior, you can use a <tt>newtype</tt>
--   wrapper.
class Field a
decode :: Field a => Maybe String -> Result a

-- | Implement <tt><a>decode</a></tt> for a required field.
require :: (String -> Maybe a) -> Maybe String -> Result a

-- | <tt><a>read</a></tt> in <tt><a>Maybe</a></tt>.
safeRead :: Read a => String -> Maybe a

-- | Decode a field by column name.
--   
--   Called from TH-generated code, but may be useful independently.
getField :: Field a => Column -> Row -> Result a

-- | Class of types which can be parsed from a <tt><a>Row</a></tt>. These
--   types are typically single-constructor records.
--   
--   Instances may be generated using <tt>Text.RowRecord.TH</tt>.
class ParseRow a
parseRow :: ParseRow a => Row -> Result a

-- | Parse a whole table.
parseTable :: ParseRow a => Table -> Result [a]
instance Show RowError
instance Show a => Show (Result a)
instance Field a => Field (Maybe a)
instance Field Char
instance Field String
instance Field Double
instance Field Float
instance Field Integer
instance Field Int
instance Field Bool
instance Applicative Result
instance Monad Result
instance Functor Result


-- | Generate instances for converting lists of strings to records.
module Text.RowRecord.TH

-- | Generate a <tt><a>ParseRow</a></tt> instance for each of the named
--   types.
--   
--   Each type must have exactly one constructor, in record style.
--   
--   Column names are derived from the record field names by dropping the
--   first <tt>'_'</tt>-separated component. This allows for a prefix to
--   disambiguate record labels between types.
--   
--   For example, with
--   
--   <pre>
--   data Foo = Foo
--     { f_bar :: String
--     , f_baz :: Int }
--   $(rowRecords [''Foo])
--   </pre>
--   
--   we can parse files of the form
--   
--   <pre>
--   bar,baz
--   abc,3
--   def,5
--   </pre>
--   
--   assuming an appropriate CSV parser.
rowRecords :: [Name] -> Q [Dec]