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


-- | Dynamic reconfiguration in Haskell
--   
--   Dyre implements dynamic reconfiguration facilities after the style of
--   Xmonad. Dyre aims to be as simple as possible without sacrificing
--   features, and places an emphasis on simplicity of integration with an
--   application. A full introduction with a complete example project can
--   be found in the documentation for <a>Config.Dyre</a>
@package dyre
@version 0.7

module Config.Dyre.Options

-- | Store Dyre's command-line options to the IO-Store <a>dyre</a>, and
--   then execute the provided IO action with all Dyre's options removed
--   from the command-line arguments.
withDyreOptions :: IO a -> IO a

-- | Return the set of options which will be passed to another instance of
--   Dyre. Preserves the master binary, state file, and debug mode flags,
--   but doesn't pass along the forced-recompile flag. Can be passed a set
--   of other arguments to use, or it defaults to using the current
--   arguments when passed <a>Nothing</a>.
customOptions :: Maybe [String] -> IO [String]

-- | Get the value of the '--force-reconf' flag, which is used to force a
--   recompile of the custom configuration.
getReconf :: IO Bool

-- | Get the value of the '--dyre-debug' flag, which is used to debug a
--   program without installation. Specifically, it forces the application
--   to use './cache/' as the cache directory, and <tt>./</tt> as the
--   configuration directory.
getDebug :: IO Bool

-- | Get the path to the master binary. This is set to the path of the
--   *current* binary unless the '--dyre-master-binary=' flag is set.
--   Obviously, we pass the '--dyre-master-binary=' flag to the custom
--   configured application from the master binary.
getMasterBinary :: IO (Maybe String)

-- | Get the path to a persistent state file. This is set only when the
--   '--dyre-state-persist=' flag is passed to the program. It is used
--   internally by <tt>Config.Dyre.Relaunch</tt> to save and restore state
--   when relaunching the program.
getStatePersist :: IO (Maybe String)


-- | Compatibility code for things that need to be done differently on
--   different systems.
module Config.Dyre.Compat

-- | Called whenever execution needs to be transferred over to a different
--   binary.
customExec :: FilePath -> Maybe [String] -> IO ()

-- | What it says on the tin. Gets the current PID as a string. Used to
--   determine the name for the state file during restarts.
getPIDString :: IO String

module Config.Dyre.Relaunch

