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


-- | TOML 1.0.0 parser
--   
--   TOML parser using generated lexers and parsers with careful attention
--   to the TOML 1.0.0 semantics for defining tables.
@package toml-parser
@version 1.3.2.0


-- | This type helps to build up computations that can validate a TOML
--   value and compute some application-specific representation.
--   
--   It supports warning messages which can be used to deprecate old
--   configuration options and to detect unused table keys.
--   
--   It supports tracking multiple error messages when you have more than
--   one decoding option and all of them have failed.
--   
--   Use <a>prettyMatchMessage</a> for an easy way to make human readable
--   strings from matcher outputs.
module Toml.FromValue.Matcher

-- | Computations that result in a <a>Result</a> and which track a list of
--   nested contexts to assist in generating warnings and error messages.
--   
--   Use <a>withScope</a> to run a <a>Matcher</a> in a new, nested scope.
data Matcher a

-- | Computation outcome with error and warning messages. Multiple error
--   messages can occur when multiple alternatives all fail. Resolving any
--   one of the error messages could allow the computation to succeed.
data Result e a

-- | error messages
Failure :: [e] -> Result e a

-- | warning messages and result
Success :: [e] -> a -> Result e a

-- | A message emitted while matching a TOML value. The message is paired
--   with the path to the value that was in focus when the message was
--   generated. These message get used for both warnings and errors.
data MatchMessage
MatchMessage :: [Scope] -> String -> MatchMessage

-- | path to message location
[matchPath] :: MatchMessage -> [Scope]

-- | error and warning message body
[matchMessage] :: MatchMessage -> String

-- | Run a <a>Matcher</a> with an empty scope.
runMatcher :: Matcher a -> Result MatchMessage a

-- | Run a <a>Matcher</a> with a locally extended scope.
withScope :: Scope -> Matcher a -> Matcher a

-- | Get the current list of scopes.
getScope :: Matcher [Scope]

-- | Emit a warning mentioning the current scope.
warning :: String -> Matcher ()

-- | Scopes for TOML message.
data Scope

-- | zero-based array index
ScopeIndex :: Int -> Scope

-- | key in a table
ScopeKey :: String -> Scope

-- | Update the scope with the message corresponding to a table key
inKey :: String -> Matcher a -> Matcher a

-- | Update the scope with the message corresponding to an array index
inIndex :: Int -> Matcher a -> Matcher a
instance GHC.Classes.Ord Toml.FromValue.Matcher.Scope
instance GHC.Classes.Eq Toml.FromValue.Matcher.Scope
instance GHC.Show.Show Toml.FromValue.Matcher.Scope
instance GHC.Read.Read Toml.FromValue.Matcher.Scope
instance GHC.Classes.Ord Toml.FromValue.Matcher.MatchMessage
instance GHC.Classes.Eq Toml.FromValue.Matcher.MatchMessage
instance GHC.Show.Show Toml.FromValue.Matcher.MatchMessage
instance GHC.Read.Read Toml.FromValue.Matcher.MatchMessage
instance GHC.Base.Monoid (Toml.FromValue.Matcher.DList a)
instance GHC.Base.Semigroup (Toml.FromValue.Matcher.DList a)
instance (GHC.Classes.Ord e, GHC.Classes.Ord a) => GHC.Classes.Ord (Toml.FromValue.Matcher.Result e a)
instance (GHC.Classes.Eq e, GHC.Classes.Eq a) => GHC.Classes.Eq (Toml.FromValue.Matcher.Result e a)
instance (GHC.Show.Show e, GHC.Show.Show a) => GHC.Show.Show (Toml.FromValue.Matcher.Result e a)
instance (GHC.Read.Read e, GHC.Read.Read a) => GHC.Read.Read (Toml.FromValue.Matcher.Result e a)
instance GHC.Base.Functor Toml.FromValue.Matcher.Matcher
instance GHC.Base.Applicative Toml.FromValue.Matcher.Matcher
instance GHC.Base.Monad Toml.FromValue.Matcher.Matcher
instance GHC.Base.Alternative Toml.FromValue.Matcher.Matcher
instance GHC.Base.MonadPlus Toml.FromValue.Matcher.Matcher
instance Control.Monad.Fail.MonadFail Toml.FromValue.Matcher.Matcher


-- | This module provides the datatype for the lexical syntax of TOML
--   files. These tokens are generated by <a>Toml.Lexer</a> and consumed in
--   <a>Toml.Parser</a>.
module Toml.Lexer.Token

-- | Lexical token
data Token

-- | <pre>
--   true
--   </pre>
TokTrue :: Token

-- | <pre>
--   false
--   </pre>
TokFalse :: Token

-- | <pre>
--   ','
--   </pre>
TokComma :: Token

-- | <pre>
--   '='
--   </pre>
TokEquals :: Token

-- | <pre>
--   end-of-line
--   </pre>
TokNewline :: Token

-- | <pre>
--   <a>.</a>
--   </pre>
TokPeriod :: Token

-- | <pre>
--   '['
--   </pre>
TokSquareO :: Token

-- | <pre>
--   ']'
--   </pre>
TokSquareC :: Token

-- | <pre>
--   '[['
--   </pre>
Tok2SquareO :: Token

-- | <pre>
--   ']]'
--   </pre>
Tok2SquareC :: Token

-- | <pre>
--   '{'
--   </pre>
TokCurlyO :: Token

-- | <pre>
--   '}'
--   </pre>
TokCurlyC :: Token

-- | bare key
TokBareKey :: String -> Token

-- | string literal
TokString :: String -> Token

-- | multiline string literal
TokMlString :: String -> Token

-- | integer literal
TokInteger :: !Integer -> Token

-- | floating-point literal
TokFloat :: !Double -> Token

-- | date-time with timezone offset
TokOffsetDateTime :: !ZonedTime -> Token

-- | local date-time
TokLocalDateTime :: !LocalTime -> Token

-- | local date
TokLocalDate :: !Day -> Token

-- | local time
TokLocalTime :: !TimeOfDay -> Token

