toml-parser-2.0.2.0: TOML 1.1.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.1.0 https://toml.io/en/v1.1.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 `Table'` 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

Functor Located Source # | Default instance
Instance details Defined in Toml.Syntax.Position Methods fmap :: (a -> b) -> Located a -> Located b Source # (<$) :: a -> Located b -> Located a Source #
Foldable Located Source # | Default instance

Instance details

Defined in Toml.Syntax.Position

Methods

fold :: Monoid m => Located m -> m Source #

foldMap :: Monoid m => (a -> m) -> Located a -> m Source #

foldMap' :: Monoid m => (a -> m) -> Located a -> m Source #

foldr :: (a -> b -> b) -> b -> Located a -> b Source #

foldr' :: (a -> b -> b) -> b -> Located a -> b Source #

foldl :: (b -> a -> b) -> b -> Located a -> b Source #

foldl' :: (b -> a -> b) -> b -> Located a -> b Source #

foldr1 :: (a -> a -> a) -> Located a -> a Source #

foldl1 :: (a -> a -> a) -> Located a -> a Source #

toList :: Located a -> [a] Source #

null :: Located a -> Bool Source #

length :: Located a -> Int Source #

elem :: Eq a => a -> Located a -> Bool Source #

maximum :: Ord a => Located a -> a Source #

minimum :: Ord a => Located a -> a Source #

sum :: Num a => Located a -> a Source #

product :: Num a => Located a -> a Source #

Traversable Located Source # | Default instance
Instance details Defined in Toml.Syntax.Position Methods traverse :: Applicative f => (a -> f b) -> Located a -> f (Located b) Source # sequenceA :: Applicative f => Located (f a) -> f (Located a) Source # mapM :: Monad m => (a -> m b) -> Located a -> m (Located b) Source # sequence :: Monad m => Located (m a) -> m (Located a) Source #
Read a => Read (Located a) Source # | Default instance
Instance details Defined in Toml.Syntax.Position Methods readsPrec :: Int -> ReadS (Located a) Source # readList :: ReadS [Located a] Source # readPrec :: ReadPrec (Located a) Source # readListPrec :: ReadPrec [Located a] Source #
Show a => Show (Located a) Source # | Default instance
Instance details Defined in Toml.Syntax.Position Methods showsPrec :: Int -> Located a -> ShowS Source # show :: Located a -> String Source # showList :: [Located a] -> ShowS Source #

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

newtype Table' a Source #

A table with annotated keys and values.

Constructors

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

#### Instances

Instances details

Functor Table' Source # | Derived
Instance details Defined in Toml.Semantics.Types Methods fmap :: (a -> b) -> Table' a -> Table' b Source # (<$) :: a -> Table' b -> Table' a Source #
Foldable Table' Source # | Derived

Instance details

Defined in Toml.Semantics.Types

Methods

fold :: Monoid m => Table' m -> m Source #

foldMap :: Monoid m => (a -> m) -> Table' a -> m Source #

foldMap' :: Monoid m => (a -> m) -> Table' a -> m Source #

foldr :: (a -> b -> b) -> b -> Table' a -> b Source #

foldr' :: (a -> b -> b) -> b -> Table' a -> b Source #

foldl :: (b -> a -> b) -> b -> Table' a -> b Source #

foldl' :: (b -> a -> b) -> b -> Table' a -> b Source #

foldr1 :: (a -> a -> a) -> Table' a -> a Source #

foldl1 :: (a -> a -> a) -> Table' a -> a Source #

toList :: Table' a -> [a] Source #

null :: Table' a -> Bool Source #

length :: Table' a -> Int Source #

elem :: Eq a => a -> Table' a -> Bool Source #

maximum :: Ord a => Table' a -> a Source #

minimum :: Ord a => Table' a -> a Source #

sum :: Num a => Table' a -> a Source #

product :: Num a => Table' a -> a Source #

