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


-- | Convert bidirectionally between Dhall and CSV files.
--   
--   Use this package if you want to convert between Dhall expressions and
--   CSV. You can use this package as a library or an executable:
--   
--   <ul>
--   <li>See the <a>Dhall.Csv</a> or <a>Dhall.CsvToDhall</a> modules if you
--   want to use this package as a library</li>
--   <li>Use the <tt>dhall-to-csv</tt> or <tt>csv-to-dhall</tt> programs
--   from this package if you want an executable</li>
--   </ul>
--   
--   The <a>Dhall.Csv</a> and <a>Dhall.CsvToDhall</a> modules also contains
--   instructions for how to use this package
@package dhall-csv
@version 1.0.2


-- | This library exports two functions: <a>dhallToCsv</a> and
--   <a>codeToValue</a>. The former converts a Dhall expression (with
--   imports resolved already) into a sequence of CSV <a>NamedRecord</a>s
--   (from the <tt>cassava</tt> library) while the latter converts a
--   <a>Text</a> containing Dhall code into a list of CSV
--   <a>NamedRecord</a>s.
--   
--   Not all Dhall expressions can be converted to CSV since CSV is not a
--   programming language. The only things you can convert are
--   <tt>List</tt>s of records where each field is one of the following
--   types:
--   
--   <ul>
--   <li><tt>Bool</tt>s</li>
--   <li><tt>Natural</tt>s</li>
--   <li><tt>Integer</tt>s</li>
--   <li><tt>Double</tt>s</li>
--   <li><tt>Text</tt> values</li>
--   <li><tt>Optional</tt> (of valid field types)</li>
--   <li>unions (of empty alternatives or valid record field types)</li>
--   </ul>
--   
--   Dhall <tt>Bool</tt>s translate to either `"true"` or `"false"` in all
--   lowercase letters:
--   
--   <pre>
--   $ dhall-to-csv &lt;&lt;&lt; '[{ exampleBool = True }]'
--   exampleBool
--   true
--   $ dhall-to-csv &lt;&lt;&lt; '[{ exampleBool = False }]'
--   exampleBool
--   false
--   </pre>
--   
--   Dhall numbers translate to their string representations:
--   
--   <pre>
--   $ dhall-to-csv &lt;&lt;&lt; '[{ exampleInteger = +2 }]'
--   exampleInteger
--   2
--   $ dhall-to-csv &lt;&lt;&lt; '[{ exampleNatural = 2 }]'
--   exampleNatural
--   2
--   $ dhall-to-csv &lt;&lt;&lt; '[{ exampleDouble = 2.3 }]'
--   exampleDouble
--   2.3
--   </pre>
--   
--   Dhall <tt>Text</tt> translates directly to CSV. Special CSV characters
--   are enclosed by double quotes:
--   
--   <pre>
--   $ dhall-to-csv &lt;&lt;&lt; '[{ exampleText = "ABC" }]'
--   exampleText
--   ABC
--   $ dhall-to-csv &lt;&lt;&lt; '[{ exampleText = "ABC,ABC" }]'
--   exampleText
--   "ABC,ABC"
--   </pre>
--   
--   Dhall <tt>Optional</tt> values translate to the empty string if absent
--   and the unwrapped value otherwise:
--   
--   <pre>
--   $ dhall-to-csv &lt;&lt;&lt; '[{ exampleOptional = None Natural }]'
--   exampleOptional
--   
--   $ dhall-to-csv &lt;&lt;&lt; '[{ exampleOptional = Some 1 }]'
--   exampleOptional
--   1
--   </pre>
--   
--   Dhall unions translate to the wrapped value or the name of the field
--   (in case it is an empty field):
--   
--   <pre>
--   $ dhall-to-csv &lt;&lt;&lt; "[{ exampleUnion = &lt; Left | Right : Natural&gt;.Left }]"
--   exampleUnion
--   Left
--   $ dhall-to-csv &lt;&lt;&lt; "[{ exampleUnion = &lt; Left | Right : Natural&gt;.Right 2 }]"
--   exampleUnion
--   2
--   </pre>
--   
--   Also, all Dhall expressions are normalized before translation to CSV:
--   
--   <pre>
--   $ dhall-to-csv &lt;&lt;&lt; "[{ equality = True == False }]"
--   equality
--   false
--   </pre>
module Dhall.Csv