-- | <pre>
--   end-of-input
--   </pre>
TokEOF :: Token

-- | Construct a <a>TokInteger</a> from a binary integer literal lexeme.
mkBinInteger :: String -> Token

-- | Construct a <a>TokInteger</a> from a decimal integer literal lexeme.
mkDecInteger :: String -> Token

-- | Construct a <a>TokInteger</a> from a octal integer literal lexeme.
mkOctInteger :: String -> Token

-- | Construct a <a>TokInteger</a> from a hexadecimal integer literal
--   lexeme.
mkHexInteger :: String -> Token

-- | Construct a <a>TokFloat</a> from a floating-point literal lexeme.
mkFloat :: String -> Token

-- | Format strings for local date lexemes.
localDatePatterns :: [String]

-- | Format strings for local time lexemes.
localTimePatterns :: [String]

-- | Format strings for local datetime lexemes.
localDateTimePatterns :: [String]

-- | Format strings for offset datetime lexemes.
offsetDateTimePatterns :: [String]
instance GHC.Show.Show Toml.Lexer.Token.Token
instance GHC.Read.Read Toml.Lexer.Token.Token


-- | This module provides the <a>Position</a> type for tracking locations
--   in files while doing lexing and parsing for providing more useful
--   error messages.
--   
--   This module assumes 8 column wide tab stops.
module Toml.Position

