Data.Configifier

config types

data a :*> b infixr 6

Construction of config records (cons for record fields).

Constructors

a :*> b infixr 6

Instances

(Eq a, Eq b) => Eq ((:*>) a b)

(Ord a, Ord b) => Ord ((:*>) a b)

(Show a, Show b) => Show ((:*>) a b)

Typeable (* -> * -> *) (:*>)

data s :> t infixr 9

Construction of config record fields.

Instances

Typeable (Symbol -> * -> *) (:>)

data a :>: s infixr 8

Add descriptive text to record field for documentation.

Instances

Typeable (k -> Symbol -> *) ((:>:) k)

data ConfigCode k

Constructors

Record (ConfigCode k) (ConfigCode k) infixr 6

Label Symbol (ConfigCode k)

Descr (ConfigCode k) Symbol

List (ConfigCode k)

Option (ConfigCode k)

Type k

type family ToConfigCode a :: ConfigCode *

Map user-provided config type to ConfigCode types.

Equations

ToConfigCode (a :*> b) = Record (ToConfigCode a) (ToConfigCode b)

ToConfigCode (s :> a) = Label s (ToConfigCode a)

ToConfigCode (a :>: s) = Descr (ToConfigCode a) s

ToConfigCode [a] = List (ToConfigCode a)

ToConfigCode (Maybe a) = Option (ToConfigCode a)

ToConfigCode a = Type a

type family NoDesc a :: ConfigCode *

Filter Descr constructors from ConfigCode.

Equations

NoDesc (Record a b) = Record (NoDesc a) (NoDesc b)

NoDesc (Label s a) = Label s (NoDesc a)

NoDesc (Descr a s) = NoDesc a

NoDesc (List a) = List (NoDesc a)

NoDesc (Option a) = Option (NoDesc a)

NoDesc (Type a) = Type a

type family ToConfig a f :: *

Map ConfgCode types to the types of config values.

Equations

ToConfig (Record a b) f = ToConfig a f :*> ToConfig b f

ToConfig (Label s a) f = f (ToConfig a f)

ToConfig (List a) f = [ToConfig a f]

ToConfig (Option a) f = MaybeO (ToConfig a f)

ToConfig (Type a) f = a

data MaybeO a

MaybeO is isomorphic to Maybe, but is only used for Option values.

Constructors

JustO a

NothingO

Instances

Eq a => Eq (MaybeO a)

Ord a => Ord (MaybeO a)

Show a => Show (MaybeO a)

Typeable (* -> *) MaybeO

data Id a

Transformers' Identity is not in Typeable, so we roll our own. It's also less work to write.

Constructors

Id a

Instances

Eq a => Eq (Id a)

Ord a => Ord (Id a)

Show a => Show (Id a)

Typeable (* -> *) Id

sources

data Source

Constructors

ConfigFileYaml SBS

ShellEnv [(String, String)]

CommandLine [String]

Instances

Eq Source

Ord Source

Show Source

Typeable * Source

data ConfigFile

Instances

HasRenderDoc * ConfigFile

data ShellEnv

Instances

HasRenderDoc * ShellEnv

data CommandLine

Instances

HasRenderDoc * CommandLine

tagged values

data Tagged cfg

Constructors

Tagged

Fields

fromTagged :: ToConfig cfg Id

Instances

Eq (ToConfig cfg Id) => Eq (Tagged cfg)

Show (ToConfig cfg Id) => Show (Tagged cfg)

data TaggedM cfg

Constructors

TaggedM

Fields

fromTaggedM :: ToConfig cfg Maybe

Instances

Eq (ToConfig cfg Maybe) => Eq (TaggedM cfg)

Show (ToConfig cfg Maybe) => Show (TaggedM cfg)

ToJSON a => ToJSON (TaggedM (Type * a))

instance ToJSON Type

((~) * t (ToConfig cfg Maybe), (~) * (ToConfig (Option * cfg) Maybe) (MaybeO t''), ToJSON (TaggedM cfg)) => ToJSON (TaggedM (Option * cfg))

instance ToJSON Option

((~) * t (ToConfig cfg Maybe), ToJSON (TaggedM cfg)) => ToJSON (TaggedM (List * cfg))

instance ToJSON List