-- | Convert a Dhall expression (with resolved imports) to an sequence of
--   CSV <tt>NamedRecord</tt>s.
dhallToCsv :: Expr s Void -> Either CompileError (Seq NamedRecord)

-- | Convert a <tt>Text</tt> with Dhall code to a list of
--   <tt>NamedRecord</tt>s.
codeToValue :: Maybe FilePath -> Text -> IO [NamedRecord]

-- | This is the exception type for errors that can arise when converting
--   from Dhall to CSV.
--   
--   It contains information on the specific cases that might fail to give
--   a better insight.
data CompileError
instance GHC.Show.Show Dhall.Csv.CompileError
instance GHC.Exception.Type.Exception Dhall.Csv.CompileError

module Dhall.Csv.Util

-- | Utility to convert a list of <tt>NamedRecord</tt> to Text formatted as
--   a CSV.
encodeCsvDefault :: [NamedRecord] -> Text

-- | Utility to decode a CSV into a list of records. Must specify whether
--   the CSV to decode has header or not.
decodeCsvDefault :: Bool -> Text -> Either String [NamedRecord]


-- | Convert CSV data to Dhall providing an expected Dhall type necessary
--   to know which type will be interpreted.
--   
--   The translation process will produce a Dhall expression where its type
--   is a <tt>List</tt> of records and the type of each field of the
--   records is one of the following:
--   
--   <ul>
--   <li><tt>Bool</tt>s</li>
--   <li><tt>Natural</tt>s</li>
--   <li><tt>Integer</tt>s</li>
--   <li><tt>Double</tt>s</li>
--   <li><tt>Text</tt>s</li>
--   <li><tt>Optional</tt>s (of valid field types)</li>
--   <li>unions (of empty alternatives or valid record field types)</li>
--   </ul>
--   
--   It is exactly the same as <tt>dhall-to-csv</tt> supported input types.
--   
--   You can use this code as a library (this module) or as an executable
--   named <tt>csv-to-dhall</tt>, which is used in the examples below.
--   
--   For now, <tt>csv-to-dhall</tt> does not support type inference so you
--   must always specify the Dhall type you expect.
--   
--   <pre>
--   $ cat example.csv
--   example
--   1
--   $ csv-to-dhall 'List { example : Integer }' &lt; example.csv
--   [{ example = +1 }]
--   </pre>
--   
--   When using the <tt>csv-to-dhall</tt> executable you can specify that
--   the CSV you want to translate does not have a header with the flag
--   `--no-header`. In this case the resulting record fields will be named
--   <tt>_1</tt>, <tt>_2</tt>, ... in the same order they were in the input
--   CSV. You must still provide the expected Dhall type taking this into
--   consideration.
--   
--   <pre>
--   $ cat no-header-example.csv
--   1,3.14,Hello
--   -1,2.68,Goodbye
--   $ csv-to-dhall --no-header 'List { _1 : Integer, _2 : Double, _3 : Text } &lt; no-header-example.csv
--   [ { _1 = +1, _2 = 3.14, _3 = "Hello" }
--   , { _1 = -1, _2 = 2.68, _3 = "Goodbye" }
--   ]
--   </pre>
--   
--   <h2>Primitive types</h2>
--   
--   Strings <tt>true</tt> and <tt>false</tt> can translate to Dhall
--   <tt>Bool</tt>s
--   
--   <pre>
--   $ cat example.csv
--   exampleBool
--   true
--   false
--   $ csv-to-dhall 'List { exampleBool : Bool }' &lt; example.csv
--   [ { exampleBool = True }, { exampleBool = False } ]
--   </pre>
--   
--   Numeric strings can translate to Dhall numbers:
--   
--   <pre>
--   $ cat example.csv
--   exampleNatural,exampleInt,exampleDouble
--   1,2,3
--   0,-2,3.14
--   0,+2,-3.14
--   $ csv-to-dhall 'List { exampleNatural : Natural, exampleInt : Integer, exampleDouble : Double }' &lt; example.csv
--   [ { exampleNatural = 1, exampleInt = +2, exampleDouble = 3.0 }
--   , { exampleNatural = 0, exampleInt = -2, exampleDouble = 3.14 }
--   , { exampleNatural = 0, exampleInt = +2, exampleDouble = -3.14 }
--   ]
--   </pre>
--   
--   Every CSV Field can translate directly to Dhall <tt>Text</tt>:
--   
--   <pre>
--   $ cat example.csv
--   exampleText
--   Hello
--   false
--   
--   ","
--   $ csv-to-dhall 'List { exampleText : Text }' &lt; example.csv
--   [ { exampleText = "Hello" }
--   , { exampleText = "false" }
--   , { exampleText = "" }
--   , { exampleText = "," }
--   ]
--   </pre>
--   
--   <h2>Unions and Optionals</h2>
--   
--   By default, when a union is expected, the first alternative that
--   matches the CSV field is chosen. With the `--unions-strict` flag one
--   can make sure that only one alternative matches. With the
--   `--unions-none` unions are not allowed.
--   
--   An union alternative matches a CSV field if
--   
--   <ul>
--   <li>It's an empty alternative and the name is the same as the text in
--   the CSV field.</li>
--   <li>It's a non-empty alternative and the CSV field can be converted to
--   the underlying type.</li>
--   </ul>
--   
--   <pre>
--   $ cat example.csv
--   exampleUnion
--   Hello
--   1
--   1.11
--   $ csv-to-dhall 'List { exampleUnion : &lt;Hello | Nat : Natural | Dob : Double&gt; }' &lt; example.csv
--   [ { exampleUnion = &lt;Hello | Nat : Natural | Dob : Double&gt;.Hello }
--   , { exampleUnion = &lt;Hello | Nat : Natural | Dob : Double&gt;.Nat 1 }
--   , { exampleUnion = &lt;Hello | Nat : Natural | Dob : Double&gt;.Dob 1.11 }
--   ]
--   </pre>
--   
--   Optional values can be either missing or have the expected value. The
--   missing value is represented by the empty string. If a field's
--   expected value is an Optional and the field is not in the CSV, then
--   all the values will be None.
--   
--   <pre>
--   $ cat example.csv
--   exampleOptional
--   1
--   
--   3
--   $ csv-to-dhall 'List { exampleOptional : Optional Natural, exampleMissing : Optional Natural }' &lt; example.csv
--   [ { exampleOptional = Some 1, exampleMissing = None Natural }
--   , { exampleOptional = None Natural, exampleMissing = None Natural }
--   , { exampleOptional = Some 3, exampleMissing = None Natural }
--   ]
--   </pre>
module Dhall.CsvToDhall