-- | A position in a text file
data Position
Position :: {-# UNPACK #-} !Int -> {-# UNPACK #-} !Int -> {-# UNPACK #-} !Int -> Position

-- | code-point index (zero-based)
[posIndex] :: Position -> {-# UNPACK #-} !Int

-- | line index (one-based)
[posLine] :: Position -> {-# UNPACK #-} !Int

-- | column index (one-based)
[posColumn] :: Position -> {-# UNPACK #-} !Int

-- | The initial <a>Position</a> for the start of a file
startPos :: Position

-- | Adjust a file position given a single character handling newlines and
--   tabs. All other characters are considered to fill exactly one column.
move :: Char -> Position -> Position
instance GHC.Classes.Eq Toml.Position.Position
instance GHC.Classes.Ord Toml.Position.Position
instance GHC.Show.Show Toml.Position.Position
instance GHC.Read.Read Toml.Position.Position


-- | This module provides a simple tuple for tracking pairs of values and
--   their file locations.
module Toml.Located

-- | A value annotated with its text file position
data Located a
Located :: {-# UNPACK #-} !Position -> !a -> Located a

-- | position
[locPosition] :: Located a -> {-# UNPACK #-} !Position

-- | thing at position
[locThing] :: Located a -> !a
instance Data.Traversable.Traversable Toml.Located.Located
instance Data.Foldable.Foldable Toml.Located.Located
instance GHC.Base.Functor Toml.Located.Located
instance GHC.Show.Show a => GHC.Show.Show (Toml.Located.Located a)
instance GHC.Read.Read a => GHC.Read.Read (Toml.Located.Located a)


-- | This module provides a raw representation of TOML files as a list of
--   table definitions and key-value assignments.
--   
--   These values use the raw dotted keys and have no detection for
--   overlapping assignments.
--   
--   Further processing will happen in the <a>Semantics</a> module.
module Toml.Parser.Types

-- | Non-empty sequence of dotted simple keys
type Key = NonEmpty (Located String)

-- | Headers and assignments corresponding to lines of a TOML file
data Expr

-- | key value assignment: <tt>key = value</tt>
KeyValExpr :: Key -> Val -> Expr

-- | table: <tt>[key]</tt>
TableExpr :: Key -> Expr

-- | array of tables: <tt>[[key]]</tt>
ArrayTableExpr :: Key -> Expr

-- | Unvalidated TOML values. Table are represented as a list of
--   assignments rather than as resolved maps.
data Val
ValInteger :: Integer -> Val
ValFloat :: Double -> Val
ValArray :: [Val] -> Val
ValTable :: [(Key, Val)] -> Val
ValBool :: Bool -> Val
ValString :: String -> Val
ValTimeOfDay :: TimeOfDay -> Val
ValZonedTime :: ZonedTime -> Val
ValLocalTime :: LocalTime -> Val
ValDay :: Day -> Val

-- | Kinds of table headers.
data SectionKind

-- | <ul>
--   <li><i>table</i></li>
--   </ul>
TableKind :: SectionKind

-- | <ul>
--   <li><i>[array of tables</i> ]</li>
--   </ul>
ArrayTableKind :: SectionKind
instance GHC.Show.Show Toml.Parser.Types.Val
instance GHC.Read.Read Toml.Parser.Types.Val
instance GHC.Show.Show Toml.Parser.Types.Expr
instance GHC.Read.Read Toml.Parser.Types.Expr
instance GHC.Classes.Eq Toml.Parser.Types.SectionKind
instance GHC.Show.Show Toml.Parser.Types.SectionKind
instance GHC.Read.Read Toml.Parser.Types.SectionKind


-- | This module parses a TOML file into a lazy sequence of tokens. The
--   lexer is aware of nested brackets and equals signs in order to handle
--   TOML's context-sensitive lexing requirements. This context enables the
--   lexer to distinguish between bare keys and various values like:
--   floating-point literals, integer literals, and date literals.
--   
--   This module uses actions and lexical hooks defined in
--   <a>LexerUtils</a>.
module Toml.Lexer

-- | Representation of the current lexer state.
data Context

-- | top-level where <tt>[[</tt> and <tt>]]</tt> have special meaning
TopContext :: Context

-- | inline table - lex key names
TableContext :: Context

-- | value lexer - lex number literals
ValueContext :: Context

-- | multiline basic string: position of opening delimiter and list of
--   fragments
MlBstrContext :: Position -> [String] -> Context

-- | basic string: position of opening delimiter and list of fragments
BstrContext :: Position -> [String] -> Context

-- | multiline literal string: position of opening delimiter and list of
--   fragments
MlLstrContext :: Position -> [String] -> Context

-- | literal string: position of opening delimiter and list of fragments
LstrContext :: Position -> [String] -> Context

-- | Get the next token from a located string. This function can be total
--   because one of the possible token outputs is an error token.
scanToken :: Context -> Located String -> Either (Located String) (Located Token, Located String)

-- | Lex a single token in a value context. This is mostly useful for
--   testing.
lexValue :: String -> Either String Token

-- | Lexical token
data Token

-- | <pre>
--   true
--   </pre>
TokTrue :: Token

-- | <pre>
--   false
--   </pre>
TokFalse :: Token

-- | <pre>
--   ','
--   </pre>
TokComma :: Token

-- | <pre>
--   '='
--   </pre>
TokEquals :: Token

-- | <pre>
--   end-of-line
--   </pre>
TokNewline :: Token

-- | <pre>
--   <a>.</a>
--   </pre>
TokPeriod :: Token

-- | <pre>
--   '['
--   </pre>
TokSquareO :: Token

-- | <pre>
--   ']'
--   </pre>
TokSquareC :: Token

-- | <pre>
--   '[['
--   </pre>
Tok2SquareO :: Token

-- | <pre>
--   ']]'
--   </pre>
Tok2SquareC :: Token

-- | <pre>
--   '{'
--   </pre>
TokCurlyO :: Token

-- | <pre>
--   '}'
--   </pre>
TokCurlyC :: Token

-- | bare key
TokBareKey :: String -> Token

-- | string literal
TokString :: String -> Token

-- | multiline string literal
TokMlString :: String -> Token

-- | integer literal
TokInteger :: !Integer -> Token

-- | floating-point literal
TokFloat :: !Double -> Token

-- | date-time with timezone offset
TokOffsetDateTime :: !ZonedTime -> Token

-- | local date-time
TokLocalDateTime :: !LocalTime -> Token

-- | local date
TokLocalDate :: !Day -> Token

-- | local time
TokLocalTime :: !TimeOfDay -> Token

-- | <pre>
--   end-of-input
--   </pre>
TokEOF :: Token


-- | This module can help build a key ordering projection given an existing
--   TOML file. This could be useful for applying a transformation to a
--   TOML file before pretty-printing it back in something very close to
--   the original order.
--   
--   When using the computed order, table keys will be remembered in the
--   order they appeared in the source file. Any key additional keys added
--   to the tables will be ordered alphabetically after all the known keys.
--   
--   <pre>
--   demo =
--    do txt &lt;- <a>readFile</a> "demo.toml"
--       let Right exprs = <a>parseRawToml</a> txt
--           to          = <a>extractTableOrder</a> exprs
--           Right toml  = <a>semantics</a> exprs
--           projection  = <a>projectKey</a> to
--       <a>print</a> (<a>prettyTomlOrdered</a> projection toml)
--   </pre>
module Toml.Semantics.Ordered

-- | Summary of the order of the keys in a TOML document.
data TableOrder

-- | Extract a <a>TableOrder</a> from the output of <a>parseRawToml</a> to
--   be later used with <a>projectKey</a>.
extractTableOrder :: [Expr] -> TableOrder

-- | Generate a projection function for use with <a>prettyTomlOrdered</a>
projectKey :: TableOrder -> [String] -> String -> ProjectedKey
data ProjectedKey

-- | Render a white-space nested representation of the key ordering
--   extracted by <a>extractTableOrder</a>. This is provided for debugging
--   and understandability.
debugTableOrder :: TableOrder -> String
instance GHC.Classes.Ord Toml.Semantics.Ordered.ProjectedKey
instance GHC.Classes.Eq Toml.Semantics.Ordered.ProjectedKey


-- | This module provides the type for the semantics of a TOML file. All
--   dotted keys are resolved in this representation. Each table is a Map
--   with a single level of keys.
module Toml.Value

-- | Semantic TOML value with all table assignments resolved.
data Value
Integer :: Integer -> Value
Float :: Double -> Value
Array :: [Value] -> Value
Table :: Table -> Value
Bool :: Bool -> Value
String :: String -> Value
TimeOfDay :: TimeOfDay -> Value
ZonedTime :: ZonedTime -> Value
LocalTime :: LocalTime -> Value
Day :: Day -> Value

-- | Representation of a TOML key-value table.
type Table = Map String Value
instance GHC.Generics.Generic Toml.Value.Value
instance Data.Data.Data Toml.Value.Value
instance GHC.Read.Read Toml.Value.Value
instance GHC.Show.Show Toml.Value.Value
instance GHC.Classes.Eq Toml.Value.Value


-- | The <a>ToValue</a> class provides a conversion function from
--   application-specific to TOML values.
--   
--   Because the top-level TOML document is always a table, the
--   <a>ToTable</a> class is for types that specifically support conversion
--   to a <a>Table</a>.
--   
--   <a>Toml.ToValue.Generic</a> can be used to derive instances of
--   <a>ToTable</a> automatically for record types.
module Toml.ToValue

-- | Class for types that can be embedded into <a>Value</a>
class ToValue a

-- | Embed a single thing into a TOML value.
toValue :: ToValue a => a -> Value

-- | Helper for converting a list of things into a value. This is typically
--   left to be defined by its default implementation and exists to help
--   define the encoding for TOML arrays.
toValueList :: ToValue a => [a] -> Value

-- | Class for things that can be embedded into a TOML table.
--   
--   Implement this for things that always embed into a <a>Table</a> and
--   then the <a>ToValue</a> instance can be derived with
--   <a>defaultTableToValue</a>.
--   
--   <pre>
--   instance ToValue Example where
--       toValue = defaultTableToValue
--   
--   -- Option 1: Manual instance
--   instance ToTable Example where
--       toTable x = <a>table</a> ["field1" <a>.=</a> field1 x, "field2" <a>.=</a> field2 x]
--   
--   -- Option 2: GHC.Generics derived instance using Toml.ToValue.Generic
--   instance ToTable Example where
--       toTable = genericToTable
--   </pre>
class ToValue a => ToTable a

-- | Convert a single value into a table
toTable :: ToTable a => a -> Table

-- | Convert to a table key. This class enables various string types to be
--   used as the keys of a <a>Map</a> when converting into TOML tables.
class ToKey a
toKey :: ToKey a => a -> String

-- | Convenience function for building <a>ToValue</a> instances.
defaultTableToValue :: ToTable a => a -> Value

-- | Build a <a>Table</a> from a list of key-value pairs.
--   
--   Use <a>.=</a> for a convenient way to build the pairs.
table :: [(String, Value)] -> Table

-- | Convenience function for building key-value pairs while constructing a
--   <a>Table</a>.
--   
--   <pre>
--   <a>table</a> [a <a>.=</a> b, c <a>.=</a> d]
--   </pre>
(.=) :: ToValue a => String -> a -> (String, Value)
instance (Toml.ToValue.ToKey k, Toml.ToValue.ToValue v) => Toml.ToValue.ToTable (Data.Map.Internal.Map k v)
instance (Toml.ToValue.ToKey k, Toml.ToValue.ToValue v) => Toml.ToValue.ToValue (Data.Map.Internal.Map k v)
instance (GHC.Types.Char GHC.Types.~ a) => Toml.ToValue.ToKey [a]
instance Toml.ToValue.ToKey Data.Text.Internal.Text
instance Toml.ToValue.ToKey Data.Text.Internal.Lazy.Text
instance Toml.ToValue.ToValue Toml.Value.Value
instance Toml.ToValue.ToValue GHC.Types.Char
instance Toml.ToValue.ToValue Data.Text.Internal.Text
instance Toml.ToValue.ToValue Data.Text.Internal.Lazy.Text
instance Toml.ToValue.ToValue a => Toml.ToValue.ToValue [a]
instance Toml.ToValue.ToValue a => Toml.ToValue.ToValue (GHC.Base.NonEmpty a)
instance Toml.ToValue.ToValue a => Toml.ToValue.ToValue (Data.Sequence.Internal.Seq a)
instance GHC.Real.Integral a => Toml.ToValue.ToValue (GHC.Real.Ratio a)
instance Toml.ToValue.ToValue GHC.Types.Double
instance Toml.ToValue.ToValue GHC.Types.Float
instance Toml.ToValue.ToValue GHC.Types.Bool
instance Toml.ToValue.ToValue Data.Time.LocalTime.Internal.TimeOfDay.TimeOfDay
instance Toml.ToValue.ToValue Data.Time.LocalTime.Internal.LocalTime.LocalTime
instance Toml.ToValue.ToValue Data.Time.LocalTime.Internal.ZonedTime.ZonedTime
instance Toml.ToValue.ToValue Data.Time.Calendar.Days.Day
instance Toml.ToValue.ToValue GHC.Num.Integer.Integer
instance Toml.ToValue.ToValue GHC.Num.Natural.Natural
instance Toml.ToValue.ToValue GHC.Types.Int
instance Toml.ToValue.ToValue GHC.Int.Int8
instance Toml.ToValue.ToValue GHC.Int.Int16
instance Toml.ToValue.ToValue GHC.Int.Int32
instance Toml.ToValue.ToValue GHC.Int.Int64
instance Toml.ToValue.ToValue GHC.Types.Word
instance Toml.ToValue.ToValue GHC.Word.Word8
instance Toml.ToValue.ToValue GHC.Word.Word16
instance Toml.ToValue.ToValue GHC.Word.Word32
instance Toml.ToValue.ToValue GHC.Word.Word64


-- | Use <a>genericToTable</a> to derive an instance of <a>ToTable</a>
--   using the field names of a record.
--   
--   Use <a>genericToArray</a> to derive an instance of <a>ToValue</a>
--   using the positions of data in a constructor.
module Toml.ToValue.Generic

-- | Supports conversion of product types with field selector names to TOML
--   values.
class GToTable f
gToTable :: GToTable f => f a -> [(String, Value)] -> [(String, Value)]

-- | Use a record's field names to generate a <a>Table</a>
genericToTable :: (Generic a, GToTable (Rep a)) => a -> Table

-- | Convert product types to arrays positionally.
class GToArray f
gToArray :: GToArray f => f a -> [Value] -> [Value]

-- | Use a record's field names to generate a <a>Table</a>
genericToArray :: (Generic a, GToArray (Rep a)) => a -> Value
instance Toml.ToValue.Generic.GToArray f => Toml.ToValue.Generic.GToArray (GHC.Generics.M1 i c f)
instance (Toml.ToValue.Generic.GToArray f, Toml.ToValue.Generic.GToArray g) => Toml.ToValue.Generic.GToArray (f GHC.Generics.:*: g)
instance Toml.ToValue.ToValue a => Toml.ToValue.Generic.GToArray (GHC.Generics.K1 i a)
instance Toml.ToValue.Generic.GToTable f => Toml.ToValue.Generic.GToTable (GHC.Generics.D1 c f)
instance Toml.ToValue.Generic.GToTable f => Toml.ToValue.Generic.GToTable (GHC.Generics.C1 c f)
instance (Toml.ToValue.Generic.GToTable f, Toml.ToValue.Generic.GToTable g) => Toml.ToValue.Generic.GToTable (f GHC.Generics.:*: g)
instance (GHC.Generics.Selector s, Toml.ToValue.ToValue a) => Toml.ToValue.Generic.GToTable (GHC.Generics.S1 s (GHC.Generics.K1 i (GHC.Maybe.Maybe a)))
instance (GHC.Generics.Selector s, Toml.ToValue.ToValue a) => Toml.ToValue.Generic.GToTable (GHC.Generics.S1 s (GHC.Generics.K1 i a))
instance Toml.ToValue.Generic.GToTable GHC.Generics.U1
instance Toml.ToValue.Generic.GToTable GHC.Generics.V1


-- | This module extracts a nested Map representation of a TOML file. It
--   detects invalid key assignments and resolves dotted key assignments.
module Toml.Semantics

-- | This type represents errors generated when resolving keys in a TOML
--   document.
data SemanticError
SemanticError :: String -> SemanticErrorKind -> SemanticError
[errorKey] :: SemanticError -> String
[errorKind] :: SemanticError -> SemanticErrorKind

-- | Enumeration of the kinds of conflicts a key can generate.
data SemanticErrorKind

-- | Attempted to assign to a key that was already assigned
AlreadyAssigned :: SemanticErrorKind

-- | Attempted to open a table already closed
ClosedTable :: SemanticErrorKind

-- | Attempted to open a tables as an array of tables that was implicitly
--   defined to be a table
ImplicitlyTable :: SemanticErrorKind

-- | Extracts a semantic value from a sequence of raw TOML expressions, or
--   reports a semantic error if one occurs.
semantics :: [Expr] -> Either (Located SemanticError) Table
instance GHC.Classes.Ord Toml.Semantics.SemanticErrorKind
instance GHC.Classes.Eq Toml.Semantics.SemanticErrorKind
instance GHC.Show.Show Toml.Semantics.SemanticErrorKind
instance GHC.Read.Read Toml.Semantics.SemanticErrorKind
instance GHC.Classes.Ord Toml.Semantics.SemanticError
instance GHC.Classes.Eq Toml.Semantics.SemanticError
instance GHC.Show.Show Toml.Semantics.SemanticError
instance GHC.Read.Read Toml.Semantics.SemanticError
instance GHC.Show.Show Toml.Semantics.FrameKind
instance GHC.Show.Show Toml.Semantics.Frame


-- | This module provides human-readable renderers for types used in this
--   package to assist error message production.
--   
--   The generated <a>Doc</a> values are annotated with <a>DocClass</a>
--   values to assist in producing syntax-highlighted outputs.
--   
--   To extract a plain String representation, use <a>show</a>.
module Toml.Pretty

-- | Pretty-printer document with TOML class attributes to aid in
--   syntax-highlighting.
type TomlDoc = Doc DocClass

-- | Annotation used to enable styling pretty-printed TOML
data DocClass

-- | top-level <tt>[key]</tt> and <tt>[[key]]</tt>
TableClass :: DocClass

-- | dotted keys, left-hand side of assignments
KeyClass :: DocClass

-- | string literals
StringClass :: DocClass

-- | number literals
NumberClass :: DocClass

-- | date and time literals
DateClass :: DocClass

-- | boolean literals
BoolClass :: DocClass

-- | Render a complete TOML document using top-level table and array of
--   table sections where possible.
--   
--   Keys are sorted alphabetically. To provide a custom ordering, see
--   <a>prettyTomlOrdered</a>.
prettyToml :: Table -> TomlDoc

-- | Render a complete TOML document like <a>prettyToml</a> but use a
--   custom key ordering. The comparison function has access to the
--   complete key path. Note that only keys in the same table will every be
--   compared.
--   
--   This operation allows you to render your TOML files with the most
--   important sections first. A TOML file describing a package might
--   desire to have the <tt>[package]</tt> section first before any of the
--   ancilliary configuration sections.
--   
--   The <i>table path</i> is the name of the table being sorted. This
--   allows the projection to be aware of which table is being sorted.
--   
--   The <i>key</i> is the key in the table being sorted. These are the
--   keys that will be compared to each other.
--   
--   Here's a projection that puts the <tt>package</tt> section first, the
--   <tt>secondary</tt> section second, and then all remaining cases are
--   sorted alphabetically afterward.
--   
--   <pre>
--   example :: [String] -&gt; String -&gt; Either Int String
--   example [] "package" = Left 1
--   example [] "second"  = Left 2
--   example _  other     = Right other
--   </pre>
--   
--   We could also put the tables in reverse-alphabetical order by
--   leveraging an existing newtype.
--   
--   <pre>
--   reverseOrderProj :: [String] -&gt; String -&gt; Down String
--   reverseOrderProj _ = Down
--   </pre>
prettyTomlOrdered :: Ord a => ([String] -> String -> a) -> Table -> TomlDoc

-- | Render a value suitable for assignment on the right-hand side of an
--   equals sign. This value will always use inline table and list syntax.
prettyValue :: Value -> TomlDoc

-- | Render token for human-readable error messages.
prettyToken :: Token -> String

-- | Pretty-print a section heading. The result is annotated as a
--   <a>TableClass</a>.
prettySectionKind :: SectionKind -> NonEmpty String -> TomlDoc

-- | Renders a simple-key using quotes where necessary.
prettySimpleKey :: String -> Doc a

-- | Renders a dotted-key using quotes where necessary and annotated as a
--   <a>KeyClass</a>.
prettyKey :: NonEmpty String -> TomlDoc

-- | Render a semantic TOML error in a human-readable string.
prettySemanticError :: SemanticError -> String

-- | Render a TOML decoding error as a human-readable string.
prettyMatchMessage :: MatchMessage -> String
prettyLocated :: Located String -> String
instance GHC.Classes.Ord Toml.Pretty.DocClass
instance GHC.Classes.Eq Toml.Pretty.DocClass
instance GHC.Show.Show Toml.Pretty.DocClass
instance GHC.Read.Read Toml.Pretty.DocClass


-- | This module parses TOML tokens into a list of raw, uninterpreted
--   sections and assignments.
module Toml.Parser

-- | Headers and assignments corresponding to lines of a TOML file
data Expr

-- | key value assignment: <tt>key = value</tt>
KeyValExpr :: Key -> Val -> Expr

-- | table: <tt>[key]</tt>
TableExpr :: Key -> Expr

-- | array of tables: <tt>[[key]]</tt>
ArrayTableExpr :: Key -> Expr

-- | Kinds of table headers.
data SectionKind

-- | <ul>
--   <li><i>table</i></li>
--   </ul>
TableKind :: SectionKind

-- | <ul>
--   <li><i>[array of tables</i> ]</li>
--   </ul>
ArrayTableKind :: SectionKind

-- | Unvalidated TOML values. Table are represented as a list of
--   assignments rather than as resolved maps.
data Val
ValInteger :: Integer -> Val
ValFloat :: Double -> Val
ValArray :: [Val] -> Val
ValTable :: [(Key, Val)] -> Val
ValBool :: Bool -> Val
ValString :: String -> Val
ValTimeOfDay :: TimeOfDay -> Val
ValZonedTime :: ZonedTime -> Val
ValLocalTime :: LocalTime -> Val
ValDay :: Day -> Val

-- | Non-empty sequence of dotted simple keys
type Key = NonEmpty (Located String)

-- | Parse a list of tokens either returning the first unexpected token or
--   a list of the TOML statements in the file to be processed by
--   <a>Toml.Semantics</a>.
parseRawToml :: String -> Either (Located String) [Expr]


-- | This module provides utilities for matching key-value pairs out of
--   tables while building up application-specific values.
--   
--   It will help generate warnings for unused keys, help select between
--   multiple possible keys, and emit location-specific error messages when
--   keys are unavailable.
--   
--   This module provides the <a>ParseTable</a> implementation, but most of
--   the basic functionality is exported directly from
--   <a>Toml.FromValue</a>.
module Toml.FromValue.ParseTable

-- | A <a>Matcher</a> that tracks a current set of unmatched key-value
--   pairs from a table.
--   
--   Use <a>optKey</a> and <a>reqKey</a> to extract keys.
--   
--   Use <a>getTable</a> and <a>setTable</a> to override the table and
--   implement other primitives.
data ParseTable a

-- | Key and value matching function
data KeyAlt a

-- | pick alternative based on key match
Key :: String -> (Value -> Matcher a) -> KeyAlt a

-- | default case when no previous cases matched
Else :: Matcher a -> KeyAlt a

-- | Take the first option from a list of table keys and matcher functions.
--   This operation will commit to the first table key that matches. If the
--   associated matcher fails, only that error will be propagated and the
--   other alternatives will not be matched.
--   
--   If no keys match, an error message is generated explaining which keys
--   would have been accepted.
--   
--   This is provided as an alternative to chaining multiple <a>reqKey</a>
--   cases together with <tt>(<tt>&lt;|&gt;</tt>)</tt> because that will
--   generate one error message for each unmatched alternative as well as
--   the error associate with the matched alternative.
pickKey :: [KeyAlt a] -> ParseTable a

-- | Run a <a>ParseTable</a> computation with a given starting
--   <a>Table</a>. Unused tables will generate a warning. To change this
--   behavior <a>getTable</a> and <a>setTable</a> can be used to discard or
--   generate error messages.
runParseTable :: ParseTable a -> Table -> Matcher a

-- | Lift a matcher into the current table parsing context.
liftMatcher :: Matcher a -> ParseTable a

-- | Emit a warning at the current location.
warnTable :: String -> ParseTable ()

-- | Replace the remaining portion of the table being matched.
setTable :: Table -> ParseTable ()

-- | Return the remaining portion of the table being matched.
getTable :: ParseTable Table
instance GHC.Base.MonadPlus Toml.FromValue.ParseTable.ParseTable
instance GHC.Base.Alternative Toml.FromValue.ParseTable.ParseTable
instance GHC.Base.Monad Toml.FromValue.ParseTable.ParseTable
instance GHC.Base.Applicative Toml.FromValue.ParseTable.ParseTable
instance GHC.Base.Functor Toml.FromValue.ParseTable.ParseTable
instance Control.Monad.Fail.MonadFail Toml.FromValue.ParseTable.ParseTable


-- | Use <a>FromValue</a> to define a transformation from some <a>Value</a>
--   to an application domain type.
--   
--   Use <a>ParseTable</a> to help build <a>FromValue</a> instances that
--   match tables. It will make it easy to track which table keys have been
--   used and which are left over.
--   
--   Warnings can be emitted using <a>warning</a> and <a>warnTable</a>
--   (depending on what) context you're in. These warnings can provide
--   useful feedback about problematic decodings or keys that might be
--   unused now but were perhaps meaningful in an old version of a
--   configuration file.
--   
--   <a>Toml.FromValue.Generic</a> can be used to derive instances of
--   <a>FromValue</a> automatically for record types.
module Toml.FromValue

-- | Class for types that can be decoded from a TOML value.
class FromValue a

-- | Convert a <a>Value</a> or report an error message
fromValue :: FromValue a => Value -> Matcher a

-- | Used to implement instance for '[]'. Most implementations rely on the
--   default implementation.
listFromValue :: FromValue a => Value -> Matcher [a]

-- | Convert from a table key
class FromKey a
fromKey :: FromKey a => String -> Matcher a

-- | Computations that result in a <a>Result</a> and which track a list of
--   nested contexts to assist in generating warnings and error messages.
--   
--   Use <a>withScope</a> to run a <a>Matcher</a> in a new, nested scope.
data Matcher a

-- | A message emitted while matching a TOML value. The message is paired
--   with the path to the value that was in focus when the message was
--   generated. These message get used for both warnings and errors.
data MatchMessage
MatchMessage :: [Scope] -> String -> MatchMessage

-- | path to message location
[matchPath] :: MatchMessage -> [Scope]

-- | error and warning message body
[matchMessage] :: MatchMessage -> String

-- | Computation outcome with error and warning messages. Multiple error
--   messages can occur when multiple alternatives all fail. Resolving any
--   one of the error messages could allow the computation to succeed.
data Result e a

-- | error messages
Failure :: [e] -> Result e a

-- | warning messages and result
Success :: [e] -> a -> Result e a

-- | Emit a warning mentioning the current scope.
warning :: String -> Matcher ()

-- | A <a>Matcher</a> that tracks a current set of unmatched key-value
--   pairs from a table.
--   
--   Use <a>optKey</a> and <a>reqKey</a> to extract keys.
--   
--   Use <a>getTable</a> and <a>setTable</a> to override the table and
--   implement other primitives.
data ParseTable a

-- | Run a <a>ParseTable</a> computation with a given starting
--   <a>Table</a>. Unused tables will generate a warning. To change this
--   behavior <a>getTable</a> and <a>setTable</a> can be used to discard or
--   generate error messages.
runParseTable :: ParseTable a -> Table -> Matcher a

-- | Used to derive a <a>fromValue</a> implementation from a
--   <a>ParseTable</a> matcher.
parseTableFromValue :: ParseTable a -> Value -> Matcher a

-- | Convenience function for matching a required key with a
--   <a>FromValue</a> instance.
--   
--   <pre>
--   reqKey key = <a>reqKeyOf</a> key <a>fromValue</a>
--   </pre>
reqKey :: FromValue a => String -> ParseTable a

-- | Convenience function for matching an optional key with a
--   <a>FromValue</a> instance.
--   
--   <pre>
--   optKey key = <a>optKeyOf</a> key <a>fromValue</a>
--   </pre>
optKey :: FromValue a => String -> ParseTable (Maybe a)

-- | Match a table entry by key or report an error if missing.
--   
--   See <a>pickKey</a> for more complex cases.
reqKeyOf :: String -> (Value -> Matcher a) -> ParseTable a

-- | Match a table entry by key if it exists or return <a>Nothing</a> if
--   not. If the key is defined, it is matched by the given function.
--   
--   See <a>pickKey</a> for more complex cases.
optKeyOf :: String -> (Value -> Matcher a) -> ParseTable (Maybe a)

-- | Emit a warning at the current location.
warnTable :: String -> ParseTable ()

-- | Key and value matching function
data KeyAlt a

-- | pick alternative based on key match
Key :: String -> (Value -> Matcher a) -> KeyAlt a

-- | default case when no previous cases matched
Else :: Matcher a -> KeyAlt a

-- | Take the first option from a list of table keys and matcher functions.
--   This operation will commit to the first table key that matches. If the
--   associated matcher fails, only that error will be propagated and the
--   other alternatives will not be matched.
--   
--   If no keys match, an error message is generated explaining which keys
--   would have been accepted.
--   
--   This is provided as an alternative to chaining multiple <a>reqKey</a>
--   cases together with <tt>(<tt>&lt;|&gt;</tt>)</tt> because that will
--   generate one error message for each unmatched alternative as well as
--   the error associate with the matched alternative.
pickKey :: [KeyAlt a] -> ParseTable a

-- | Return the remaining portion of the table being matched.
getTable :: ParseTable Table

-- | Replace the remaining portion of the table being matched.
setTable :: Table -> ParseTable ()

-- | Lift a matcher into the current table parsing context.
liftMatcher :: Matcher a -> ParseTable a
instance (GHC.Classes.Ord k, Toml.FromValue.FromKey k, Toml.FromValue.FromValue v) => Toml.FromValue.FromValue (Data.Map.Internal.Map k v)
instance (a GHC.Types.~ GHC.Types.Char) => Toml.FromValue.FromKey [a]
instance Toml.FromValue.FromKey Data.Text.Internal.Text
instance Toml.FromValue.FromKey Data.Text.Internal.Lazy.Text
instance Toml.FromValue.FromValue GHC.Num.Integer.Integer
instance Toml.FromValue.FromValue GHC.Num.Natural.Natural
instance Toml.FromValue.FromValue GHC.Types.Int
instance Toml.FromValue.FromValue GHC.Int.Int8
instance Toml.FromValue.FromValue GHC.Int.Int16
instance Toml.FromValue.FromValue GHC.Int.Int32
instance Toml.FromValue.FromValue GHC.Int.Int64
instance Toml.FromValue.FromValue GHC.Types.Word
instance Toml.FromValue.FromValue GHC.Word.Word8
instance Toml.FromValue.FromValue GHC.Word.Word16
instance Toml.FromValue.FromValue GHC.Word.Word32
instance Toml.FromValue.FromValue GHC.Word.Word64
instance Toml.FromValue.FromValue GHC.Types.Char
instance Toml.FromValue.FromValue Data.Text.Internal.Text
instance Toml.FromValue.FromValue Data.Text.Internal.Lazy.Text
instance Toml.FromValue.FromValue GHC.Types.Double
instance Toml.FromValue.FromValue GHC.Types.Float
instance GHC.Real.Integral a => Toml.FromValue.FromValue (GHC.Real.Ratio a)
instance Toml.FromValue.FromValue a => Toml.FromValue.FromValue (GHC.Base.NonEmpty a)
instance Toml.FromValue.FromValue a => Toml.FromValue.FromValue (Data.Sequence.Internal.Seq a)
instance Toml.FromValue.FromValue GHC.Types.Bool
instance Toml.FromValue.FromValue a => Toml.FromValue.FromValue [a]
instance Toml.FromValue.FromValue Data.Time.Calendar.Days.Day
instance Toml.FromValue.FromValue Data.Time.LocalTime.Internal.TimeOfDay.TimeOfDay
instance Toml.FromValue.FromValue Data.Time.LocalTime.Internal.ZonedTime.ZonedTime
instance Toml.FromValue.FromValue Data.Time.LocalTime.Internal.LocalTime.LocalTime
instance Toml.FromValue.FromValue Toml.Value.Value


-- | Use <a>genericParseTable</a> to derive a <a>ParseTable</a> using the
--   field names of a record. This can be combined with
--   <a>parseTableFromValue</a> to derive a <a>FromValue</a> instance.
module Toml.FromValue.Generic

-- | Supports conversion of TOML tables into record values using field
--   selector names as TOML keys.
class GParseTable f

-- | Convert a value and apply the continuation to the result.
gParseTable :: GParseTable f => ParseTable (f a)

-- | Match a <tt>Table</tt> using the field names in a record.
genericParseTable :: (Generic a, GParseTable (Rep a)) => ParseTable a

-- | Supports conversion of TOML arrays into product-type values.
class GFromArray f
gFromArray :: GFromArray f => StateT [Value] Matcher (f a)

-- | Match a <a>Value</a> as an array positionally matching field fields of
--   a constructor to the elements of the array.
genericFromArray :: (Generic a, GFromArray (Rep a)) => Value -> Matcher a
instance Toml.FromValue.Generic.GFromArray f => Toml.FromValue.Generic.GFromArray (GHC.Generics.M1 i c f)
instance (Toml.FromValue.Generic.GFromArray f, Toml.FromValue.Generic.GFromArray g) => Toml.FromValue.Generic.GFromArray (f GHC.Generics.:*: g)
instance Toml.FromValue.FromValue a => Toml.FromValue.Generic.GFromArray (GHC.Generics.K1 i a)
instance Toml.FromValue.Generic.GFromArray GHC.Generics.U1
instance Toml.FromValue.Generic.GParseTable f => Toml.FromValue.Generic.GParseTable (GHC.Generics.D1 c f)
instance Toml.FromValue.Generic.GParseTable f => Toml.FromValue.Generic.GParseTable (GHC.Generics.C1 ('GHC.Generics.MetaCons sym fix 'GHC.Types.True) f)
instance (Toml.FromValue.Generic.GParseTable f, Toml.FromValue.Generic.GParseTable g) => Toml.FromValue.Generic.GParseTable (f GHC.Generics.:*: g)
instance (GHC.Generics.Selector s, Toml.FromValue.FromValue a) => Toml.FromValue.Generic.GParseTable (GHC.Generics.S1 s (GHC.Generics.K1 i (GHC.Maybe.Maybe a)))
instance (GHC.Generics.Selector s, Toml.FromValue.FromValue a) => Toml.FromValue.Generic.GParseTable (GHC.Generics.S1 s (GHC.Generics.K1 i a))
instance Toml.FromValue.Generic.GParseTable GHC.Generics.U1


-- | This module makes it possible to easily derive the TOML classes using
--   the <tt>DerivingVia</tt> extension.
--   
--   For example:
--   
--   <pre>
--   data Physical = Physical {
--       color :: String,
--       shape :: String
--       }
--       deriving (Eq, Show, Generic)
--       deriving (ToTable, ToValue, FromValue) via GenericTomlTable Physical
--   </pre>
--   
--   These derived instances would allow you to match TOML
--   <tt>{color="red", shape="round"}</tt> to value <tt>Coord 1 2</tt>.
--   
--   <pre>
--   data Coord = Coord Int Int
--       deriving (Eq, Show, Generic)
--       deriving (ToValue, FromValue) via GenericTomlArray Physical
--   </pre>
--   
--   These derived instances would allow you to match TOML <tt>[1,2]</tt>
--   to value <tt>Coord 1 2</tt>.
module Toml.Generic

-- | Helper type to use GHC's DerivingVia extension to derive
--   <a>ToValue</a>, <a>ToTable</a>, <a>FromValue</a> for records.
newtype GenericTomlTable a
GenericTomlTable :: a -> GenericTomlTable a

-- | Helper type to use GHC's DerivingVia extension to derive
--   <a>ToValue</a>, <a>ToTable</a>, <a>FromValue</a> for any product type.
newtype GenericTomlArray a
GenericTomlArray :: a -> GenericTomlArray a
instance (GHC.Generics.Generic a, Toml.ToValue.Generic.GToArray (GHC.Generics.Rep a)) => Toml.ToValue.ToValue (Toml.Generic.GenericTomlArray a)
instance (GHC.Generics.Generic a, Toml.FromValue.Generic.GFromArray (GHC.Generics.Rep a)) => Toml.FromValue.FromValue (Toml.Generic.GenericTomlArray a)
instance (GHC.Generics.Generic a, Toml.ToValue.Generic.GToTable (GHC.Generics.Rep a)) => Toml.ToValue.ToValue (Toml.Generic.GenericTomlTable a)
instance (GHC.Generics.Generic a, Toml.ToValue.Generic.GToTable (GHC.Generics.Rep a)) => Toml.ToValue.ToTable (Toml.Generic.GenericTomlTable a)
instance (GHC.Generics.Generic a, Toml.FromValue.Generic.GParseTable (GHC.Generics.Rep a)) => Toml.FromValue.FromValue (Toml.Generic.GenericTomlTable a)


-- | This is the high-level interface to the toml-parser library. It
--   enables parsing, printing, and coversion into and out of
--   application-specific representations.
--   
--   This parser implements TOML 1.0.0 <a>https://toml.io/en/v1.0.0</a> as
--   carefully as possible.
module Toml

-- | Representation of a TOML key-value table.
type Table = Map String Value

-- | Semantic TOML value with all table assignments resolved.
data Value
Integer :: Integer -> Value
Float :: Double -> Value
Array :: [Value] -> Value
Table :: Table -> Value
Bool :: Bool -> Value
String :: String -> Value
TimeOfDay :: TimeOfDay -> Value
ZonedTime :: ZonedTime -> Value
LocalTime :: LocalTime -> Value
Day :: Day -> Value

-- | Parse a TOML formatted <a>Value</a> or report an error message.
parse :: String -> Either String Table

-- | Render a complete TOML document using top-level table and array of
--   table sections where possible.
--   
--   Keys are sorted alphabetically. To provide a custom ordering, see
--   <a>prettyTomlOrdered</a>.
prettyToml :: Table -> TomlDoc

-- | Annotation used to enable styling pretty-printed TOML
data DocClass

-- | top-level <tt>[key]</tt> and <tt>[[key]]</tt>
TableClass :: DocClass

-- | dotted keys, left-hand side of assignments
KeyClass :: DocClass

-- | string literals
StringClass :: DocClass

-- | number literals
NumberClass :: DocClass

-- | date and time literals
DateClass :: DocClass

-- | boolean literals
BoolClass :: DocClass

-- | Use the <a>FromValue</a> instance to decode a value from a TOML
--   string.
decode :: FromValue a => String -> Result String a

-- | Use the <a>ToTable</a> instance to encode a value to a TOML string.
encode :: ToTable a => a -> TomlDoc

-- | Computation outcome with error and warning messages. Multiple error
--   messages can occur when multiple alternatives all fail. Resolving any
--   one of the error messages could allow the computation to succeed.
data Result e a

-- | error messages
Failure :: [e] -> Result e a

-- | warning messages and result
Success :: [e] -> a -> Result e a