(ToJSON (TaggedM cfg), KnownSymbol s) => ToJSON (TaggedM (Label * s cfg))

instance ToJSON Label

((~) * t1 (ToConfig cfg1 Maybe), ToJSON (TaggedM cfg1), (~) * t2 (ToConfig cfg2 Maybe), ToJSON (TaggedM cfg2)) => ToJSON (TaggedM (Record * cfg1 cfg2))

instance ToJSON Record

FromJSON a => FromJSON (TaggedM (Type * a))

instance FromJSON Type

FromJSON (TaggedM cfg) => FromJSON (TaggedM (Option * cfg))

instance ParseJSON Option

FromJSON (TaggedM cfg) => FromJSON (TaggedM (List * cfg))

instance ParseJSON List

(FromJSON (TaggedM cfg), KnownSymbol s) => FromJSON (TaggedM (Label * s cfg))

instance FromJSON Label (tolerates unknown fields in json object.)

(FromJSON (TaggedM cfg1), FromJSON (TaggedM cfg2)) => FromJSON (TaggedM (Record * cfg1 cfg2))

instance FromJSON Record

Monoid (TaggedM a) => Monoid (TaggedM (Option * a))

Monoid (TaggedM (List * a))

Lists are initialized empty by default. Append overwrites left values with right values. (If we tried to append list elements recursively, there would be awkward questions about matching list lengths.)

Monoid (TaggedM (Label * s (Type * a)))

There is no instance Monoid (TaggedM (Type a)), since there is no reasonable mempty. Therefore, we offer a specialized instance for labels that map to Type.

Monoid (TaggedM a) => Monoid (TaggedM (Label * s a))

If one of two configs is Nothing, do the expected thing. If both are Just, append the values.

(Monoid (TaggedM a), Monoid (TaggedM b)) => Monoid (TaggedM (Record * a b))

results and errors

type Result cfg = Either Error (Tagged cfg)

data Error

Constructors

InvalidYaml

Fields

invalidYamlInput :: SBS

invalidYamlMsg :: String

ShellEnvNil

ShellEnvNoParse

Fields

shellEnvNoParseType :: String

shellEnvNoParseValue :: String

shellEnvNoParseMsg :: String

CommandLinePrimitiveParseError String

CommandLinePrimitiveOtherError Error

FreezeIncomplete

Fields

freezeIncompleteAtPath :: [String]

Instances

Eq Error

Ord Error

Show Error

Exception Error

Typeable * Error

the main function

configify :: forall cfg tm. (tm ~ TaggedM cfg, Show tm, Monoid tm, Freeze cfg, FromJSON tm, HasParseShellEnv cfg, HasParseCommandLine cfg, CanonicalizePartial cfg) => [Source] -> Result cfg

configify' :: forall cfg tm. (tm ~ TaggedM cfg, Show tm, Monoid tm, Freeze cfg, FromJSON tm, HasParseShellEnv cfg, HasParseCommandLine cfg, CanonicalizePartial cfg) => tm -> [Source] -> Result cfg

yaml / json

parseConfigFile :: FromJSON (TaggedM cfg) => SBS -> Either Error (TaggedM cfg)

renderConfigFile :: (Freeze cfg, t ~ Tagged cfg, ToJSON (TaggedM cfg)) => t -> SBS

shell env

type Env = [(String, String)]

class HasParseShellEnv cfg where

Methods

parseShellEnv :: Env -> Either Error (TaggedM cfg)

Instances

(Typeable * a, FromJSON (TaggedM (Type * a))) => HasParseShellEnv (Type * a)

HasParseShellEnv a => HasParseShellEnv (Option * a)

HasParseShellEnv a => HasParseShellEnv (List * a)

You can provide a list value via the shell environment by providing a single element. This element will be put into a list implicitly.

(A more general approach that allows for yaml-encoded list values in shell variables is more tricky to design, implement, and use: If you have a list of sub-configs and don't want the entire sub-config to be yaml-encoded, but use a longer shell variable name to go further down to deeper sub-configs, there is a lot of ambiguity. It may be possible to resolve that at run-time, but it's more tricky.)

(KnownSymbol path, HasParseShellEnv a) => HasParseShellEnv (Label * path a)