-- | Convert a list of CSV <tt>NameRecord</tt> to a Dhall expression given
--   the expected Dhall Type of the output.
dhallFromCsv :: Conversion -> ExprX -> [NamedRecord] -> Either CompileError ExprX

-- | Standard parser for options related to the conversion method
parseConversion :: Parser Conversion

-- | Default conversion options
defaultConversion :: Conversion

-- | Parse schema code and resolve imports
resolveSchemaExpr :: Text -> IO ExprX

-- | Check that the Dhall type expression actually has type <tt>Type</tt>
typeCheckSchemaExpr :: (Exception e, MonadCatch m) => (CompileError -> e) -> ExprX -> m ExprX

-- | CSV-to-dhall translation options
data Conversion
Conversion :: Bool -> UnionConv -> Conversion
[strictRecs] :: Conversion -> Bool
[unions] :: Conversion -> UnionConv

-- | This is the exception type for errors that can arise when converting
--   from CSV to Dhall.
--   
--   It contains information on the specific cases that might fail to give
--   a better insight.
data CompileError
Unsupported :: ExprX -> CompileError
NotAList :: ExprX -> CompileError
NotARecord :: ExprX -> CompileError
TypeError :: TypeError Src Void -> CompileError
BadSchemaType :: ExprX -> ExprX -> CompileError
MissingField :: Text -> CompileError
UnhandledFields :: [Text] -> CompileError
Mismatch :: ExprX -> Text -> Text -> CompileError
ContainsUnion :: ExprX -> CompileError
UndecidableUnion :: ExprX -> Text -> Text -> [ExprX] -> CompileError
UndecidableMissingUnion :: ExprX -> Text -> [ExprX] -> CompileError
UnicodeError :: UnicodeException -> CompileError
instance GHC.Classes.Eq Dhall.CsvToDhall.UnionConv
instance GHC.Read.Read Dhall.CsvToDhall.UnionConv
instance GHC.Show.Show Dhall.CsvToDhall.UnionConv
instance GHC.Show.Show Dhall.CsvToDhall.Conversion
instance GHC.Show.Show Dhall.CsvToDhall.CompileError
instance GHC.Exception.Type.Exception Dhall.CsvToDhall.CompileError