Toml.Pretty

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

Contents

- Types
- Printing semantic values
- Printing syntactic components
- Printing keys
- Locations

Description

This module provides human-readable renderers for types used in this package to assist error message production.

The generated `Doc` values are annotated with `DocClass` values to assist in producing syntax-highlighted outputs.

To extract a plain String representation, use `show`.

Synopsis

- type TomlDoc = Doc DocClass
- data DocClass
  - = TableClass
  - | KeyClass
  - | StringClass
  - | NumberClass
  - | DateClass
  - | BoolClass
- prettyToml :: Table' a -> TomlDoc
- prettyTomlOrdered :: Ord a => ([Text] -> Text -> a) -> Table' l -> TomlDoc
- prettyValue :: Value' l -> TomlDoc
- prettyToken :: Token -> String
- prettySectionKind :: SectionKind -> NonEmpty Text -> TomlDoc
- prettySimpleKey :: Text -> Doc a
- prettyKey :: NonEmpty Text -> TomlDoc
- prettyLocated :: Located String -> String
- prettyPosition :: Position -> String

# Types

type TomlDoc = Doc DocClass #

Pretty-printer document with TOML class attributes to aid in syntax-highlighting.

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 #

# Printing semantic values

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

prettyTomlOrdered #

Arguments

:: Ord a |
=> ([Text] -> Text -> a) | table path -> key -> projection
-> Table' l | table to print
-> TomlDoc | TOML syntax

Render a complete TOML document like `prettyToml` 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 `[package]` section first before any of the ancillary configuration sections.

The table path is the name of the table being sorted. This allows the projection to be aware of which table is being sorted.

The key 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 `package` section first, the `secondary` section second, and then all remaining cases are sorted alphabetically afterward.

    example :: [String] -> String -> Either Int String
    example [] "package" = Left 1
    example [] "second"  = Left 2
    example _  other     = Right other

We could also put the tables in reverse-alphabetical order by leveraging an existing newtype.

    reverseOrderProj :: [String] -> String -> Down String
    reverseOrderProj _ = Down

prettyValue :: Value' l -> 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.

# Printing syntactic components

prettyToken :: Token -> String #

Render token for human-readable error messages.

prettySectionKind :: SectionKind -> NonEmpty Text -> TomlDoc #

Pretty-print a section heading. The result is annotated as a `TableClass`.

# Printing keys

prettySimpleKey :: Text -> Doc a #

Renders a simple-key using quotes where necessary.

prettyKey :: NonEmpty Text -> TomlDoc #

Renders a dotted-key using quotes where necessary and annotated as a `KeyClass`.

# Locations

prettyLocated :: Located String -> String #

Pretty-print as `line:col: message`

prettyPosition :: Position -> String #

Pretty-print as `line:col`