The paths into the recursive structure of the config file are concatenated to shell variable names with separating '_'. (It is still ok to have '_' in your config path names. This parser chops off complete matching names, whether they contain '_' or not, and only then worries about trailing '_'.)

(HasParseShellEnv a, HasParseShellEnv b) => HasParseShellEnv (Record * a b)

cli

type Args = [String]

class HasParseCommandLine cfg where

Methods

parseCommandLine :: [String] -> Either Error (TaggedM cfg)

Instances

HasParseShellEnv cfg => HasParseCommandLine cfg

primitiveParseCommandLine :: HasParseShellEnv cfg => [String] -> Either Error (TaggedM cfg)

Very basic fist approach: read --(key)(=|s+)(value); construct shell env from keys and names, and use parseShellEnv on the command line. If it doesn't like the syntax used in the command line, it will crash. I hope for this to get much fancier in the future.

parseArgs :: Args -> Either String Env

parseArgsWithEqSign :: String -> Either String Env

parseArgsWithSpace :: String -> String -> Either String Env

parseArgName :: String -> String

accessing config values

(>>.) :: forall cfg ps r. (Sel cfg ps, ToValE cfg ps ~ Done r) => Tagged cfg -> Proxy ps -> r infix 7

Map a Tagged config value and a type-level path to the part of the config value the path points to. Trigger an informative type error if path does not exist.

type family ToVal a p :: Maybe *

Map ConfgCode types to the types of config values.

Equations

ToVal (Record a b) [] = Just (ToConfig (Record a b) Id)

ToVal (Record a b) ps = OrElse (ToVal a ps) (ToVal b ps)

ToVal (Label p a) (p : ps) = ToVal a ps

ToVal (Option a) ps = ToValueMaybe (ToVal a ps)

ToVal a [] = Just (ToConfig a Id)

ToVal a (p : ps) = Nothing

type family OrElse x y :: Maybe k

This is <|> on Maybe lifted to the type level.

Equations

OrElse (Just x) y = Just x

OrElse Nothing y = y

data CMaybe a where

Compile-time Maybe. Type-level Just / Nothing (as produced by ToVal) are embedded in each constructor, resp.. Since Just and Nothing are different types, CNothing and CJust can be distinguished by the type checker.

Constructors

CNothing :: CMaybe Nothing

CJust :: a -> CMaybe (Just a)

orElse :: CMaybe a -> CMaybe b -> CMaybe (OrElse a b)

This is a version of <|> on Maybe for CMaybe.

options

type family ToValueMaybe a :: Maybe *

Equations

ToValueMaybe (Just x) = Just (Maybe x)

ToValueMaybe Nothing = Nothing

toValueMaybe :: CMaybe a -> CMaybe (ToValueMaybe a)

class NothingValue a where

Methods

nothingValue :: Proxy a -> CMaybe (ToValueMaybe a)

Instances

NothingValue (Nothing *)

NothingValue (Just * x)

cfg traversal

class Sel cfg ps where

Methods

sel :: Tagged cfg -> Proxy ps -> CMaybe (ToVal cfg ps)

Instances

Sel' cfg ps => Sel cfg ps

((~) (ConfigCode *) cfg (Option * cfg'), NothingValue (ToVal cfg' ps), Sel cfg' ps) => Sel (Option * cfg') ps

