Toml

toml-parser-2.0.1.0: TOML 1.0.0 parser

Copyright | (c) Eric Mertens 2023
License | ISC
Maintainer | emertens@gmail.com
Safe Haskell | None
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' () #

A `Table'` with trivial annotations

type Value = Value' () #

A `Value'` with trivial annotations

# Located types

data Located a #

A value annotated with its text file position

Constructors

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

#### Instances

Instances details

Functor Located # | Default instance
Instance details Defined in Toml.Syntax.Position Methods fmap :: (a -> b) -> Located a -> Located b # (<$) :: a -> Located b -> Located a #
Foldable Located # | 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 # | 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) #
Read a => Read (Located a) # | 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) # | 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 #

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 # | 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 # | Default instance
Instance details Defined in Toml.Syntax.Position Methods showsPrec :: Int -> Position -> ShowS # show :: Position -> String # showList :: [Position] -> ShowS #
Eq Position # | Default instance
Instance details Defined in Toml.Syntax.Position Methods (==) :: Position -> Position -> Bool # (/=) :: Position -> Position -> Bool #
Ord Position # | 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 #

A table with annotated keys and values.

Constructors

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

#### Instances

Instances details

Functor Table' # | Derived
Instance details Defined in Toml.Semantics.Types Methods fmap :: (a -> b) -> Table' a -> Table' b # (<$) :: a -> Table' b -> Table' a #
Foldable Table' # | 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' # | 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) #
FromValue Table # |
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Table # listFromValue :: Value' l -> Matcher l [Table] #
Read a => Read (Table' a) # | 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) # | 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) # | Default instance
Instance details Defined in Toml.Semantics.Types Methods (==) :: Table' a -> Table' a -> Bool # (/=) :: Table' a -> Table' a -> Bool #
ToTable (Table' a) # |
Instance details Defined in Toml.Schema.ToValue Methods toTable :: Table' a -> Table #
ToValue (Table' a) # |
Instance details Defined in Toml.Schema.ToValue Methods toValue :: Table' a -> Value # toValueList :: [Table' a] -> Value #

data Value' a #

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

Functor Value' # | Derived
Instance details Defined in Toml.Semantics.Types Methods fmap :: (a -> b) -> Value' a -> Value' b # (<$) :: a -> Value' b -> Value' a #
Foldable Value' # | 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' # | 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) #
FromValue Value # | Matches all values, used for pass-through
Instance details Defined in Toml.Schema.FromValue Methods fromValue :: Value' l -> Matcher l Value # listFromValue :: Value' l -> Matcher l [Value] #
ToValue Value # | Identity function
Instance details Defined in Toml.Schema.ToValue Methods toValue :: Value -> Value # toValueList :: [Value] -> Value #
() ~ a => IsString (Value' a) # | Constructs a TOML string literal.
    fromString = String
Instance details Defined in Toml.Semantics.Types Methods fromString :: String -> Value' a #
Read a => Read (Value' a) # | 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) # | 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) # | 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 #

Extract the top-level annotation from a value.

valueType :: Value' l -> String #

String representation of the kind of value using TOML vocabulary

forgetTableAnns :: Table' a -> Table #

Replaces annotations with a unit.

forgetValueAnns :: Value' a -> Value #

Replaces annotations with a unit.

# Parsing

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

Decode TOML syntax into an application value.

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

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

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

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

data DecodeError #

Sum of errors that can occur during TOML decoding

data Result e 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.

Constructors

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

#### Instances

Instances details

(Read e, Read a) => Read (Result e a) # | 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) # | 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) # | 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) # | 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 #

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

prettyToml #

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 #

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 # |
Instance details Defined in Toml.Pretty Methods readsPrec :: Int -> ReadS DocClass # readList :: ReadS [DocClass] # readPrec :: ReadPrec DocClass # readListPrec :: ReadPrec [DocClass] #
Show DocClass # |
Instance details Defined in Toml.Pretty Methods showsPrec :: Int -> DocClass -> ShowS # show :: DocClass -> String # showList :: [DocClass] -> ShowS #
Eq DocClass # |
Instance details Defined in Toml.Pretty Methods (==) :: DocClass -> DocClass -> Bool # (/=) :: DocClass -> DocClass -> Bool #
Ord DocClass # |
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 #

Human-readable representation of a `DecodeError`

prettyLocated :: Located String -> String #

Pretty-print as `line:col: message`

prettyMatchMessage :: MatchMessage Position -> String #

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

prettySemanticError :: SemanticError Position -> String #

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