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


-- | A tasty enhancement to cassava for easy csv exporting
--   
--   tapioca is a package that builds on cassava, to provide a simpler,
--   more succinct method of mapping records to and from csv data.
@package tapioca
@version 0.1.1.0


-- | This module builds on
--   <a>http://hackage.haskell.org/package/cassava</a> to provide support
--   for simpler mapping of records to and from CSV.
--   
--   This is primarily achieved by use of modern GHC features such as
--   HasField and OverloadedLabels.
--   
--   Mappings created in Tapioca are type-safe - all fields must be
--   accounted for when creating a mapping.
module Data.Tapioca
data CsvMap r
CsvMap :: m -> CsvMap r

-- | This is the core type class of tapioca. Implement it in your types to
--   support easy encoding to CSV
class CsvMapped r
csvMap :: CsvMapped r => CsvMap r

-- | A newtype which provides instances for Cassava's To*, From*, and
--   DefaultOrdered typeclasses Can be used with DerivingVia to provide
--   these instances to your records directly. Refer to CassavaCompat
--   example for a demonstration.
newtype ByCsvMap a
ByCsvMap :: a -> ByCsvMap a
[unByCsvMap] :: ByCsvMap a -> a

-- | The method via which to attempt decoding of the record
data DecodeIndexing r t

-- | Use the csv's header row to match against our field mappings. This is
--   the primary use case.
[DecodeNamed] :: DecodeIndexing r NamedRecord

-- | Attempt to read the csv in the same order as our mapping has been
--   defined. If HasHeader is set, the first row (header row) will be
--   skipped.
[DecodeOrdered] :: HasHeader -> DecodeIndexing r Record

-- | A mapping for a single field in our record. A <a>CsvMap</a> is a chain
--   of FieldMappings joined with <a>:|</a>
--   
--   Can be created with:
--   
--   <ul>
--   <li><a>&lt;-&gt;</a> to map a single field</li>
--   <li><a>nest</a> to nest the record at this field</li>
--   </ul>
data FieldMapping (s :: Symbol) r f

-- | Joins together FieldMappings to create a CsvMap
data a (:|) b
(:|) :: a -> b -> (:|) a b

-- | Create a bidirectional mapping from name to field.
(<->) :: forall s r f c. (FromField c, ToField c) => ByteString -> Field s r f c -> FieldMapping s r f
infixl 3 <->

-- | Nest the record at this field into the mapping at this point.
nest :: forall s r f c. (CsvMapped c, Generic c) => Field s r f c -> FieldMapping s r f

-- | Encode a list of items using our mapping
encode :: forall r. CsvMapped r => HasHeader -> [r] -> ByteString

-- | Decode a CSV String. If there is an error parsion, error message is
--   returned on the left
decode :: forall r t. (CsvMapped r, Generic r) => DecodeIndexing r t -> ByteString -> Either String (Vector r)

-- | Return a vector of all headers specified by our csv map in order.
--   Nested maps will have their headers spliced inline. Similar to
--   cassava's headerOrder function.
header :: forall r. CsvMapped r => Header

-- | Perform a bidirectional mapping on this field with the given
--   <a>Iso</a>
(<:>) :: Field s r f c -> Iso' f c' -> Field s r f c'
infixl 4 <:>

-- | A prefix synonym for <a>&lt;:&gt;</a>.
codec :: Field s r f c -> Iso' f c' -> Field s r f c'

-- | Encode a single record to a cassava <tt>Record</tt> by ordering.
toRecord :: forall r. CsvMapped r => r -> Record

-- | Encode a single record to a cassava <tt>NamedRecord</tt>.
toNamedRecord :: forall r. CsvMapped r => r -> NamedRecord
data HasHeader :: *
HasHeader :: HasHeader
NoHeader :: HasHeader