Copyright	(c) Eric Mertens 2023
License	ISC
Maintainer	emertens@gmail.com
Safe Haskell	Safe-Inferred
Language	Haskell2010

Toml

Contents

Types
Located types
Parsing
Printing
Error rendering

Description

This is the high-level interface to the toml-parser library. It enables parsing, printing, and conversion into and out of application-specific representations.

This parser implements TOML 1.0.0 https://toml.io/en/v1.0.0 as carefully as possible.

Use Toml.Schema to implement functions mapping between TOML values and your application types.

Use Toml.Syntax and Toml.Semantics for low-level TOML syntax processing and semantic validation. Most applications will not need to use these modules directly unless the application is about TOML itself.

The types and functions of this package are parameterized over an annotation type in order to allow applications to provide detailed feedback messages tracked back to specific source locations in an original TOML file. While the default annotation is a simple file position, some applications might upgrade this annotation to track multiple file names or synthetically generated sources. Other applications won't need source location and can replace annotations with a simple unit type.

Synopsis

type Table = Table' ()
type Value = Value' ()
data Located a = Located {
- locPosition :: !Position
- locThing :: !a
}
data Position = Position {
- posIndex :: !Int
- posLine :: !Int
- posColumn :: !Int
}
newtype Table' a = MkTable (Map Text (a, Value' a))
data Value' a where
- Integer' a Integer
- Double' a Double
- List' a [Value' a]
- Table' a (Table' a)
- Bool' a Bool
- Text' a Text
- TimeOfDay' a TimeOfDay
- ZonedTime' a ZonedTime
- LocalTime' a LocalTime
- Day' a Day
- pattern Bool :: Bool -> Value
- pattern Double :: Double -> Value
- pattern List :: [Value] -> Value
- pattern Integer :: Integer -> Value
- pattern Text :: Text -> Value
- pattern Table :: Table -> Value
- pattern Day :: Day -> Value
- pattern TimeOfDay :: TimeOfDay -> Value
- pattern LocalTime :: LocalTime -> Value
- pattern ZonedTime :: ZonedTime -> Value
valueAnn :: Value' a -> a
valueType :: Value' l -> String
forgetTableAnns :: Table' a -> Table
forgetValueAnns :: Value' a -> Value
decode' :: FromValue a => Text -> Result DecodeError a
decode :: FromValue a => Text -> Result String a
parse :: Text -> Either String (Table' Position)
data DecodeError
data Result e a
- = Failure [e]
- | Success [e] a
encode :: ToTable a => a -> TomlDoc
prettyToml :: Table' a -> TomlDoc
data DocClass
- = TableClass
- | KeyClass
- | StringClass
- | NumberClass
- | DateClass
- | BoolClass
prettyDecodeError :: DecodeError -> String
prettyLocated :: Located String -> String
prettyMatchMessage :: MatchMessage Position -> String
prettySemanticError :: SemanticError Position -> String

Types

type Table = Table' () Source #

A Value' with trivial annotations

type Value = Value' () Source #

A Value' with trivial annotations

Located types

data Located a Source #

A value annotated with its text file position

Constructors

Located
Fields locPosition :: !Position position locThing :: !a thing at position

Instances

Instances details

Foldable Located Source #	Default instance
Instance details Defined in Toml.Syntax.Position Methods fold :: Monoid m => Located m -> m # foldMap :: Monoid m => (a -> m) -> Located a -> m # foldMap' :: Monoid m => (a -> m) -> Located a -> m # foldr :: (a -> b -> b) -> b -> Located a -> b # foldr' :: (a -> b -> b) -> b -> Located a -> b # foldl :: (b -> a -> b) -> b -> Located a -> b # foldl' :: (b -> a -> b) -> b -> Located a -> b # foldr1 :: (a -> a -> a) -> Located a -> a # foldl1 :: (a -> a -> a) -> Located a -> a # toList :: Located a -> [a] # null :: Located a -> Bool # length :: Located a -> Int # elem :: Eq a => a -> Located a -> Bool # maximum :: Ord a => Located a -> a # minimum :: Ord a => Located a -> a # sum :: Num a => Located a -> a # product :: Num a => Located a -> a #
Traversable Located Source #	Default instance
Instance details Defined in Toml.Syntax.Position Methods traverse :: Applicative f => (a -> f b) -> Located a -> f (Located b) # sequenceA :: Applicative f => Located (f a) -> f (Located a) # mapM :: Monad m => (a -> m b) -> Located a -> m (Located b) # sequence :: Monad m => Located (m a) -> m (Located a) #
Functor Located Source #	Default instance
Instance details Defined in Toml.Syntax.Position Methods fmap :: (a -> b) -> Located a -> Located b # (<$) :: a -> Located b -> Located a #
Read a => Read (Located a) Source #	Default instance
Instance details Defined in Toml.Syntax.Position Methods readsPrec :: Int -> ReadS (Located a) # readList :: ReadS [Located a] # readPrec :: ReadPrec (Located a) # readListPrec :: ReadPrec [Located a] #
Show a => Show (Located a) Source #	Default instance
Instance details Defined in Toml.Syntax.Position Methods showsPrec :: Int -> Located a -> ShowS # show :: Located a -> String # showList :: [Located a] -> ShowS #

data Position Source #

A position in a text file

Constructors

Position
Fields posIndex :: !Int code-point index (zero-based) posLine :: !Int line index (one-based) posColumn :: !Int column index (one-based)

Instances

Instances details

Read Position Source #	Default instance
Instance details Defined in Toml.Syntax.Position Methods readsPrec :: Int -> ReadS Position # readList :: ReadS [Position] # readPrec :: ReadPrec Position # readListPrec :: ReadPrec [Position] #
Show Position Source #	Default instance
Instance details Defined in Toml.Syntax.Position Methods showsPrec :: Int -> Position -> ShowS # show :: Position -> String # showList :: [Position] -> ShowS #
Eq Position Source #	Default instance
Instance details Defined in Toml.Syntax.Position Methods (==) :: Position -> Position -> Bool # (/=) :: Position -> Position -> Bool #
Ord Position Source #	Default instance
Instance details Defined in Toml.Syntax.Position Methods compare :: Position -> Position -> Ordering # (<) :: Position -> Position -> Bool # (<=) :: Position -> Position -> Bool # (>) :: Position -> Position -> Bool # (>=) :: Position -> Position -> Bool # max :: Position -> Position -> Position # min :: Position -> Position -> Position #

newtype Table' a Source #

A table with annotated keys and values.

Constructors

MkTable (Map Text (a, Value' a))

Instances

Instances details

Foldable Table' Source #	Derived
Instance details Defined in Toml.Semantics.Types Methods fold :: Monoid m => Table' m -> m # foldMap :: Monoid m => (a -> m) -> Table' a -> m # foldMap' :: Monoid m => (a -> m) -> Table' a -> m # foldr :: (a -> b -> b) -> b -> Table' a -> b # foldr' :: (a -> b -> b) -> b -> Table' a -> b # foldl :: (b -> a -> b) -> b -> Table' a -> b # foldl' :: (b -> a -> b) -> b -> Table' a -> b # foldr1 :: (a -> a -> a) -> Table' a -> a # foldl1 :: (a -> a -> a) -> Table' a -> a # toList :: Table' a -> [a] # null :: Table' a -> Bool # length :: Table' a -> Int # elem :: Eq a => a -> Table' a -> Bool # maximum :: Ord a => Table' a -> a # minimum :: Ord a => Table' a -> a # sum :: Num a => Table' a -> a # product :: Num a => Table' a -> a #
Traversable Table' Source #	Derived
Instance details Defined in Toml.Semantics.Types Methods traverse :: Applicative f => (a -> f b) -> Table' a -> f (Table' b) # sequenceA :: Applicative f => Table' (f a) -> f (Table' a) # mapM :: Monad m => (a -> m b) -> Table' a -> m (Table' b) # sequence :: Monad m => Table' (m a) -> m (Table' a) #
Functor Table' Source #	Derived
Instance details Defined in Toml.Semantics.Types Methods fmap :: (a -> b) -> Table' a -> Table' b # (<$) :: a -> Table' b -> Table' a #
FromValue Table Source #
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Table Source # listFromValue :: Value' l -> Matcher l [Table] Source #
Read a => Read (Table' a) Source #	Default instance
Instance details Defined in Toml.Semantics.Types Methods readsPrec :: Int -> ReadS (Table' a) # readList :: ReadS [Table' a] # readPrec :: ReadPrec (Table' a) # readListPrec :: ReadPrec [Table' a] #
Show a => Show (Table' a) Source #	Default instance
Instance details Defined in Toml.Semantics.Types Methods showsPrec :: Int -> Table' a -> ShowS # show :: Table' a -> String # showList :: [Table' a] -> ShowS #
Eq a => Eq (Table' a) Source #	Default instance
Instance details Defined in Toml.Semantics.Types Methods (==) :: Table' a -> Table' a -> Bool # (/=) :: Table' a -> Table' a -> Bool #
ToTable (Table' a) Source #
Instance details Defined in Toml.Schema.ToValue Methods toTable :: Table' a -> Table Source #
ToValue (Table' a) Source #
Instance details Defined in Toml.Schema.ToValue Methods toValue :: Table' a -> Value Source # toValueList :: [Table' a] -> Value Source #

data Value' a Source #

Semantic TOML value with all table assignments resolved.

Constructors

Integer' a Integer
Double' a Double
List' a [Value' a]
Table' a (Table' a)
Bool' a Bool
Text' a Text
TimeOfDay' a TimeOfDay
ZonedTime' a ZonedTime
LocalTime' a LocalTime
Day' a Day

Bundled Patterns

pattern Bool :: Bool -> Value
pattern Double :: Double -> Value
pattern List :: [Value] -> Value
pattern Integer :: Integer -> Value
pattern Text :: Text -> Value
pattern Table :: Table -> Value
pattern Day :: Day -> Value
pattern TimeOfDay :: TimeOfDay -> Value
pattern LocalTime :: LocalTime -> Value
pattern ZonedTime :: ZonedTime -> Value

Instances

Instances details

Foldable Value' Source #	Derived
Instance details Defined in Toml.Semantics.Types Methods fold :: Monoid m => Value' m -> m # foldMap :: Monoid m => (a -> m) -> Value' a -> m # foldMap' :: Monoid m => (a -> m) -> Value' a -> m # foldr :: (a -> b -> b) -> b -> Value' a -> b # foldr' :: (a -> b -> b) -> b -> Value' a -> b # foldl :: (b -> a -> b) -> b -> Value' a -> b # foldl' :: (b -> a -> b) -> b -> Value' a -> b # foldr1 :: (a -> a -> a) -> Value' a -> a # foldl1 :: (a -> a -> a) -> Value' a -> a # toList :: Value' a -> [a] # null :: Value' a -> Bool # length :: Value' a -> Int # elem :: Eq a => a -> Value' a -> Bool # maximum :: Ord a => Value' a -> a # minimum :: Ord a => Value' a -> a # sum :: Num a => Value' a -> a # product :: Num a => Value' a -> a #
Traversable Value' Source #	Derived
Instance details Defined in Toml.Semantics.Types Methods traverse :: Applicative f => (a -> f b) -> Value' a -> f (Value' b) # sequenceA :: Applicative f => Value' (f a) -> f (Value' a) # mapM :: Monad m => (a -> m b) -> Value' a -> m (Value' b) # sequence :: Monad m => Value' (m a) -> m (Value' a) #
Functor Value' Source #	Derived
Instance details Defined in Toml.Semantics.Types Methods fmap :: (a -> b) -> Value' a -> Value' b # (<$) :: a -> Value' b -> Value' a #
FromValue Value Source #	Matches all values, used for pass-through
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Value Source # listFromValue :: Value' l -> Matcher l [Value] Source #
ToValue Value Source #	Identity function
Instance details Defined in Toml.Schema.ToValue Methods toValue :: Value -> Value Source # toValueList :: [Value] -> Value Source #
() ~ a => IsString (Value' a) Source #	Constructs a TOML string literal. fromString = String
Instance details Defined in Toml.Semantics.Types Methods fromString :: String -> Value' a #
Read a => Read (Value' a) Source #	Default instance
Instance details Defined in Toml.Semantics.Types Methods readsPrec :: Int -> ReadS (Value' a) # readList :: ReadS [Value' a] # readPrec :: ReadPrec (Value' a) # readListPrec :: ReadPrec [Value' a] #
Show a => Show (Value' a) Source #	Default instance
Instance details Defined in Toml.Semantics.Types Methods showsPrec :: Int -> Value' a -> ShowS # show :: Value' a -> String # showList :: [Value' a] -> ShowS #
Eq a => Eq (Value' a) Source #	Nearly default instance except `ZonedTime` doesn't have an `Eq` instance. `ZonedTime` values are equal if their times and time-zones are both equal.
Instance details Defined in Toml.Semantics.Types Methods (==) :: Value' a -> Value' a -> Bool # (/=) :: Value' a -> Value' a -> Bool #

valueAnn :: Value' a -> a Source #

Extract the top-level annotation from a value.

valueType :: Value' l -> String Source #

String representation of the kind of value using TOML vocabulary

forgetTableAnns :: Table' a -> Table Source #

Replaces annotations with a unit.

forgetValueAnns :: Value' a -> Value Source #

Replaces annotations with a unit.

Parsing

decode' :: FromValue a => Text -> Result DecodeError a Source #

Decode TOML syntax into an application value.

decode :: FromValue a => Text -> Result String a Source #

Wrapper rending error and warning messages into human-readable strings.

parse :: Text -> Either String (Table' Position) Source #

Parse a TOML formatted String or report a human-readable error message.

data DecodeError Source #

Sum of errors that can occur during TOML decoding

data Result e a Source #

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.

Constructors

Failure [e]	error messages
Success [e] a	warning messages and result

Instances

Instances details

(Read e, Read a) => Read (Result e a) Source #	Default instance
Instance details Defined in Toml.Schema.Matcher Methods readsPrec :: Int -> ReadS (Result e a) # readList :: ReadS [Result e a] # readPrec :: ReadPrec (Result e a) # readListPrec :: ReadPrec [Result e a] #
(Show e, Show a) => Show (Result e a) Source #	Default instance
Instance details Defined in Toml.Schema.Matcher Methods showsPrec :: Int -> Result e a -> ShowS # show :: Result e a -> String # showList :: [Result e a] -> ShowS #
(Eq e, Eq a) => Eq (Result e a) Source #	Default instance
Instance details Defined in Toml.Schema.Matcher Methods (==) :: Result e a -> Result e a -> Bool # (/=) :: Result e a -> Result e a -> Bool #
(Ord e, Ord a) => Ord (Result e a) Source #	Default instance
Instance details Defined in Toml.Schema.Matcher Methods compare :: Result e a -> Result e a -> Ordering # (<) :: Result e a -> Result e a -> Bool # (<=) :: Result e a -> Result e a -> Bool # (>) :: Result e a -> Result e a -> Bool # (>=) :: Result e a -> Result e a -> Bool # max :: Result e a -> Result e a -> Result e a # min :: Result e a -> Result e a -> Result e a #

Printing

encode :: ToTable a => a -> TomlDoc Source #

Use the ToTable instance to encode a value to a TOML string.

prettyToml Source #

Arguments

:: Table' a	table to print
-> TomlDoc	TOML syntax

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 prettyTomlOrdered.

data DocClass Source #

Annotation used to enable styling pretty-printed TOML

Constructors

TableClass	top-level `[key]` and `[[key]]`
KeyClass	dotted keys, left-hand side of assignments
StringClass	string literals
NumberClass	number literals
DateClass	date and time literals
BoolClass	boolean literals

Instances

Instances details

Read DocClass Source #
Instance details Defined in Toml.Pretty Methods readsPrec :: Int -> ReadS DocClass # readList :: ReadS [DocClass] # readPrec :: ReadPrec DocClass # readListPrec :: ReadPrec [DocClass] #
Show DocClass Source #
Instance details Defined in Toml.Pretty Methods showsPrec :: Int -> DocClass -> ShowS # show :: DocClass -> String # showList :: [DocClass] -> ShowS #
Eq DocClass Source #
Instance details Defined in Toml.Pretty Methods (==) :: DocClass -> DocClass -> Bool # (/=) :: DocClass -> DocClass -> Bool #
Ord DocClass Source #
Instance details Defined in Toml.Pretty Methods compare :: DocClass -> DocClass -> Ordering # (<) :: DocClass -> DocClass -> Bool # (<=) :: DocClass -> DocClass -> Bool # (>) :: DocClass -> DocClass -> Bool # (>=) :: DocClass -> DocClass -> Bool # max :: DocClass -> DocClass -> DocClass # min :: DocClass -> DocClass -> DocClass #

Error rendering

prettyDecodeError :: DecodeError -> String Source #

Human-readable representation of a DecodeError

prettyLocated :: Located String -> String Source #

Pretty-print as line:col: message

prettyMatchMessage :: MatchMessage Position -> String Source #

Render a TOML decoding error as a human-readable string.

prettySemanticError :: SemanticError Position -> String Source #

Render a semantic TOML error in a human-readable string.