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


-- | 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>newParams</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 a
Params :: String -> Bool -> Maybe (IO FilePath) -> Maybe (IO FilePath) -> (cfgType -> IO a) -> (cfgType -> String -> cfgType) -> [FilePath] -> [String] -> [String] -> Bool -> (String -> IO ()) -> RTSOptionHandling -> Bool -> Params cfgType a

-- | 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 a -> 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 a -> Bool

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

-- | The directory to store build files in, including the final generated
--   executable.
[cacheDir] :: Params cfgType a -> 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 a -> cfgType -> IO a

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

-- | Optional extra include dirs to use during compilation. To support
--   installation via cabal-install, include the path returned from
--   <tt>Paths_&lt;appName&gt;.getLibDir</tt>.
[includeDirs] :: Params cfgType a -> [FilePath]

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

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

-- | Should GHC be given the -fforce-recomp flag?
[forceRecomp] :: Params cfgType a -> 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 a -> String -> IO ()

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

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

-- | Specify additional or replacement GHC runtime system options
data RTSOptionHandling

-- | replaces RTS options with given list
RTSReplace :: [String] -> RTSOptionHandling

-- | merges given list with RTS options from command line (so that nothing
--   is lost)
RTSAppend :: [String] -> RTSOptionHandling


-- | Handling for the command-line options that can be used to configure
--   Dyre. As of the last count, there are four of them, and more are
--   unlikely to be needed. The only one that a user should ever need to
--   use is the <tt>--force-reconf</tt> option, so the others all begin
--   with <tt>--dyre-<a>option-name</a></tt>.
--   
--   At the start of the program, before anything else occurs, the
--   <a>withDyreOptions</a> function is used to hide Dyre's command-line
--   options. They are loaded into the <tt>IO</tt> monad using the module
--   <a>System.IO.Storage</a>. This keeps them safely out of the way of the
--   user code and our own.
--   
--   Later, when Dyre needs to access the options, it does so through the
--   accessor functions defined here. When it comes time to pass control
--   over to a new binary, it gets an argument list which preserves the
--   important flags with a call to <a>customOptions</a>.
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 r -> 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 <tt>--deny-reconf</tt> flag, which disables
--   recompilation. This overrides "--force-reconf", too.
getDenyReconf :: IO Bool

-- | Get the value of the <tt>--force-reconf</tt> flag, which is used to
--   force a recompile of the custom configuration.
getForceReconf :: IO Bool

-- | Get the value of the <tt>--dyre-debug</tt> flag, which is used to
--   debug a program without installation. Specifically, it forces the
--   application to use <tt>.<i>cache</i></tt> 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
--   <i>current</i> binary unless the <tt>--dyre-master-binary=</tt> flag
--   is set. Obviously, we pass the <tt>--dyre-master-binary=</tt> 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
--   <tt>--dyre-state-persist=</tt> flag is passed to the program. It is
--   used internally by <a>Config.Dyre.Relaunch</a> 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 a

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


-- | File paths of interest to Dyre, and related values.
module Config.Dyre.Paths

-- | Data type to make it harder to confuse which path is which.
data PathsConfig
PathsConfig :: FilePath -> FilePath -> FilePath -> FilePath -> FilePath -> PathsConfig
[runningExecutable] :: PathsConfig -> FilePath
[customExecutable] :: PathsConfig -> FilePath

-- | Where Dyre looks for the custom configuration file.
[configFile] :: PathsConfig -> FilePath

-- | <tt><a>configDir</a>/libs</tt>. This directory gets added to the GHC
--   include path during compilation, so use configurations can be split up
--   into modules. Changes to files under this directory trigger
--   recompilation.
[libsDirectory] :: PathsConfig -> FilePath

-- | Where the custom executable, object and interface files, errors file
--   and other metadata get stored.
[cacheDirectory] :: PathsConfig -> FilePath

-- | Determine a file name for the compiler to write to, based on the
--   <a>customExecutable</a> path.
outputExecutable :: FilePath -> FilePath

-- | Return a <a>PathsConfig</a>, which records the current binary, the
--   custom binary, the config file, and the cache directory.
getPaths :: Params c r -> IO (FilePath, FilePath, FilePath, FilePath, FilePath)
getPathsConfig :: Params cfg a -> IO PathsConfig

-- | 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)
checkFilesModified :: PathsConfig -> IO Bool

-- | Recursively find Haskell files (<tt>.hs</tt>, <tt>.lhs</tt>) at the
--   given location.
findHaskellFiles :: FilePath -> IO [FilePath]


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

