configurator-pg

Reduced parser for configurator-ng config files

https://github.com/robx/configurator-pg

Version on this page:0.2.4
LTS Haskell 22.14:0.2.10
Stackage Nightly 2024-03-28:0.2.10
Latest on Hackage:0.2.10

See all snapshots configurator-pg appears in

BSD-3-Clause licensed by Robert Vollmert
Maintained by [email protected]
This version can be pinned in stack with:configurator-pg-0.2.4@sha256:62a02e84ad6c534168fe017becb816bd5bea5fb6f244d4368796846453b2048b,2844

Module documentation for 0.2.4

What is this?

This is a simplified version of the resting configurator-ng, aimed particularly to offer users of configurator-ng such as PostgREST an easy path to migrate to a package that compiles with modern GHC versions and that continues to read existing configuration files.

Changes

configurator-pg skips some of configurator-ng’s features, and changes the API in other places:

  • No configuration file reloading.
  • Simplified parsing API:
    • There is no type-class based value parsing; you need to supply explicit value parsers.
    • There’s only load to read and evaluate a configuration file, and runParser to extract configuration values.
  • Simpler error handling and improved logging of parse errors.
  • Simplified handling of configuration subsets. There’s subassocs and the unit tests pass, but the author didn’t attempt to understand the original implementation fully.

Credits

The original configurator-ng is due to MailRank, Inc., Bryan O’Sullivan and Leon P Smith.

The low-level parser (Data.Configurator.Syntax) was initially mostly unchanged, but has since been rewritten with Megaparsec for better error messages. The evaluation (Data.Configurator.Load) is still close to the original. The high-level parser (Data.Configurator.Parser) is original.

File format

In short, the file format supports:

  • A simple but flexible configuration language that supports several of the most commonly needed types of data, along with interpolation of strings from the configuration or the system environment (e.g. $(HOME)).

  • An import directive allows the configuration of a complex application to be split across several smaller files, or common configuration data to be shared across several applications.

The format is more fully documented in the packages configurator and configurator-ng.

Here’s an example:

# listen address
hostname = "localhost"
port = 8000

logdir = "$(HOME)/logs"
logfile = "$(logdir)/log.txt"
loglevels = [1, 4, 5]

users {
  alice = "[email protected]"
  bob   = "[email protected]"
}

# passwords.txt might contain
#   alice = "12345"
#   bob   = "sesame"
passwords {
  import "secrets/passwords.txt"
}

Usage

The following code can be used to parse the example above.

import Data.Configurator

data Settings = Settings
  { hostname  :: Text
  , port      :: Int
  , logfile   :: Maybe FilePath
  , loglevels :: Maybe [Int]
  , users     :: [(Text, Text)]
  , passwords :: [(Text, Text)]
  }

settingsParser :: Parser Config Settings
settingsParser =
  Settings
    <$> required "hostname" string
    <*> (Maybe.withDefault 1234 <$> optional "port" int)
    <*> optional "logfile" (pack <$> string)
    <*> optional "loglevels" (list int)
    <*> subassocs "users" string
    <*> subassocs "passwords" string

loadSettings :: IO Settings
loadSettings = do
  cfg <- load "settings.cfg"
  case runParser settingsParser cfg of
    Left err       -> die $ "reading config: " <> err
    Right settings -> return settings

Though note that for no apparent reason, subassocs returns the full key, whence the parsed list of users will be

    [ ("users.alice", "[email protected]")
    , ("users.bob", "[email protected]")
    ]

Changes

Revision history for configurator-pg

0.2.4 – 2020-09-04

  • Allow megaparsec-9.0.

0.2.3 – 2020-04-19

  • Drop support for GHC 7.10.

0.2.2 – 2020-04-07

  • Support GHC 8.10.

0.2.1 – 2020-03-11

  • Include test output files in source release.

0.2.0 – 2020-03-10

  • Rewrite file parser with Megaparsec instead of Attoparsec for better error messages. No expected change in functionality except possibly in pathological cases.

0.1.0.6 – 2020-03-08

  • Fix GHC 7.10 build by depending on package fail.

0.1.0.5 – 2020-03-07

  • Provide a MonadFail instance for Parser. This fixes a PostgREST compile failure with GHC 8.8.3.

0.1.0.4 – 2020-03-07

  • Relax bounds to support GHC 8.8.3.

0.1.0.3 – 2019-06-04

  • Include another missing test data file.

0.1.0.2 – 2019-06-04

  • Lower bounds to support GHC 7.10.3.
  • Include test data to fix tests.

0.1.0.1 – 2019-06-03

  • Include README.md in release.

0.1.0.0 – 2019-06-03

  • First version.