-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Runtime-editable program settings.
--   
--   This library aims to be a tool for constructing a settings management
--   UI on top of the relevant part of your program state. The settings
--   tree structure definition is separate from the actual setting values,
--   so your program logic code doesn't need to be changed. It can access
--   the settings as regular Haskell values.
--   
--   The settings are presented to the user as a tree hierarchy. The idea
--   has some similarity to <tt>git config</tt> and <a>Weechat</a>'s
--   settings system, but isn't identical.
--   
--   To get started, see the tutorial in the <a>Data.Settings</a> module.
@package settings
@version 0.2.2.0

module Data.Settings.Types

-- | A settings option. The option value itself is held as usual in regular
--   application state, not here. What is held here is <i>functions</i>
--   applied to that state to get or set the value.
data Option m
Option :: m String -> (String -> m (Maybe SettingsError)) -> m () -> Option m
[optGet] :: Option m -> m String
[optSet] :: Option m -> String -> m (Maybe SettingsError)
[optReset] :: Option m -> m ()
data Section m
Section :: HashMap String (Option m) -> HashMap String (Section m) -> Section m
[secOpts] :: Section m -> HashMap String (Option m)
[secSubs] :: Section m -> HashMap String (Section m)
type OptName = String
type SecName = String
type OptPath = String
type OptRoute = [String]
data SettingsError
InvalidPath :: OptPath -> SettingsError
NoSuchOption :: OptRoute -> SettingsError
NoSuchSection :: OptRoute -> SettingsError
NoSuchNode :: OptRoute -> SettingsError
InvalidValueForType :: String -> SettingsError
InvalidValue :: String -> SettingsError
class OptionValue v
readOption :: OptionValue v => String -> Maybe v
showOption :: OptionValue v => v -> String
typeName :: OptionValue v => v -> String
class Monad m => MonadSettings m s | m -> s
getSettings :: MonadSettings m s => m s
putSettings :: MonadSettings m s => s -> m ()
modifySettings :: MonadSettings m s => (s -> s) -> m ()
getSTree :: MonadSettings m s => m (Section m)

module Data.Settings.Option
mkOptionV :: (Monad m, OptionValue v) => m v -> (v -> m Bool) -> m () -> Option m
mkOptionS :: (MonadSettings m s, OptionValue v) => (s -> v) -> (v -> s -> Maybe s) -> (s -> (Maybe v, s)) -> (v -> m ()) -> Option m


-- | This module provides functions work working with the <a>Section</a>
--   type, i.e. option trees. The style is similar to the APIs for
--   <tt>HashMap</tt>s and <tt>Map</tt>s. You can use these functions to
--   construct a custom settings tree UI. Before you do that, try the
--   <a>Data.Settings.Interface</a> module, which may already offer what
--   you need.
module Data.Settings.Section

-- | Construct an empty section, no options and no subsections.
empty :: Section m

-- | Construct a section with a single option.
singleton :: SecName -> Option m -> Section m

-- | Return <a>True</a> if this section contains any options, <a>False</a>
--   otherwise.
hasOpts :: Section m -> Bool

-- | Return <a>True</a> if this section contains any subsections,
--   <a>False</a> otherwise.
hasSubs :: Section m -> Bool

-- | Return <a>True</a> if this section is empty (no options, no
--   subsections), <a>False</a> otherwise.
null :: Section m -> Bool

-- | Return <a>True</a> if an option or a subsection is present at the
--   specified path, <a>False</a> otherwise.
member :: OptRoute -> Section m -> (Bool, Bool)

-- | Return <a>True</a> if an option is present at the specified path,
--   <a>False</a> otherwise.
memberOpt :: OptRoute -> Section m -> Bool

-- | Return <a>True</a> if a subsection is present at the specified path,
--   <a>False</a> otherwise.
memberSub :: OptRoute -> Section m -> Bool