-- | Return the path to the error file.
getErrorPath :: Params cfgType a -> 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 a -> 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 <a>Config.Dyre.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.
--   
--   <h1>Writing a program that uses Dyre</h1>
--   
--   The following example program uses most of Dyre's major features:
--   
--   <pre>
--   -- DyreExample.hs --
--   module DyreExample
--     ( Config(..)
--     , defaultConfig
--     , dyreExample
--     )
--   where
--   
--   import qualified <a>Config.Dyre</a> as Dyre
--   import <a>Config.Dyre.Relaunch</a>
--   
--   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;- <a>restoreTextState</a> $ State []
--       case errorMsg of
--            Nothing -&gt; return ()
--            Just em -&gt; putStrLn $ "Error: " ++ em
--       putStrLn message
--       traverse putStrLn . reverse $ buffer
--       putStr "&gt; " *&gt; hFlush stdout
--       input &lt;- getLine
--       case input of
--            "exit" -&gt; return ()
--            "quit" -&gt; return ()
--            other  -&gt; <a>relaunchWithTextState</a> (State $ other:buffer) Nothing
--   
--   dyreExample = Dyre.<a>wrapMain</a> $ Dyre.<a>newParams</a> "dyreExample" realMain showError
--   </pre>
--   
--   All of the program logic is contained in the <tt>DyreExample</tt>
--   module. The module exports the <tt>Config</tt> data type, a
--   <tt>defaultConfig</tt>, and the <tt>dyreExample</tt> function which,
--   when applied to a <tt>Config</tt>, returns an <tt>(IO a)</tt> value to
--   be used as <tt>main</tt>.
--   
--   The <tt>Main</tt> module of the program is trivial. All that is
--   required is to apply <tt>dyreExample</tt> to the default
--   configuration:
--   
--   <pre>
--   -- Main.hs --
--   import DyreExample
--   main = dyreExample defaultConfig
--   </pre>
--   
--   <h1>Custom program configuration</h1>
--   
--   Users can create a custom configuration file that 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 a program that uses Dyre starts, Dyre checks to see if a custom
--   configuration exists. If so, it runs a custom executable. Dyre
--   (re)compiles and caches the custom executable the first time it sees
--   the custom config or whenever the custom config has changed.
--   
--   If a custom configuration grows large, you can extract parts of it
--   into one or more files under <tt>lib/</tt>. For example:
--   
--   <pre>
--   -- ~/.config/dyreExample/dyreExample.hs --
--   import DyreExample
--   import Message
--   main = dyreExample $ defaultConfig { message = Message.msg }
--   </pre>
--   
--   <pre>
--   -- ~/.config/dyreExample/lib/Message.hs --
--   module Message where
--   msg = "Dyre Example v0.1 (Modified)"
--   </pre>
--   
--   <h2>Working with the Cabal store</h2>
--   
--   For a Dyre-enabled program to work when installed via <tt>cabal
--   install</tt>, it needs to add its library directory as an extra
--   include directory for compilation. The library <i>package name</i>
--   <b>must</b> match the Dyre <a>projectName</a> for this to work. For
--   example:
--   
--   <pre>
--   import Paths_dyreExample (getLibDir)
--   
--   dyreExample cfg = do
--     libdir &lt;- getLibDir
--     let params = (Dyre.<a>newParams</a> "dyreExample" realMain showError)
--           { Dyre.<a>includeDirs</a> = [libdir] }
--     Dyre.<a>wrapMain</a> params cfg
--   </pre>
--   
--   See also the Cabal <a>Paths_pkgname feature documentation</a>.
--   
--   <h2>Specifying the compiler</h2>
--   
--   If the compiler that Dyre should use is not available as <tt>ghc</tt>,
--   set the <tt>HC</tt> environment variable when running the main
--   program:
--   
--   <pre>
--   export HC=/opt/ghc/$GHC_VERSION/bin/ghc
--   dyreExample  # Dyre will use $HC for recompilation
--   </pre>
--   
--   <h1>Configuring Dyre</h1>
--   
--   Program authors configure Dyre using the <a>Params</a> type. This type
--   controls Dyre's behaviour, not the main program logic (the example
--   uses the <tt>Config</tt> type for that).
--   
--   Use <a>newParams</a> to construct a <a>Params</a> value. The three
--   arguments are:
--   
--   <ul>
--   <li><i>Application name</i> (a <tt>String</tt>). This affects the
--   names of files and directories that Dyre uses for config, cache and
--   logging.</li>
--   <li>The <i>real main</i> function of the program, which has type
--   <tt>(cfgType -&gt; IO a)</tt>. <tt>cfgType</tt> is the main program
--   config type, and <tt>a</tt> is usually <tt>()</tt>.</li>
--   <li>The <i>show error</i> function, which has type <tt>(cfgType -&gt;
--   String -&gt; cfgType)</tt>. If compiling the custom program fails,
--   Dyre uses this function to set the compiler output in the main
--   program's configuration. The main program can then display the error
--   string to the user, or handle it however the author sees fit.</li>
--   </ul>
--   
--   The <a>Params</a> type has several other fields for modifying Dyre's
--   behaviour. <a>newParams</a> uses reasonable defaults, but behaviours
--   you can change include:
--   
--   <ul>
--   <li>Where to look for custom configuration (<a>configDir</a>). By
--   default Dyre will look for
--   <tt>$XDG_CONFIG_HOME/&lt;appName&gt;/&lt;appName&gt;.hs</tt>,</li>
--   <li>Where to cache the custom executable and other files
--   (<a>cacheDir</a>). By default Dyre will use
--   <tt>$XDG_CACHE_HOME/&lt;appName&gt;/</tt>.</li>
--   <li>Extra options to pass to GHC when compiling the custom executable
--   (<a>ghcOpts</a>). Default: none.</li>
--   </ul>
--   
--   See <a>Params</a> for descriptions of all the fields.
module Config.Dyre

