-- 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.8.12


-- | Defines the <a>Params</a> datatype which Dyre uses to define all
--   program-specific configuration data. Shouldn't be imported directly,
--   as <a>Dyre</a> 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 <a>defaultParams</a>, 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] -> Bool -> (String -> IO ()) -> RTSOptionHandling -> Bool -> 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]

-- | Should GHC be given the -fforce-recomp flag?
[forceRecomp] :: Params cfgType -> Bool

-- | 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 ()

-- | Whether to append, or replace GHC runtime system options with others.
[rtsOptsHandling] :: Params cfgType -> RTSOptionHandling

-- | Whether to add current directory to include list (set False to prevent
--   name shadowing within project directory.) --
[includeCurrentDirectory] :: Params cfgType -> Bool
data RTSOptionHandling
RTSReplace :: [String] -> RTSOptionHandling
RTSAppend :: [String] -> RTSOptionHandling

module Config.Dyre.Options

-- | Remove all Dyre's options from the given commandline arguments.
removeDyreOptions :: [String] -> [String]

-- | Store Dyre's command-line options to the IO-Store "dyre", and then
--   execute the provided IO action with all Dyre's options removed from
--   the command-line arguments.
withDyreOptions :: Params c -> 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 '--deny-reconf' flag, which disables
--   recompilation. This overrides "--force-reconf", too.
getDenyReconf :: IO Bool

-- | Get the value of the '--force-reconf' flag, which is used to force a
--   recompile of the custom configuration.
getForceReconf :: 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 <a>Relaunch</a> to save and restore state when
--   relaunching the program.
getStatePersist :: IO (Maybe String)

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, 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 UTCTime)


-- | 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 ()

-- | Return the path to the error file.
getErrorPath :: Params cfgType -> IO FilePath

-- | If the error file exists and actually has some contents, return
--   <a>Just</a> the error string. Otherwise return <a>Nothing</a>.
getErrorString :: Params cfgType -> 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


-- | 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 <a>Relaunch</a> 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 most of Dyre's major 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, being essentially just the default configuration
--   for the program:
--   
--   <pre>
--   -- Main.hs --
--   import DyreExample
--   main = dyreExample defaultConfig
--   </pre>
--   
--   The user can then create a custom configuration file, which overrides
--   some or all of the default configuration:
--   
--   <pre>
--   -- ~/.config/dyreExample/dyreExample.hs --
--   import DyreExample
--   main = dyreExample $ defaultConfig { message = "Dyre Example v0.1 (Modified)" }
--   </pre>
--   
--   When reading the above program, notice that the majority of the code
--   is simply *program logic*. Dyre is designed to intelligently handle
--   recompilation with a minimum of programmer work.
--   
--   Some mention should be made of Dyre's defaults. The
--   <a>defaultParams</a> structure used in the example defines reasonable
--   default values for most configuration items. The three elements
--   defined above are the only elements that must be overridden. For
--   documentation of the parameters, consult the <a>Params</a> module.
--   
--   In the absence of any customization, Dyre will search for
--   configuration files in
--   '$XDG_CONFIG_HOME/&lt;appName&gt;/&lt;appName&gt;.hs', and will store
--   cache files in '$XDG_CACHE_HOME/&lt;appName&gt;/' directory. The
--   module <a>XDG</a> is used for this purpose, which also provides
--   analogous behaviour on Windows.
--   
--   The above example can be tested by running Main.hs with
--   <tt>runhaskell</tt>, and will detect custom configurations and
--   recompile correctly even when the library isn't installed, so long as
--   it is in the current directory when run.
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 <a>defaultParams</a>, 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] -> Bool -> (String -> IO ()) -> RTSOptionHandling -> Bool -> 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]

-- | Should GHC be given the -fforce-recomp flag?
[forceRecomp] :: Params cfgType -> Bool

-- | 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 ()

-- | Whether to append, or replace GHC runtime system options with others.
[rtsOptsHandling] :: Params cfgType -> RTSOptionHandling

-- | Whether to add current directory to include list (set False to prevent
--   name shadowing within project directory.) --
[includeCurrentDirectory] :: Params cfgType -> Bool

-- | A set of reasonable defaults for configuring Dyre. The fields that
--   have to be filled are <a>projectName</a>, <a>realMain</a>, and
--   <a>showError</a>.
defaultParams :: Params cfgType