Traversable Table' Source # | Derived
Instance details Defined in Toml.Semantics.Types Methods traverse :: Applicative f => (a -> f b) -> Table' a -> f (Table' b) Source # sequenceA :: Applicative f => Table' (f a) -> f (Table' a) Source # mapM :: Monad m => (a -> m b) -> Table' a -> m (Table' b) Source # sequence :: Monad m => Table' (m a) -> m (Table' a) Source #
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) Source # readList :: ReadS [Table' a] Source # readPrec :: ReadPrec (Table' a) Source # readListPrec :: ReadPrec [Table' a] Source #
Show a => Show (Table' a) Source # | Default instance
Instance details Defined in Toml.Semantics.Types Methods showsPrec :: Int -> Table' a -> ShowS Source # show :: Table' a -> String Source # showList :: [Table' a] -> ShowS Source #
Eq a => Eq (Table' a) Source # | Default instance
Instance details Defined in Toml.Semantics.Types Methods (==) :: Table' a -> Table' a -> Bool Source # (/=) :: Table' a -> Table' a -> Bool Source #
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

Functor Value' Source # | Derived
Instance details Defined in Toml.Semantics.Types Methods fmap :: (a -> b) -> Value' a -> Value' b Source # (<$) :: a -> Value' b -> Value' a Source #
Foldable Value' Source # | Derived

Instance details

Defined in Toml.Semantics.Types

Methods

fold :: Monoid m => Value' m -> m Source #

foldMap :: Monoid m => (a -> m) -> Value' a -> m Source #

foldMap' :: Monoid m => (a -> m) -> Value' a -> m Source #

foldr :: (a -> b -> b) -> b -> Value' a -> b Source #

foldr' :: (a -> b -> b) -> b -> Value' a -> b Source #

foldl :: (b -> a -> b) -> b -> Value' a -> b Source #

foldl' :: (b -> a -> b) -> b -> Value' a -> b Source #

foldr1 :: (a -> a -> a) -> Value' a -> a Source #

foldl1 :: (a -> a -> a) -> Value' a -> a Source #

toList :: Value' a -> [a] Source #

null :: Value' a -> Bool Source #

length :: Value' a -> Int Source #

elem :: Eq a => a -> Value' a -> Bool Source #

maximum :: Ord a => Value' a -> a Source #

minimum :: Ord a => Value' a -> a Source #

sum :: Num a => Value' a -> a Source #

product :: Num a => Value' a -> a Source #

Traversable Value' Source # | Derived
Instance details Defined in Toml.Semantics.Types Methods traverse :: Applicative f => (a -> f b) -> Value' a -> f (Value' b) Source # sequenceA :: Applicative f => Value' (f a) -> f (Value' a) Source # mapM :: Monad m => (a -> m b) -> Value' a -> m (Value' b) Source # sequence :: Monad m => Value' (m a) -> m (Value' a) Source #
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 Source #
Read a => Read (Value' a) Source # | Default instance
Instance details Defined in Toml.Semantics.Types Methods readsPrec :: Int -> ReadS (Value' a) Source # readList :: ReadS [Value' a] Source # readPrec :: ReadPrec (Value' a) Source # readListPrec :: ReadPrec [Value' a] Source #
Show a => Show (Value' a) Source # | Default instance
Instance details Defined in Toml.Semantics.Types Methods showsPrec :: Int -> Value' a -> ShowS Source # show :: Value' a -> String Source # showList :: [Value' a] -> ShowS Source #
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 Source # (/=) :: Value' a -> Value' a -> Bool Source #

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) Source # readList :: ReadS [Result e a] Source # readPrec :: ReadPrec (Result e a) Source # readListPrec :: ReadPrec [Result e a] Source #
(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 Source # show :: Result e a -> String Source # showList :: [Result e a] -> ShowS Source #
(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 Source # (/=) :: Result e a -> Result e a -> Bool Source #
(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 Source #

(<) :: Result e a -> Result e a -> Bool Source #

(<=) :: Result e a -> Result e a -> Bool Source #

(>) :: Result e a -> Result e a -> Bool Source #

(>=) :: Result e a -> Result e a -> Bool Source #

max :: Result e a -> Result e a -> Result e a Source #

min :: Result e a -> Result e a -> Result e a Source #

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

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