-- | <tt>wrapMain</tt> is how Dyre receives 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.
--   
--   <tt>wrapMain</tt> returns whatever value is returned by the
--   <tt>realMain</tt> function in the <tt>params</tt> (if it returns at
--   all). In the common case this is <tt>()</tt> but you can use Dyre with
--   any <tt>IO</tt> action.
wrapMain :: Params cfgType a -> cfgType -> IO a

-- | 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>newParams</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 a
Params :: String -> Bool -> Maybe (IO FilePath) -> Maybe (IO FilePath) -> (cfgType -> IO a) -> (cfgType -> String -> cfgType) -> [FilePath] -> [String] -> [String] -> Bool -> (String -> IO ()) -> RTSOptionHandling -> Bool -> Params cfgType a

-- | 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 a -> 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 a -> Bool

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

-- | The directory to store build files in, including the final generated
--   executable.
[cacheDir] :: Params cfgType a -> 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 a -> cfgType -> IO a

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

-- | Optional extra include dirs to use during compilation. To support
--   installation via cabal-install, include the path returned from
--   <tt>Paths_&lt;appName&gt;.getLibDir</tt>.
[includeDirs] :: Params cfgType a -> [FilePath]

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

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

-- | Should GHC be given the -fforce-recomp flag?
[forceRecomp] :: Params cfgType a -> 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 a -> String -> IO ()

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

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

-- | Construct a <a>Params</a> with the required values as given, and
--   reasonable defaults for everything else.
newParams :: String -> (cfg -> IO a) -> (cfg -> String -> cfg) -> Params cfg a

-- | 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> (because their initial value is <tt>undefined</tt>).
--   
--   Deprecated in favour of <a>newParams</a> which takes the required
--   fields as arguments.

-- | <i>Deprecated: Use <a>newParams</a> instead</i>
defaultParams :: Params cfgType a


-- | This is the only other module aside from <a>Config.Dyre</a> which
--   needs to be imported specially. It contains functions for restarting
--   the program (which, usefully, will cause a recompile if the config has
--   been changed), as well as saving and restoring state across said
--   restarts.
--   
--   The impossibly simple function arguments are a consequence of a little
--   cheating we do using the <a>System.IO.Storage</a> library. Of course,
--   we can't use the stored data unless something else put it there, so
--   this module will probably explode horribly if used outside of a
--   program whose recompilation is managed by Dyre.
--   
--   The functions for saving and loading state come in two variants: one
--   which uses the <a>Read</a> and <a>Show</a> typeclasses, and one which
--   uses <a>Data.Binary</a> to serialize it. The <a>Read</a> and
--   <a>Show</a> versions are much easier to use thanks to automatic
--   deriving, but the binary versions offer more control over saving and
--   loading, as well as probably being a bit faster.
module Config.Dyre.Relaunch

-- | Just relaunch the master binary. We don't have any important state to
--   worry about. (Or, like when <tt>relaunchWith&lt;X&gt;State</tt> 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 <a>getArgs</a> 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