-- | Return <a>Just</a> the section or option at the specified path, or
--   <a>Nothing</a> if this section contains no such path.
lookup :: OptRoute -> Section m -> Maybe (Either (Section m) (Option m))

-- | Return <a>Just</a> the option at the specified path, or <a>Nothing</a>
--   if this section doesn't contain an option at this path.
lookupOpt :: [String] -> Section m -> Maybe (Option m)

-- | Return <a>Just</a> the section at the specified path, or
--   <a>Nothing</a> if this section doesn't contain a subsection at this
--   path.
lookupSub :: [String] -> Section m -> Maybe (Section m)

-- | Alias for <a>insertOpt</a>.
insert :: [String] -> Option m -> Section m -> Section m

-- | Add the specified option at the specified path under this section. If
--   the section previously contained an option for this path, the old
--   value is replaced.
insertOpt :: [String] -> Option m -> Section m -> Section m

-- | Add the specified subsection at the specified path under this section.
--   If the section previously contained a subsection for this path, the
--   old value is replaced.
insertSub :: [String] -> Section m -> Section m -> Section m

-- | Remove the option at the specified path, if present. If there is a
--   section under this path, it won't be removed.
deleteOpt :: [String] -> Section m -> Section m

-- | Remove the section at the specified path, if present. If there is an
--   option under this path, it won't be removed.
deleteSub :: [String] -> Section m -> Section m

-- | Remove the option or section at the specified path, if present.
delete :: [String] -> Section m -> Section m

module Data.Settings.Route

-- | Split a path string into its components, if it's a valid path
--   syntactically.
parseRoute :: OptPath -> Maybe OptRoute

-- | Like <a>parseRoute</a>, but allows to choose the escape character
--   (e.g. <tt>'\'</tt>) and the path separator character (e.g.
--   <tt><a>.</a></tt>).
parseRoute' :: Char -> Char -> OptPath -> Maybe OptRoute

-- | Create a string representation of a path, with the parts separated by
--   periods, and literal periods escaped using backslashes.
showRoute :: OptRoute -> OptPath

-- | Like <a>showRoute</a>, but allows to choose the escape character (e.g.
--   <tt><tt>\\</tt></tt>) and the path separator character (e.g.
--   <tt><a>.</a></tt>).
showRoute' :: Char -> Char -> OptRoute -> OptPath

module Data.Settings.Interface

-- | TODO
queryR :: MonadSettings m s => OptRoute -> m (Either SettingsError (Either ([SecName], [OptName]) String))

-- | TODO
querySectionR :: MonadSettings m s => OptRoute -> m (Either SettingsError ([SecName], [OptName]))

-- | TODO
queryOptionR :: MonadSettings m s => OptRoute -> m (Either SettingsError String)

-- | TODO
updateOptionR :: MonadSettings m s => OptRoute -> String -> m (Maybe SettingsError)

-- | TODO
resetOptionR :: MonadSettings m s => OptRoute -> m (Maybe SettingsError)

-- | TODO
query :: MonadSettings m s => OptPath -> m (Either SettingsError (Either ([SecName], [OptName]) String))

-- | TODO
querySection :: MonadSettings m s => OptPath -> m (Either SettingsError ([SecName], [OptName]))

-- | TODO
queryOption :: MonadSettings m s => OptPath -> m (Either SettingsError String)

-- | TODO
updateOption :: MonadSettings m s => OptPath -> String -> m (Maybe SettingsError)

-- | TODO
resetOption :: MonadSettings m s => OptPath -> m (Maybe SettingsError)


