toml-reader: TOML format parser compliant with v1.0.0.

[ bsd3, configuration, library, text, toml ] [ Propose Tags ] [ Report a vulnerability ]

TOML format parser compliant with v1.0.0. See README.md for more details.


[Skip to Readme]

Downloads

Note: This package has metadata revisions in the cabal description newer than included in the tarball. To unpack the package including the revisions, use 'cabal get'.

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.1.0.0, 0.2.0.0, 0.2.1.0
Change log CHANGELOG.md
Dependencies base (>=4.15 && <5), containers (<0.8), megaparsec (<10), parser-combinators (<1.4), text (<3), time (<1.15) [details]
License BSD-3-Clause
Author Brandon Chinn <brandonchinn178@gmail.com>
Maintainer Brandon Chinn <brandonchinn178@gmail.com>
Revised Revision 4 made by brandonchinn178 at 2024-03-12T04:23:48Z
Category TOML, Text, Configuration
Home page https://github.com/brandonchinn178/toml-reader#readme
Bug tracker https://github.com/brandonchinn178/toml-reader/issues
Source repo head: git clone https://github.com/brandonchinn178/toml-reader
Uploaded by brandonchinn178 at 2023-06-13T04:45:44Z
Distributions LTSHaskell:0.2.1.0, NixOS:0.2.1.0, Stackage:0.2.1.0
Reverse Dependencies 3 direct, 1 indirect [details]
Downloads 912 total (22 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2023-06-13 [all 1 reports]

Readme for toml-reader-0.2.1.0

[back to package description]

toml-reader

GitHub Actions

TOML format parser compliant with v1.0.0 (verified with the toml-test tool).

Usage

{-# LANGUAGE OverloadedStrings #-}

import TOML (DecodeTOML, tomlDecoder, getField, decodeFile)

data MyConfig = MyConfig
  { field1 :: Int
  , field2 :: Bool
  } deriving (Show)

instance DecodeTOML MyConfig where
  tomlDecoder =
    MyConfig
      <$> getField "field1"
      <*> getField "field2"

main :: IO ()
main = do
  result <- decodeFile "config.toml"
  case result of
    Right cfg -> print (cfg :: MyConfig)
    Left e -> print e

Design decisions

  • Only supports reading, not writing, since TOML is lossy. For example, a simple a.b.c = 1 line could be written in a number of ways:

    a.b.c = 1
    a.b = { c = 1 }
    a = { b.c = 1 }
    
    [a]
    b.c = 1
    b = { c = 1 }
    
    [a.b]
    c = 1
    

    Since reading/writing isn't an idempotent operation, this library won't even pretend to provide DecodeTOML/EncodeTOML typeclasses that imply that they're inverses of each other.

    Hopefully some other toml-writer library may come along to make it easy to specify how to format your data in TOML (e.g. a combinator for table vs inlineTable), or you could use tomland.

  • This library defines DecodeTOML with an opaque Decoder a as opposed to a Value -> DecodeM a function, like aeson does. In my opinion, this makes the common case of decoding config files much more straightforward, especially around nested fields, which are much more common in TOML than JSON. e.g.

    -- aeson-like
    instance DecodeTOML MyConfig where
      decodeTOML :: Value -> DecodeM MyConfig
      decodeTOML = withObject "MyConfig" $ \o ->
        MyConfig
          <$> o .: "field1"
          <*> (o .: "field2" >>= (.: "field3"))
    
    -- with toml-parser
    instance DecodeTOML MyConfig where
      tomlDecoder :: Decoder MyConfig
      tomlDecoder =
        MyConfig
          <$> getField "field1"
          <*> getFields ["field2", "field3"]
    

    It also makes it easy to define ad-hoc decoders:

    instance DecodeTOML MyConfig where
      tomlDecoder = ...
    
    alternativeDecoder :: Decoder MyConfig
    alternativeDecoder = ...
    
    -- uses tomlDecoder
    decode "a = 1"
    
    -- uses explicit decoder
    decodeWith alternativeDecoder "a = 1"
    

    As a bonus, it also makes for a less point-free interface when defining a decoder based on another decoder, which is kinda cool:

    -- aeson-like
    instance DecodeTOML MyString where
      decodeTOML = fmap toMyString . decodeTOML
    
    -- with toml-parser
    instance DecodeTOML MyString where
      tomlDecoder = toMyString <$> tomlDecoder
    

    Ultimately, Decoder is just a newtype around Value -> DecodeM a, so we could always go back to it. Originally, I wanted to do something like jordan, where this interface is required due to the way it parses and deserializes at the same time, but this isn't possible with TOML due to the way TOML needs to be normalized.