Sel (Record * cfg' cfg'') ([] Symbol)

((~) (ConfigCode *) cfg (Label * p cfg'), (~) * t (ToConfig cfg Id), Sel cfg' ps, KnownSymbol p) => Sel (Label * p cfg') ((:) Symbol p ps)

((~) (ConfigCode *) cfg (Record * cfg' cfg''), Sel cfg' ((:) Symbol p ps), Sel cfg'' ((:) Symbol p ps)) => Sel (Record * cfg' cfg'') ((:) Symbol p ps)

class Sel' cfg ps where

Helper class for disambiguating overlaps. The trick is that the Sel instance based on the Sel' constraint is more general than all other instances, so OverlappingInstances will ensure it is matched last. This way, no instance of Sel' can wrongly overlap with any instance of Sel.

Methods

sel' :: Tagged cfg -> Proxy ps -> CMaybe (ToVal cfg ps)

Instances

((~) * t (ToConfig cfg Id), (~) (Maybe *) (ToVal cfg ([] Symbol)) (Just * t)) => Sel' cfg ([] Symbol)

(~) (Maybe *) (ToVal cfg ((:) Symbol p ps)) (Nothing *) => Sel' cfg ((:) Symbol p ps)

static lookup error handling

type ToValE a p = ToExc (LookupFailed a p) (ToVal a p)

data Exc a b

Constructors

Fail a

Done b

data LookupFailed a p

type family ToExc a x :: Exc k l

Equations

ToExc a Nothing = Fail a

ToExc a (Just x) = Done x

merge configs

merge :: forall cfg tm ti. (tm ~ TaggedM cfg, ti ~ Tagged cfg, Freeze cfg, Monoid tm, CanonicalizePartial cfg) => [tm] -> Either Error ti

freeze :: forall cfg tm ti. (tm ~ TaggedM cfg, ti ~ Tagged cfg, Freeze cfg) => tm -> Either Error ti

thaw :: forall cfg tm ti. (tm ~ TaggedM cfg, ti ~ Tagged cfg, Freeze cfg) => ti -> tm

class Freeze c where

Methods

frz :: Proxy c -> [String] -> ToConfig c Maybe -> Either Error (ToConfig c Id)

thw :: Proxy c -> ToConfig c Id -> ToConfig c Maybe

Instances

Freeze (Type * c)

((~) * (ToConfig (Option * c) Maybe) (MaybeO tm), (~) * (ToConfig (Option * c) Id) (MaybeO ti), (~) * tm (ToConfig c Maybe), (~) * ti (ToConfig c Id), Freeze c) => Freeze (Option * c)

FIXME: if a non-optional part of an optional sub-config is missing, the FreezeIncomplete error is ignored and the entire sub-config is cleared. it would be better to distinguish between the cases `sub-config missing` and `sub-config provided incompletely`, and still raise an error in the latter.

Freeze c => Freeze (List * c)

(KnownSymbol s, Freeze t) => Freeze (Label * s t)

(Freeze a, Freeze b) => Freeze (Record * a b)

class CanonicalizePartial a where

Methods

canonicalizePartial :: TaggedM a -> TaggedM a

emptyPartial :: TaggedM a -> Bool

Instances

CanonicalizePartial (Type * a)

((~) (ConfigCode *) cfg (Option * cfg'), CanonicalizePartial cfg') => CanonicalizePartial (Option * cfg')

((~) (ConfigCode *) cfg (List * cfg'), CanonicalizePartial cfg') => CanonicalizePartial (List * cfg')

((~) (ConfigCode *) cfg (Label * s cfg'), CanonicalizePartial cfg') => CanonicalizePartial (Label * s cfg')

(CanonicalizePartial cfg, CanonicalizePartial cfg') => CanonicalizePartial (Record * cfg cfg')

docs

docs :: (HasToDoc a, HasRenderDoc ConfigFile, HasRenderDoc ShellEnv, HasRenderDoc CommandLine) => Proxy a -> ST

data Doc

Constructors

DocDict [(String, Maybe String, Doc, DocOptional)]

DocList Doc

DocType String

Instances

Eq Doc

Ord Doc

Read Doc

Show Doc

Typeable * Doc

data DocOptional

Constructors

DocMandatory

DocOptional

Instances

Eq DocOptional

Ord DocOptional

Read DocOptional

Show DocOptional

Typeable * DocOptional

concatDoc :: Doc -> Doc -> Doc

class HasToDoc a where

Methods

toDoc :: Proxy a -> Doc

Instances

Typeable * a => HasToDoc (Type * a)

HasToDoc a => HasToDoc (Option * a)

HasToDoc a => HasToDoc (List * a)

(HasToDoc a, KnownSymbol path, KnownSymbol descr) => HasToDoc (Descr * (Label * path a) descr)

(KnownSymbol path, HasToDoc a) => HasToDoc (Label * path a)

(HasToDoc a, HasToDoc b) => HasToDoc (Record * a b)

class HasRenderDoc t where

Methods

renderDoc :: Proxy t -> Doc -> ST

Instances

HasRenderDoc * CommandLine

HasRenderDoc * ShellEnv

HasRenderDoc * ConfigFile