-- | This top-level module contains just a tutorial, which you can read
--   below. It will help you figure out which of the sub-modules you need,
--   and how to use them.
--   
--   <h1>Tutorial</h1>
--   
--   <h2>Concepts</h2>
--   
--   For a real usage example, see the <i>funbot</i> package.
--   
--   This library works with 2 components of your application state:
--   
--   <ol>
--   <li>Application settings value, of any type you like. Usually this is
--   a record of a type you define specifically for your application. It
--   can be a value just for settings, or, if modifiable settings are
--   stored in various parts of your state, it can be the state value
--   itself.</li>
--   <li>A settings tree, of type <tt>Section</tt> (defined in
--   <a>Data.Settings.Types</a>). This is a user interface component for
--   accessing the settings values as a tree with labeled nodes. If your
--   settings tree never changes, you can use a Haskell value directly for
--   it. It if changes, add it to your application state so that it can be
--   modified as needed during run time.</li>
--   </ol>
--   
--   The idea is that you freely use whatever you like for the settings
--   values, and the settings tree is a UI component added on top without
--   interfering with your program logic code. Persistence using simple
--   periodic exports to JSON is available in the <tt>json-state</tt>
--   package, but you can use any other solution as needed, e.g. the
--   acid-state package.
--   
--   <h2>Settings Tree Basics</h2>
--   
--   In order to understand the layers of the API, we'll examine it
--   bottom-up. We'll start with the generic flexible parts and move
--   towards the more specific but simpler and more convenient ones. You'll
--   likely need a bit of both sides, so it's probably best to taste both.
--   
--   Suppose we're writing a terminal based text editor, like <i>nano</i>
--   or <i>vim</i>. The UI allows the user to enter commands like <tt>get
--   x.y.z</tt> or <tt>set x.y.z val</tt> which manipulate the settings.
--   
--   Let's define a type for settings. It may look like this:
--   
--   <pre>
--   data Settings = Settings
--       { setsTabWidth    :: Int
--       , setsFont        :: String
--       , setsTextSize    :: Int
--       , setsColorScheme :: String
--       }
--   </pre>
--   
--   For simplicity, suppose the settings tree won't be changing, so all we
--   need in our application state is the settings. Let's use this:
--   
--   <pre>
--   data AppState = AppState
--       { appOpenFiles :: [String]
--       , appUI        :: Widget
--       , appSettings  :: Settings
--       }
--   </pre>
--   
--   If we wanted to allow the settings tree structure to change, we'd have
--   a field for it too in the app state record.
--   
--   This will be our monad:
--   
--   <pre>
--   type App = StateT AppState IO
--   </pre>
--   
--   Now let's define a settings tree. A settings tree is the top-level
--   <i>section</i> of it. Each such section consists of two things: A set
--   of settings options, and a set of subsections. An empty tree looks
--   like this:
--   
--   <pre>
--   import Data.Settings.Section (empty)
--   
--   stree :: Section App
--   stree = empty
--   </pre>
--   
--   Which is equivalent to:
--   
--   <pre>
--   import qualified Data.HashMap.Lazy as M
--   
--   stree :: Section App
--   stree = Section
--       { secOpts = M.empty
--       , secSubs = M.empty
--       }
--   </pre>
--   
--   The <tt>secOpts</tt> field is a map between option names and
--   <tt>Option</tt> values. The <tt>secSubs</tt> field is a map between
--   subsection names and <tt>Section</tt> values. We can then refer to a
--   specific tree node using period-separated syntax. For example, if we
--   have a tree with a single top-level option <tt>"a"</tt>, we can refer
--   to it in the UI simply a <tt>"a"</tt>. If we have a tree with a
--   subsection <tt>"s"</tt> and under it an option <tt>"a"</tt>, we refer
--   to that section as <tt>"a"</tt> and to the option under it as
--   <tt>"s.a"</tt>. And so on, we can have arbitrarily deep nesting of
--   sections and options, e.g. <tt>"s.t.u.v.w.x.a"</tt>.
--   
--   It is possible for a section or option name to contain a period. In
--   that case, the period must be escaped using a backslash before it. To
--   specify a literal backslash, escape it too, i.e. use two backslashes.
--   It is also possible different separator characters instead of a
--   period.
--   
--   The low-level flexible way to define a settings tree is by using
--   <tt>Option</tt> value contructors directly. Let's define a simple flat
--   tree with 4 options and no subsections.
--   
--   The <tt>Option</tt> fields are monadic actions in our application
--   monad, <tt>App</tt>.
--   
--   <pre>
--   import Control.Monad.Trans.State
--   import qualified Data.HashMap.Lazy as M
--   import Data.Settings.Types
--   import Text.Read (readMaybe)
--   
--   -- Convenience wrappers to make the code shorter
--   -- Perhaps a good chance to use lens?
--   getS = gets appSettings
--   putS sets = modify $ \ app -&gt; app { appSettings = sets }
--   modifyS f = modify $ \ app -&gt; app { appSettings = f $ appSettings app }
--   
--   stree :: Section App
--   stree = Section
--       { secOpts = M.fromList
--           [ ( "tab-width"
--             , Option
--                 { optGet   = liftM (show . setsTabWidth) getS
--                 , optSet   = \ val -&gt;
--                       case readMaybe val of
--                           Just n -&gt; do
--                               modifyS $ \ s -&gt; s { setsTabWidth = n }
--                               return Nothing
--                           Nothing -&gt; return $ Just $ InvalidValueForType val
--                 , optReset = modifyS $ \ s -&gt; s { setsTabWidth = 4 }
--                 }
--             )
--           , ( "font"
--             , Option {- ... similar fashion ... -}
--             )
--           , ( "text-size"
--             , Option {- ... similar fashion ... -}
--             )
--           , ( "color-scheme"
--             , Option {- ... similar fashion ... -}
--             )
--           ]
--       , secSubs = M.empty
--       }
--   </pre>
--   
--   <h2>Building a Settings UI</h2>
--   
--   We'll see higher level alternatives later. Let's see how to contruct
--   the settings UI now. The <a>Data.Settings.Iterface</a> provides a set
--   of high-level functions you can use on your UI code. You just need to
--   wrap them with UI actions like error message (e.g. invalid value) and
--   feedback for successful operations.
--   
--   Before we can use those functions, we need to make our application
--   monad an instance of the <tt>MonadSettings</tt> (multi-parameter)
--   typeclass:
--   
--   <pre>
--   instance MonadSettings App Settings where
--       getSettings = getS
--       putSettings = putS
--       modifySettings = modifyS
--       getSTree = return stree
--   </pre>
--   
--   Now, suppose the user enters the command <tt>get x.y.z</tt> in our
--   text editor's command input line. This should return a friendly
--   result. If <tt>x.y.z</tt> is a valid path in our settings tree leading
--   to an option value, display that value. If it's a section, display a
--   list of the options and subsections it contains. If it's neither, i.e.
--   the path is invalid, report the error.
--   
--   Such a UI can easily be constructed using functions in
--   <a>Data.Settings.Interface</a>, e.g. see the <a>query</a> function.
--   Using the values it returns, you can construct UI strings to display
--   on the screen.
--   
--   For example, in our case we'd want <tt>get</tt> to display the
--   top-level tree contents, <tt>get tab-width</tt> to display a number (4
--   by default) and <tt>get foo</tt> to display an error <i>no such option
--   or section</i>.
--   
--   <h2>Settings Tree Definition Tools</h2>
--   
--   Let's go back to defining the settings tree. Some things we could
--   improve:
--   
--   <ul>
--   <li>We defined <tt>getS</tt> and related small functions, and used
--   them when we defined the <tt>MonadSettings</tt> instance. Instead, we
--   can first define the instance and then just use its methods in our
--   settings free definition if needed.</li>
--   <li>The usage of <tt>readMaybe</tt> and <tt>show</tt> allowed us to
--   easily and quickly wrap the tab width, an <a>Int</a> value, by the
--   string-based interface. But with larger settings records and more
--   value types, we'd want something more robust and appropriate for UI.
--   For example, if we did this for a <a>Bool</a> field, the user would
--   have to type in <tt>set x.y.z True</tt> while <tt>set x.y.z yes</tt>
--   wouldn't work. Why tie the UI to the way booleans are written in
--   Haskell? We can have <i>true, TRUE, True, yes, Yes, 1</i> etc. all
--   mean <a>True</a>. Be flexible and user friendly.</li>
--   <li>Once we write the <tt>MonadSettings</tt> instance, instead of
--   using its methods directly (like we used <tt>getS</tt> etc.) we can
--   have wrappers do it for us, so that we only need to write functions
--   operating over the <tt>Settings</tt> type directly, making our code
--   simple and readable and easy to tweak.</li>
--   </ul>
--   
--   Let's start with the second point, wrapping typed settings values with
--   UI, e.g. like the example given for booleans above. The
--   <a>Data.Settings.Option</a> module provides the <tt>mkOptionV</tt>
--   function. This function wraps the type details for us, if we supply
--   instances of the <tt>OptionValue</tt> class. Let's define an instance
--   for <a>Int</a>, which is the type of 2 out of the 4 fields in our
--   <tt>Settings</tt> type. Generally, you'd want to define instances for
--   all the relevant field types in your settings type, e.g. perhaps also
--   <a>Bool</a> and <a>Float</a> and custom enum tyes and so on, depending
--   on your requirements and UI designs.
--   
--   <pre>
--   instace OptionValue Int where
--       readOption = readMaybe
--       showOption = show
--       typeName = const "Integer"
--   </pre>
--   
--   And here's an instance for <a>Bool</a>:
--   
--   <pre>
--   instace OptionValue Bool where
--       readOption s
--           | sl `elem` ["true, "yes", "on", "1"]   = Just True
--           | sl `elem` ["false", "no", "off", "0"] = Just False
--           | otherwise                             = Nothing
--           where sl = map toLower s
--       showOption = show
--       typeName = const "Boolean"
--   </pre>
--   
--   Now, using <tt>mkOptionV</tt>, and this time also using the
--   <tt>MonadSettings</tt> functions, we can redefine the tab width option
--   like this:
--   
--   <pre>
--   mkOptionV
--       (liftM setsTabWidth getSettings)
--       (\ n -&gt; do
--           modifySettings $ \ s -&gt; s { setsTabWidth = n }
--           return True
--       )
--       (modifySettings $ \ s -&gt; s { setsTabWidth = 4 })
--   </pre>
--   
--   Now let's improve further. This will be the highest level of the API.
--   Given a <tt>MonadSettings</tt> instance, the repetitive parts of the
--   code can be cleaned further, by using the <tt>mkOptionS</tt> function.
--   
--   <pre>
--   mkOptionS
--       setsTabWidth
--       (\ n s -&gt; Just s { setsTabWidth = n })
--       (\ s -&gt; (Just 4, s { setsTabWidth = 4 }))
--       (const $ return ())
--   </pre>
--   
--   Perhaps a bit cleaner form removing duplication is this:
--   
--   <pre>
--   mkOptionS
--       setsTabWidth
--       (\ n s -&gt; Just $ set n s)
--       (\ s -&gt; (Just defval, set defval s))
--       (const $ return ())
--       where
--       set n s = s { setsTabWidth = n }
--       defval = 4
--   </pre>
--   
--   The last argument is a callback action to be run when a successful set
--   or reset of the value occurs.
--   
--   <h2>Settings Tree Dynamic Modification</h2>
--   
--   Modification simply requires holding the tree as application state,
--   and changing as needed. Removing sections, adding options and so on.
--   There is an API in <a>Data.Settings.Section</a> for working with the
--   settings tree, and since unordered maps are being used, you may also
--   find <a>Data.HashMap.Lazy</a> useful (from unordered-containers
--   package).
module Data.Settings