Add optional imports

1 files changed, 68 insertions, 4 deletions

diff --git a/Data/ConfigManager.hs b/Data/ConfigManager.hs
index eb15ddf..bd62f40 100644
--- a/Data/ConfigManager.hs
+++ b/Data/ConfigManager.hs
@@ -1,5 +1,29 @@
+-- |
+-- Module:      Data.ConfigManager
+-- License:     GPL-3
+-- Maintainer:  Joris Guyonvarch <joris@guyonvarch.me>
+-- Stability:   experimental
+--
+-- A configuration management library.
+
 module Data.ConfigManager
-  ( readConfig
+  (
+  -- * Configuration file format
+  -- $format
+
+  -- ** Binding a name to a value
+  -- $bindings
+
+  -- ** Import other files
+  -- $import
+
+  -- ** Comments
+  -- $comments
+
+  -- * Configuration loading
+  readConfig
+
+  -- * Lookup functions
   , lookup
   , lookupDefault
   ) where
@@ -12,15 +36,55 @@ import Data.Text (Text)
 import qualified Data.Text as T
 import qualified Data.HashMap.Strict as M
 
-import Data.ConfigManager.Config
 import qualified Data.ConfigManager.Reader as R
-import Data.ConfigManager.Expr
+import Data.ConfigManager.Types
+
+-- | Load a 'Config' from a given 'FilePath'
 
 readConfig :: FilePath -> IO (Either Text Config)
-readConfig = R.readConfig
+readConfig = R.readConfig Required
+
+-- | Lookup for the value associated to a name
 
 lookup :: Read a => Name -> Config -> Maybe a
 lookup name config = join . fmap (readMaybe . T.unpack) $ M.lookup name (hashMap config)
 
+-- | Lookup for the value associated to a name and return the default value if
+-- no binding exists with the given name
+
 lookupDefault :: Value -> Name -> Config -> Value
 lookupDefault defaultValue name config = M.lookupDefault defaultValue name (hashMap config)
+
+-- $format
+--
+-- A configuration file consists of a series of:
+--
+-- * bindings,
+-- * imports,
+-- * and comments.
+
+-- $bindings
+--
+-- A binding associates a name to a value.
+--
+-- > number = 1
+-- > my-string = "Hello"
+-- > a_double = 4.0
+-- > thatIsABoolean = True
+-- > a_double = 5.0
+--
+-- If two or more bindings have the same name, only the last one is kept.
+
+-- $import
+--
+-- An import is either required or optional:
+--
+-- > import "database.conf"
+-- > importMaybe "local.conf"
+
+-- $comment
+--
+-- A comment begins with '#' and continues to the end of the line.
+--
+-- > # Comment
+-- > x = 8 # Another comment