diff --git a/CHANGELOG.markdown b/CHANGELOG.markdown new file mode 100644 --- /dev/null +++ b/CHANGELOG.markdown @@ -0,0 +1,4 @@ +### Version 0.0.0.1 (2016-10-30) + + * Documentation fixes: significant portions of the haddocks failed + to render. diff --git a/Data/Configurator/Parser.hs b/Data/Configurator/Parser.hs --- a/Data/Configurator/Parser.hs +++ b/Data/Configurator/Parser.hs @@ -12,31 +12,37 @@ -- A set of combinators for high-level configuration parsing. module Data.Configurator.Parser - ( ConfigParser - , ConfigParserA - , ConfigParserM - , ConfigError (..) - , ConfigErrorLocation (..) - , ConversionError (..) - , ConversionErrorWhy (..) - , Config - , ConfigTransform - , unsafeBind + ( + -- * High level parsing computations + ConfigParser , runParser + , ConfigParserA , runParserA - , runParserM , parserA + , unsafeBind + , ConfigParserM + , runParserM , parserM + , recover + -- * Looking up values by name + , key + , keyWith + -- * Discovering names + , subgroups , subassocs , subassocs' - , subgroups + -- * Modifying the configuration context + , Config + , ConfigTransform , localConfig , union , subconfig , superconfig - , recover - , key - , keyWith + -- * Error / warning messages + , ConfigError (..) + , ConfigErrorLocation (..) + , ConversionError (..) + , ConversionErrorWhy (..) ) where import Prelude hiding (null) @@ -64,9 +70,10 @@ runParser m conf = let (ma, errs) = unConfigParser_ m conf in (ma, toErrors errs) -{- | Returns all the value bindings from the current configuration context --- that is contained within the given subgroup, in lexicographic order. --- For example, given the following context: +{- | +Returns all the value bindings from the current configuration context that is +contained within the given subgroup, in lexicographic order. For example, +given the following context: @ x = 1 @@ -82,21 +89,21 @@ Then the following arguments to 'subassocs' would return the following lists: @ -subassocs "" ==> [("foo",String \"Hello\"),("x",Number 1)] -subassocs "foo" ==> [("foo.x",Number 2)] -subassocs "foo.bar" ==> [("foo.bar.x",Bool True)] +subassocs \"\" ==> [(\"foo\",String \"Hello\"),(\"x\",Number 1)] +subassocs \"foo\" ==> [(\"foo.x\",Number 2)] +subassocs \"foo.bar\" ==> [(\"foo.bar.x\",Bool True)] @ -All other arguments to subassocs would return [] in the given context. +All other arguments to @subassocs@ would return @[]@ in the given context. -} - subassocs :: ConfigParser m => Name -> m [(Name, Value)] subassocs t = configParser_ (\c -> (Just (C.subassocs t c), mempty)) -{- | Returns all the value bindings from the current configuration context --- that is contained within the given subgroup and all of it's subgroups --- in lexicographic order. For example, given the following context: +{- | +Returns all the value bindings from the current configuration context that is +contained within the given subgroup and all of it's subgroups in lexicographic +order. For example, given the following context: @ x = 1 @@ -112,15 +119,15 @@ Then the following arguments to 'subassocs\'' would return the following lists: @ -subassocs\' "" ==> [ ("foo" , String \"Hello\") - , ("foo.bar.y" , Bool True ) - , ("foo.x" , Number 2 ) - , ("x" , Number 1 ) +subassocs\' \"\" ==> [ (\"foo\" , String \"Hello\") + , (\"foo.bar.y\" , Bool True ) + , (\"foo.x\" , Number 2 ) + , (\"x\" , Number 1 ) ] -subassocs\' "foo" ==> [ ("foo.bar.y" , Bool True ) - , ("foo.x" , Number 2 ) +subassocs\' \"foo\" ==> [ (\"foo.bar.y\" , Bool True ) + , (\"foo.x\" , Number 2 ) ] -subassocs\' "foo.bar" ==> [ ("foo.bar.y" , Bool True ) +subassocs\' \"foo.bar\" ==> [ (\"foo.bar.y\" , Bool True ) ] @ @@ -130,9 +137,10 @@ subassocs' :: ConfigParser m => Name -> m [(Name, Value)] subassocs' t = configParser_ (\c -> (Just (C.subassocs' t c), mempty)) -{- | Returns all the non-empty value groupings that is directly under --- the argument grouping in the current configuration context. --- For example, given the following context: +{- | +Returns all the non-empty value groupings that is directly under the argument +grouping in the current configuration context. For example, given the +following context: @ foo { } @@ -156,10 +164,10 @@ Then the following arguments to 'subgroups' would return the following lists: @ -subgroups "" ==> [ "bar", "default" ] -subgroups "bar" ==> [ "bar.a", "bar.b" ] -subgroups "bar.b" ==> [ "bar.b.c" ] -subgroups "default" ==> [ "default.a" ] +subgroups \"\" ==> [ \"bar\", \"default\" ] +subgroups \"bar\" ==> [ \"bar.a\", \"bar.b\" ] +subgroups \"bar.b\" ==> [ \"bar.b.c\" ] +subgroups \"default\" ==> [ \"default.a\" ] @ All other arguments to @subgroups@ would return @[]@ in the given context. @@ -210,14 +218,14 @@ recover m = configParser_ $ \r -> let (ma, errs) = unConfigParser_ m r in (Just ma, errs) --- Look up a given value in the current configuration context, and convert --- the value using the 'fromMaybeValue' method. +-- | Look up a given value in the current configuration context, and convert +-- the value using the 'fromMaybeValue' method. key :: (ConfigParser m, FromMaybeValue a) => Name -> m a key name = keyWith name fromMaybeValue --- Look up a given value in the current configuration context, and convert --- the value using the 'MaybeParser' argument. +-- | Look up a given value in the current configuration context, and convert +-- the value using the 'MaybeParser' argument. keyWith :: (ConfigParser m) => Name -> MaybeParser a -> m a keyWith name parser = diff --git a/Data/Configurator/Parser/Implementation.hs b/Data/Configurator/Parser/Implementation.hs --- a/Data/Configurator/Parser/Implementation.hs +++ b/Data/Configurator/Parser/Implementation.hs @@ -25,11 +25,8 @@ type ConfigErrors = Maybe (DList ConfigError) --- | A @'ConfigParserM' a@ computation produces a value of type @'Maybe' a@ --- from a given 'Config', in addition to a list of diagnostic messages --- which may be interpreted as warnings or errors as deemed appropriate. --- If the value returned by a computation is 'Nothing', then no subsequent --- actions (e.g. via @\<*\>@ or @>>=@) will be performed. +-- | If the value returned by a computation is 'Nothing', then no subsequent +-- actions (e.g. via '<*>' or '>>=') will be performed. newtype ConfigParserM a = ConfigParserM { unConfigParserM :: RMW Config ConfigErrors a } @@ -50,9 +47,7 @@ Just a -> let (mb, w') = unConfigParserM (k a) r in (mb, w <> w') --- | A @'ConfigParserM' a@ computation produces a value of type @'Maybe' a@ --- from a given 'Config', in addition to a list of diagnostic messages. --- After executing a subcomputation that returns a 'Nothing' value, +-- | After executing a subcomputation that returns a 'Nothing' value, -- computations of type 'ConfigParserA' will continue to run in order to -- produce more error messages. For this reason, 'ConfigParserA' does -- not have a proper 'Monad' instance. (But see 'unsafeBind') @@ -74,7 +69,7 @@ -- | The purpose of this function is to make it convenient to use do-notation -- with 'ConfigParserA', either by defining a Monad instance or locally --- rebinding '(>>=)'. Be warned that this is an abuse, and incorrect +-- rebinding '>>='. Be warned that this is an abuse, and incorrect -- usage can result in exceptions. A safe way to use this function -- would be to treat is as applicative-do notation. A safer alternative -- would be to use the @ApplicativeDo@ language extension available in @@ -118,9 +113,13 @@ --} --- | The 'ConfigParser' type class abstracts over 'ConfigParserM' and --- 'ConfigParserA'. This is intended to be a closed typeclass, without --- any additional instances. +-- | A 'ConfigParser' computation produces a value of type @'Maybe' a@ +-- from a given 'Config', in addition to a list of diagnostic messages, +-- which may be interpreted as warnings or errors as deemed appropriate. +-- The type class abstracts over 'ConfigParserM' and 'ConfigParserA' +-- variants, which are isomorphic but have different 'Applicative' and +-- 'Monad' instances. This is intended to be a closed typeclass, without +-- any additional instances. class Applicative m => ConfigParser m where configParser_ :: RMW Config ConfigErrors a -> m a @@ -163,12 +162,12 @@ go (Subconfig pre a) = Subconfig pre (go a) go Empty = Empty --- Conceptually, @'union' f g = \config -> union\' (f config) (g config)@, +-- | Conceptually, @'union' f g = \\config -> union\' (f config) (g config)@, -- where @union\'@ is the left-biased union of two 'Config's. union :: ConfigTransform -> ConfigTransform -> ConfigTransform union (ConfigTransform x) (ConfigTransform y) = ConfigTransform (Union x y) --- @'subconfig' group@ restricts the configuration to those values that +-- | @'subconfig' group@ restricts the configuration to those values that -- are contained within @group@ (either directly, or contained within a -- descendant value grouping), and removes the @group@ prefix from all -- of the keys in the map. It's analogous to the @cd@ (change directory) @@ -178,7 +177,7 @@ subconfig :: Text -> ConfigTransform -> ConfigTransform subconfig k (ConfigTransform x) = ConfigTransform (Subconfig k x) --- @'superconfig' group@ adds the @group@ prefix to all keys in the map. +-- | @'superconfig' group@ adds the @group@ prefix to all keys in the map. -- It is vaguely analogous to the @mount@ command on unix operating systems. superconfig :: Text -> ConfigTransform -> ConfigTransform superconfig k (ConfigTransform x) = ConfigTransform (Superconfig k x) diff --git a/Data/Configurator/Parser/Internal.hs b/Data/Configurator/Parser/Internal.hs --- a/Data/Configurator/Parser/Internal.hs +++ b/Data/Configurator/Parser/Internal.hs @@ -7,6 +7,7 @@ module Data.Configurator.Parser.Internal ( RMW + , ConfigErrors , ConfigParser (..) , ConfigParserM (..) , ConfigParserA (..) diff --git a/README.markdown b/README.markdown --- a/README.markdown +++ b/README.markdown @@ -94,7 +94,7 @@ Another advantage of the `ConfigParser` interface is that it makes it easier and more convenient to validate a (sub-)configuration as an -entirety, and thus also make more intelligent decisions about to do +entirety, and thus also make more intelligent decisions about what to do in cases of misconfigurations. For example, one might want to continue running on the last known good configuration, and raise a big red flag in a monitoring solution. The goal is to provide mechanism, diff --git a/configurator-ng.cabal b/configurator-ng.cabal --- a/configurator-ng.cabal +++ b/configurator-ng.cabal @@ -1,5 +1,5 @@ name: configurator-ng -version: 0.0.0.0 +version: 0.0.0.1 license: BSD3 license-file: LICENSE category: Configuration, Data @@ -37,6 +37,7 @@ . extra-source-files: + CHANGELOG.markdown README.markdown data-files: tests/resources/*.cfg