-- | Just relaunch the master binary. We don't have any important state to
--   worry about. (Or, like when 'relaunchWith&lt;X&gt;State' calls it,
--   we're managing state on our own). It takes an argument which can
--   optionally specify a new set of arguments. If it is given a value of
--   <a>Nothing</a>, the current value of <tt>getArgs</tt> will be used.
relaunchMaster :: Maybe [String] -> IO ()

-- | Relaunch the master binary, but first preserve the program state so
--   that we can use the <a>restoreTextState</a> functions to get it back
--   again later.
relaunchWithTextState :: (Show a) => a -> Maybe [String] -> IO ()

-- | Serialize the state for later restoration with
--   <a>restoreBinaryState</a>, and then relaunch the master binary.
relaunchWithBinaryState :: (Binary a) => a -> Maybe [String] -> IO ()

-- | Serialize a state as text, for later loading with the
--   <a>restoreTextState</a> function.
saveTextState :: (Show a) => a -> IO ()

-- | Serialize a state as binary data, for later loading with the
--   <a>restoreBinaryState</a> function.
saveBinaryState :: (Binary a) => a -> IO ()

-- | Restore state which has been serialized through the
--   <a>saveTextState</a> function. Takes a default which is returned if
--   the state doesn't exist.
restoreTextState :: (Read a) => a -> IO a

-- | Restore state which has been serialized through the
--   <a>saveBinaryState</a> function. Takes a default which is returned if
--   the state doesn't exist.
restoreBinaryState :: (Binary a) => a -> IO a


-- | Defines the <a>Params</a> datatype which Dyre uses to define all
--   program-specific configuration data. Shouldn't be imported directly,
--   as <tt>Config.Dyre</tt> re-exports it.
module Config.Dyre.Params

-- | This structure is how all kinds of useful data is fed into Dyre. Of
--   course, only the <a>projectName</a>, <a>realMain</a>, and
--   <a>showError</a> fields are really necessary. By using the set of
--   default values provided as <tt>Config.Dyre.defaultParams</tt>, you can
--   get all the benefits of using Dyre to configure your program in only
--   five or six lines of code.
data Params cfgType
Params :: String -> Bool -> Maybe (IO FilePath) -> Maybe (IO FilePath) -> (cfgType -> IO ()) -> (cfgType -> String -> cfgType) -> [String] -> [String] -> (String -> IO ()) -> Params cfgType

-- | The name of the project. This needs to also be the name of the
--   executable, and the name of the configuration file.
projectName :: Params cfgType -> String

-- | Should Dyre look for and attempt to compile custom configurations?
--   Useful for creating program entry points that bypass Dyre's
--   recompilation, for testing purposes.
configCheck :: Params cfgType -> Bool

-- | The directory to look for a configuration file in.
configDir :: Params cfgType -> Maybe (IO FilePath)

-- | The directory to store build files in, including the final generated
--   executable.
cacheDir :: Params cfgType -> Maybe (IO FilePath)

-- | The main function of the program. When Dyre has completed all of its
--   recompilation, it passes the configuration data to this function and
--   gets out of the way.
realMain :: Params cfgType -> cfgType -> IO ()

-- | This function is used to display error messages that occur during
--   recompilation, by allowing the program to modify its initial
--   configuration.
showError :: Params cfgType -> cfgType -> String -> cfgType

-- | Packages that need to be hidden during compilation
hidePackages :: Params cfgType -> [String]

-- | Miscellaneous GHC compilation settings go here
ghcOpts :: Params cfgType -> [String]

-- | A status output function. Will be called with messages when Dyre
--   recompiles or launches anything. A good value is 'hPutStrLn stderr',
--   assuming there is no pressing reason to not put messages on stderr.
statusOut :: Params cfgType -> String -> IO ()

module Config.Dyre.Paths

-- | Return the paths to, respectively, the current binary, the custom
--   binary, the config file, and the cache directory.
getPaths :: Params c -> IO (FilePath, FilePath, FilePath, FilePath)

-- | Check if a file exists. If it exists, return Just the modification
--   time. If it doesn't exist, return Nothing.
maybeModTime :: FilePath -> IO (Maybe ClockTime)


-- | Compiling the custom executable. The majority of the code actually
--   deals with error handling, and not the compilation itself <i>per
--   se</i>.
module Config.Dyre.Compile

-- | Attempts to compile the configuration file. Will return a string
--   containing any compiler output.
customCompile :: Params cfgType -> IO (Maybe String)


-- | Dyre is a library for configuring your Haskell programs. Like Xmonad,
--   programs configured with Dyre will look for a configuration file
--   written in Haskell, which essentially defines a custom program
--   configured exactly as the user wishes it to be. And since the
--   configuration is written in Haskell, the user is free to do anything
--   they might wish in the context of configuring the program.
--   
--   Dyre places emphasis on elegance of operation and ease of integration
--   with existing applications. The <a>wrapMain</a> function is the sole
--   entry point for Dyre. When partially applied with a parameter
--   structure, it wraps around the <a>realMain</a> value from that
--   structure, yielding an almost identical function which has been
--   augmented with dynamic recompilation functionality.
--   
--   The <tt>Config.Dyre.Relaunch</tt> module provides the ability to
--   restart the program (recompiling if applicable), and persist state
--   across restarts, but it has no impact whatsoever on the rest of the
--   library whether it is used or not.
--   
--   A full example of using Dyre's recompilation and relaunching features
--   is as follows:
--   
--   <pre>
--   -- DyreExample.hs --
--   module DyreExample where
--   
--   import qualified Config.Dyre as Dyre
--   
--   import Config.Dyre.Relaunch
--   import System.IO
--   
--   data Config = Config { message :: String, errorMsg :: Maybe String }
--   data State  = State { bufferLines :: [String] } deriving (Read, Show)
--   
--   defaultConfig :: Config
--   defaultConfig = Config "Dyre Example v0.1" Nothing
--   
--   showError :: Config -&gt; String -&gt; Config
--   showError cfg msg = cfg { errorMsg = Just msg }
--   
--   realMain Config{message = message, errorMsg = errorMsg } = do
--       (State buffer) &lt;- restoreTextState $ State []
--       case errorMsg of
--            Nothing -&gt; return ()
--            Just em -&gt; putStrLn $ "Error: " ++ em
--       putStrLn message
--       mapM putStrLn . reverse $ buffer
--       putStr "&gt; " &gt;&gt; hFlush stdout
--       input &lt;- getLine
--       case input of
--            "exit" -&gt; return ()
--            "quit" -&gt; return ()
--            other  -&gt; relaunchWithTextState (State $ other:buffer) Nothing
--   
--   dyreExample = Dyre.wrapMain $ Dyre.defaultParams
--       { Dyre.projectName = "dyreExample"
--       , Dyre.realMain    = realMain
--       , Dyre.showError   = showError
--       }
--   </pre>
--   
--   Notice that all of the program logic is contained in the
--   <tt>DyreExample</tt> module. The main module of the program is
--   absolutely trivial.
--   
--   <pre>
--   -- Main.hs --
--   module Main where
--   import DyreExample
--   main = dyreExample defaultConfig
--   </pre>
--   
--   When reading the above program, bear in mind exactly how much of the
--   code is simply *program logic*. Dyre is designed to intelligently
--   handle recompilation with a bare minimum of program modification.
--   
--   Some mention should be made of Dyre's defaults. The
--   <a>defaultParams</a> structure used in the example defines reasonable
--   default values for several configuration items. In the absence of any
--   other definitions, Dyre will default to outputting status messages to
--   stderr, not hiding any packages during compilation, and passing no
--   special options to GHC.
--   
--   Also, Dyre will expect configuration files to be placed at the path
--   '$XDG_CONFIG_HOME/&lt;app&gt;/&lt;app&gt;.hs', and it will store cache
--   files in the '$XDG_CACHE_HOME/&lt;app&gt;/' directory. The
--   <tt>System.Environment.XDG</tt> module will be used to determine these
--   paths, so refer to it for behaviour on Windows platforms.
module Config.Dyre

-- | <a>wrapMain</a> is how Dyre recieves control of the program. It is
--   expected that it will be partially applied with its parameters to
--   yield a <tt>main</tt> entry point, which will then be called by the
--   <tt>main</tt> function, as well as by any custom configurations.
wrapMain :: Params cfgType -> cfgType -> IO ()

-- | This structure is how all kinds of useful data is fed into Dyre. Of
--   course, only the <a>projectName</a>, <a>realMain</a>, and
--   <a>showError</a> fields are really necessary. By using the set of
--   default values provided as <tt>Config.Dyre.defaultParams</tt>, you can
--   get all the benefits of using Dyre to configure your program in only
--   five or six lines of code.
data Params cfgType
Params :: String -> Bool -> Maybe (IO FilePath) -> Maybe (IO FilePath) -> (cfgType -> IO ()) -> (cfgType -> String -> cfgType) -> [String] -> [String] -> (String -> IO ()) -> Params cfgType

-- | The name of the project. This needs to also be the name of the
--   executable, and the name of the configuration file.
projectName :: Params cfgType -> String

-- | Should Dyre look for and attempt to compile custom configurations?
--   Useful for creating program entry points that bypass Dyre's
--   recompilation, for testing purposes.
configCheck :: Params cfgType -> Bool

-- | The directory to look for a configuration file in.
configDir :: Params cfgType -> Maybe (IO FilePath)

-- | The directory to store build files in, including the final generated
--   executable.
cacheDir :: Params cfgType -> Maybe (IO FilePath)

-- | The main function of the program. When Dyre has completed all of its
--   recompilation, it passes the configuration data to this function and
--   gets out of the way.
realMain :: Params cfgType -> cfgType -> IO ()

-- | This function is used to display error messages that occur during
--   recompilation, by allowing the program to modify its initial
--   configuration.
showError :: Params cfgType -> cfgType -> String -> cfgType

-- | Packages that need to be hidden during compilation
hidePackages :: Params cfgType -> [String]

-- | Miscellaneous GHC compilation settings go here
ghcOpts :: Params cfgType -> [String]

-- | A status output function. Will be called with messages when Dyre
--   recompiles or launches anything. A good value is 'hPutStrLn stderr',
--   assuming there is no pressing reason to not put messages on stderr.
statusOut :: Params cfgType -> String -> IO ()

-- | A set of reasonable defaults for configuring Dyre. If the minimal set
--   of fields are modified, the program will use the XDG-defined locations
--   for configuration and cache files (see
--   <tt>System.Environment.XDG.BaseDir</tt> for details), pass no special
--   options to GHC, and will output status messages to stderr.
--   
--   The fields that will have to be filled are <a>projectName</a>,
--   <a>realMain</a>, and <a>showError</a>
defaultParams :: Params cfgType