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


-- | Rehackable components for writing buildbots and test harnesses.
--   
--   Includes utilities for checking the host platform, running tests,
--   capturing output, handling errors, comparing runtimes against a
--   baseline, sending mail, running events to a schedule etc.
@package buildbox
@version 2.2.1.2


-- | A gang consisting of a fixed number of threads that can run actions in
--   parallel. Good for constructing parallel test frameworks.
module BuildBox.Control.Gang

-- | Abstract gang of threads.
data Gang
data GangState

-- | Gang is running and starting new actions.
GangRunning :: GangState

-- | Gang may be running already started actions, but no new ones are being
--   started.
GangPaused :: GangState

-- | Gang is waiting for currently running actions to finish, but not
--   starting new ones.
GangFlushing :: GangState

-- | Gang is finished, all the actions have completed.
GangFinished :: GangState

-- | Gang was killed, all the threads are dead (or dying).
GangKilled :: GangState

-- | Fork a new gang to run the given actions. This function returns
--   immediately, with the gang executing in the background. Gang state
--   starts as <a>GangRunning</a> then transitions to <a>GangFinished</a>.
--   To block until all the actions are finished use <a>joinGang</a>.
forkGangActions :: Int -> [IO ()] -> IO Gang

-- | Block until all actions have finished executing, or the gang is
--   killed.
joinGang :: Gang -> IO ()

-- | Pause a gang. Actions that have already been started continue to run,
--   but no more will be started until a <a>resumeGang</a> command is
--   issued. Gang state changes to <a>GangPaused</a>.
pauseGang :: Gang -> IO ()

-- | Resume a paused gang, which allows it to continue starting new
--   actions. If the gang was paused it now changes to <a>GangRunning</a>,
--   otherwise nothing happens.
resumeGang :: Gang -> IO ()

-- | Block until already started actions have completed, but don't start
--   any more. Gang state changes to <a>GangFlushing</a>.
flushGang :: Gang -> IO ()

-- | Kill all the threads in a gang. Gang stage changes to
--   <a>GangKilled</a>.
killGang :: Gang -> IO ()

-- | Get the state of a gang.
getGangState :: Gang -> IO GangState

-- | Block until the gang is in the given state.
waitForGangState :: Gang -> GangState -> IO ()
instance GHC.Classes.Eq BuildBox.Control.Gang.GangState
instance GHC.Show.Show BuildBox.Control.Gang.GangState

module BuildBox.Data.Dividable
class Dividable a
divide :: Dividable a => a -> a -> a
instance BuildBox.Data.Dividable.Dividable GHC.Integer.Type.Integer
instance BuildBox.Data.Dividable.Dividable GHC.Types.Float


-- | When the output of a command is long, keeping it as a <a>String</a> is
--   a bad idea.
module BuildBox.Data.Log

-- | A sequence of lines, without newline charaters on the end.
type Log = Seq Line
type Line = Text

-- | O(1) No logs here.
empty :: Log

-- | O(1) Check if the log is empty.
null :: Log -> Bool

-- | O(n) Convert a <a>Log</a> to a <a>String</a>.
toString :: Log -> String

-- | O(n) Convert a <a>String</a> to a <a>Log</a>.
fromString :: String -> Log

-- | O(1) Add a <a>Line</a> to the start of a <a>Log</a>.
(<|) :: Line -> Log -> Log

-- | O(1) Add a <a>Line</a> to the end of a <a>Log</a>.
(|>) :: Log -> Line -> Log

-- | O(log(min(n1,n2))) Concatenate two <a>Log</a>s.
(><) :: Log -> Log -> Log

-- | O(n) Take the first m lines from a log
firstLines :: Int -> Log -> Log

-- | O(n) Take the last m lines from a log
lastLines :: Int -> Log -> Log


-- | A schedule of commands that should be run at a certain time.
module BuildBox.Data.Schedule
second :: NominalDiffTime
minute :: NominalDiffTime
hour :: NominalDiffTime
day :: NominalDiffTime

-- | When to invoke some event.
data When

-- | Just keep doing it.
Always :: When

-- | Don't do it, ever.
Never :: When

-- | Do it some time after we last started it.
Every :: NominalDiffTime -> When

-- | Do it some time after it last finished.
After :: NominalDiffTime -> When

-- | Do it each day at this time. The '<tt>days'</tt> are UTC days, not
--   local ones.
Daily :: TimeOfDay -> When

-- | Modifier to when.
data WhenModifier

-- | If the event hasn't been invoked before then do it immediately when we
--   start the cron process.
Immediate :: WhenModifier

-- | Wait until after this time before doing it first.
WaitUntil :: UTCTime -> WhenModifier
type EventName = String

-- | Records when an event should start, and when it last ran.
data Event
Event :: EventName -> When -> Maybe WhenModifier -> Maybe UTCTime -> Maybe UTCTime -> Event

-- | A unique name for this event. Used when writing the schedule to a
--   file.
[eventName] :: Event -> EventName

-- | When to run the command.
[eventWhen] :: Event -> When

-- | Modifier to the previous.
[eventWhenModifier] :: Event -> Maybe WhenModifier

-- | When the event was last started, if any.
[eventLastStarted] :: Event -> Maybe UTCTime

-- | When the event last finished, if any.
[eventLastEnded] :: Event -> Maybe UTCTime

-- | Given the current time and a list of events, determine which one
--   should be started now. If several events are avaliable then take the
--   one with the earliest start time.
earliestEventToStartAt :: UTCTime -> [Event] -> Maybe Event

-- | Given the current time, decide whether an event could be started. If
--   the <a>WhenModifier</a> is <a>Immediate</a> this always returns true.
--   The <tt>SkipFirst</tt> modifier is ignored, as this is handled
--   separately.
eventCouldStartAt :: UTCTime -> Event -> Bool

-- | Map of event names to their details and build commands.
data Schedule cmd
Schedule :: (Map EventName (Event, cmd)) -> Schedule cmd

-- | A nice way to produce a schedule.
makeSchedule :: [(EventName, When, Maybe WhenModifier, cmd)] -> Schedule cmd

-- | Given an event name, lookup the associated event from a schedule.
lookupEventOfSchedule :: EventName -> Schedule cmd -> Maybe Event

-- | Given an event name, lookup the associated build command from a
--   schedule.
lookupCommandOfSchedule :: EventName -> Schedule cmd -> Maybe cmd

-- | Given a new version of an event, update any matching event in the
--   schedule. If the event not already there then return the original
--   schedule.
adjustEventOfSchedule :: Event -> Schedule cmd -> Schedule cmd

-- | Get the list of events in a schedule, ignoring the build commands.
eventsOfSchedule :: Schedule cmd -> [Event]
instance GHC.Classes.Eq BuildBox.Data.Schedule.Event
instance GHC.Show.Show BuildBox.Data.Schedule.Event
instance GHC.Read.Read BuildBox.Data.Schedule.Event
instance GHC.Classes.Eq BuildBox.Data.Schedule.WhenModifier
instance GHC.Show.Show BuildBox.Data.Schedule.WhenModifier
instance GHC.Read.Read BuildBox.Data.Schedule.WhenModifier
instance GHC.Classes.Eq BuildBox.Data.Schedule.When
instance GHC.Show.Show BuildBox.Data.Schedule.When
instance GHC.Read.Read BuildBox.Data.Schedule.When
instance GHC.Read.Read Data.Time.Clock.Internal.NominalDiffTime.NominalDiffTime


-- | Directory utils that don't need to be in the Build monad.
module BuildBox.IO.Directory

-- | Get the names of all files in a directory. This filters out the fake
--   files like <a>.</a> and '..'
lsFilesIn :: MonadIO m => String -> m [String]

-- | Get the names of all the dirs in this one. This filters out the fake
--   files like <a>.</a> and '..'
lsDirsIn :: MonadIO m => String -> m [String]

-- | Get all the files reachable from this directory
traceFilesFrom :: FilePath -> IO (Seq FilePath)


-- | Pretty printing utils.
module BuildBox.Pretty
class Pretty a
ppr :: Pretty a => a -> Text

-- | A space efficient, packed, unboxed Unicode text type.
data Text

-- | Append two text strings.
(%) :: Text -> Text -> Text

-- | Append two text strings separated by a space.
(%%) :: Text -> Text -> Text

-- | An empty text string.
empty :: Text

-- | Convert a single Char to text.
char :: Char -> Text

-- | Convert a String to text.
string :: String -> Text

-- | Convert a Text to Text (id).
text :: Text -> Text

-- | Concatenate a list of text vertically.
vcat :: [Text] -> Text

-- | Concatenate a list of text vertically, with blank lines in between.
vsep :: [Text] -> Text

-- | Concatenate a list of text.
hcat :: [Text] -> Text

-- | Concatenate a list of text, with spaces in between.
hsep :: [Text] -> Text

-- | Wrap a text thing in round parens.
parens :: Text -> Text

-- | Wrap a text thing in round parens.
braces :: Text -> Text

-- | Wrap a text thing in round parens.
brackets :: Text -> Text

-- | Wrap a text thing in round parens.
angles :: Text -> Text

-- | Indent some text by the given number of characters.
indents :: Int -> [Text] -> Text

-- | Right justify a doc, padding with a given character.
padRc :: Int -> Char -> Text -> Text

-- | Right justify a string with spaces.
padR :: Int -> Text -> Text

-- | Left justify a string, padding with a given character.
padLc :: Int -> Char -> Text -> Text

-- | Left justify a string with spaces.
padL :: Int -> Text -> Text

-- | Pretty print an engineering value, to 4 significant figures. Valid
--   range is 10^(-24) (y/yocto) to 10^(+24) (Y/Yotta). Out of range values
--   yield Nothing.
--   
--   examples:
--   
--   <pre>
--   liftM render $ pprEngDouble "J" 102400    ==&gt;   Just "1.024MJ"
--   liftM render $ pprEngDouble "s" 0.0000123 ==&gt;   Just "12.30us"
--   
--   </pre>
pprEngDouble :: String -> Double -> Maybe Text

-- | Like <a>pprEngDouble</a> but don't display fractional part when the
--   value is &lt; 1000. Good for units where fractional values might not
--   make sense (like bytes).
pprEngInteger :: String -> Integer -> Maybe Text
instance BuildBox.Pretty.Pretty Data.Time.Clock.Internal.UTCTime.UTCTime
instance BuildBox.Pretty.Pretty Data.Text.Internal.Text
instance BuildBox.Pretty.Pretty GHC.Base.String
instance BuildBox.Pretty.Pretty GHC.Types.Int
instance BuildBox.Pretty.Pretty GHC.Integer.Type.Integer
instance BuildBox.Pretty.Pretty GHC.Types.Char

module BuildBox.Data.Range

-- | A range extracted from many-valued data.
data Range a
Range :: a -> a -> a -> Range a
[rangeMin] :: Range a -> a
[rangeAvg] :: Range a -> a
[rangeMax] :: Range a -> a

-- | Make statistics from a list of values.
makeRange :: (Real a, Dividable a) => [a] -> Range a

-- | Flatten a <a>Range</a> into a list of its min, avg and max values.
flattenRange :: Range a -> [a]
instance GHC.Show.Show a => GHC.Show.Show (BuildBox.Data.Range.Range a)
instance GHC.Read.Read a => GHC.Read.Read (BuildBox.Data.Range.Range a)
instance BuildBox.Pretty.Pretty a => BuildBox.Pretty.Pretty (BuildBox.Data.Range.Range a)
instance GHC.Base.Functor BuildBox.Data.Range.Range

module BuildBox.Data.Physical

-- | Seconds of time, pretty printed in engineering format.
data Seconds
Seconds :: Double -> Seconds

-- | Bytes of data, pretty printed in engineering format.
data Bytes
Bytes :: Integer -> Bytes
instance GHC.Classes.Eq BuildBox.Data.Physical.Bytes
instance GHC.Classes.Ord BuildBox.Data.Physical.Bytes
instance GHC.Show.Show BuildBox.Data.Physical.Bytes
instance GHC.Read.Read BuildBox.Data.Physical.Bytes
instance GHC.Classes.Eq BuildBox.Data.Physical.Seconds
instance GHC.Classes.Ord BuildBox.Data.Physical.Seconds
instance GHC.Show.Show BuildBox.Data.Physical.Seconds
instance GHC.Read.Read BuildBox.Data.Physical.Seconds
instance GHC.Real.Real BuildBox.Data.Physical.Bytes
instance BuildBox.Data.Dividable.Dividable BuildBox.Data.Physical.Bytes
instance GHC.Num.Num BuildBox.Data.Physical.Bytes
instance BuildBox.Pretty.Pretty BuildBox.Data.Physical.Bytes
instance GHC.Real.Real BuildBox.Data.Physical.Seconds
instance BuildBox.Data.Dividable.Dividable BuildBox.Data.Physical.Seconds
instance GHC.Num.Num BuildBox.Data.Physical.Seconds
instance BuildBox.Pretty.Pretty BuildBox.Data.Physical.Seconds


-- | The detail is the name of an <tt>Aspect</tt> seprate from its data.
module BuildBox.Data.Detail
data Detail
DetailTimed :: Timed -> Detail
DetailUsed :: Used -> Detail
DetailSized :: Sized -> Detail

-- | Something that takes time to evaluate.
data Timed
TotalWall :: Timed
TotalCpu :: Timed
TotalSys :: Timed
KernelWall :: Timed
KernelCpu :: Timed
KernelSys :: Timed

-- | Some resource used during execution.
data Used
HeapMax :: Used
HeapAlloc :: Used

-- | Some static size of the benchmark that isn't affected during the run.
data Sized
ExeSize :: Sized
instance GHC.Read.Read BuildBox.Data.Detail.Detail
instance GHC.Show.Show BuildBox.Data.Detail.Detail
instance GHC.Classes.Ord BuildBox.Data.Detail.Detail
instance GHC.Classes.Eq BuildBox.Data.Detail.Detail
instance GHC.Enum.Enum BuildBox.Data.Detail.Sized
instance GHC.Read.Read BuildBox.Data.Detail.Sized
instance GHC.Show.Show BuildBox.Data.Detail.Sized
instance GHC.Classes.Ord BuildBox.Data.Detail.Sized
instance GHC.Classes.Eq BuildBox.Data.Detail.Sized
instance GHC.Enum.Enum BuildBox.Data.Detail.Used
instance GHC.Read.Read BuildBox.Data.Detail.Used
instance GHC.Show.Show BuildBox.Data.Detail.Used
instance GHC.Classes.Ord BuildBox.Data.Detail.Used
instance GHC.Classes.Eq BuildBox.Data.Detail.Used
instance GHC.Enum.Enum BuildBox.Data.Detail.Timed
instance GHC.Read.Read BuildBox.Data.Detail.Timed
instance GHC.Show.Show BuildBox.Data.Detail.Timed
instance GHC.Classes.Ord BuildBox.Data.Detail.Timed
instance GHC.Classes.Eq BuildBox.Data.Detail.Timed
instance BuildBox.Pretty.Pretty BuildBox.Data.Detail.Sized
instance BuildBox.Pretty.Pretty BuildBox.Data.Detail.Used
instance BuildBox.Pretty.Pretty BuildBox.Data.Detail.Timed

module BuildBox.Data.Comparison

-- | The comparison of two values.
data Comparison a

-- | Comparison of a recent value with a baseline.
Comparison :: a -> a -> Double -> Comparison a
[comparisonBaseline] :: Comparison a -> a
[comparisonRecent] :: Comparison a -> a
[comparisonSwing] :: Comparison a -> Double

-- | A new value that doesn't have a baseline.
ComparisonNew :: a -> Comparison a
[comparisonNew] :: Comparison a -> a

-- | Make a comparison from two values.
makeComparison :: Real a => a -> a -> Comparison a
instance GHC.Show.Show a => GHC.Show.Show (BuildBox.Data.Comparison.Comparison a)
instance GHC.Read.Read a => GHC.Read.Read (BuildBox.Data.Comparison.Comparison a)
instance BuildBox.Pretty.Pretty a => BuildBox.Pretty.Pretty (BuildBox.Data.Comparison.Comparison a)


-- | Some property of the system we can test for.
--   
--   They have <a>Show</a> instances so we can make nice error messages if
--   a <a>check</a> fails.
module BuildBox.Build.Testable

-- | Some testable property.
class Testable prop
test :: Testable prop => prop -> Build Bool

-- | Testable properties are checkable. If the check returns false then
--   throw an error.
check :: (Show prop, Testable prop) => prop -> Build ()

-- | Testable properties are checkable. If the check returns true then
--   throw an error.
checkFalse :: (Show prop, Testable prop) => prop -> Build ()

-- | Check some property while printing what we're doing.
outCheckOk :: (Show prop, Testable prop) => String -> prop -> Build ()

-- | Check some property while printing what we're doing.
outCheckFalseOk :: (Show prop, Testable prop) => String -> prop -> Build ()

module BuildBox.Build.Benchmark

-- | Benchmark definition.
data Benchmark result
Benchmark :: String -> Build () -> Build a -> a -> Build result -> Benchmark result

-- | A unique name for the benchmark
[benchmarkName] :: Benchmark result -> String

-- | Setup command to run before the main benchmark. This does not
--   contribute to the reported time of the overall result.
[benchmarkSetup] :: Benchmark result -> Build ()

-- | The main command to benchmark.
[benchmarkCommand] :: Benchmark result -> Build a

-- | Check and post-process the result of the main command. This does not
--   contribute to the reported time of the overall result.
[benchmarkCheck] :: Benchmark result -> a -> Build result

-- | Benchmark result.
data BenchResult result
BenchResult :: String -> Int -> Seconds -> result -> BenchResult result
[benchResultName] :: BenchResult result -> String
[benchResultIteration] :: BenchResult result -> Int
[benchResultTime] :: BenchResult result -> Seconds
[benchResultValue] :: BenchResult result -> result

-- | Run a benchmark a single time.
runBenchmark :: Benchmark result -> Int -> Build (BenchResult result)

-- | Run a benchmark the given number of times.
iterateBenchmark :: Int -> Benchmark result -> Build [BenchResult result]

-- | Run a command, returning its elapsed time.
timeBuild :: Build a -> Build (Seconds, a)


-- | Defines the main <a>Build</a> monad and common utils.
module BuildBox.Build

-- | Global builder configuration.
data BuildState
BuildState :: Maybe Handle -> Integer -> FilePath -> BuildState

-- | Log all system commands executed to this file handle.
[buildStateLogSystem] :: BuildState -> Maybe Handle

-- | Sequence number for generating fresh file names.
[buildStateSeq] :: BuildState -> Integer

-- | Scratch directory for making temp files.
[buildStateScratchDir] :: BuildState -> FilePath

-- | The default build config.
buildStateDefault :: FilePath -> BuildState

-- | The builder monad encapsulates and IO action that can fail with an
--   error, and also read some global configuration info.
type Build a = StateT BuildState IO a

-- | Run a build command. The first argument is a directory that can be
--   used for temporary files (like "/tmp")
runBuild :: FilePath -> Build a -> IO (Either BuildError a)

-- | Like <a>runBuild</a> but also takes a <a>BuildState</a>.
runBuildWithState :: BuildState -> Build a -> IO (Maybe a)

-- | Like <a>runBuild</a>, but report whether it succeeded to the console.
--   If it succeeded then return Just the result, else Nothing.
runBuildPrint :: FilePath -> Build a -> IO (Maybe a)

-- | Like <a>runBuildPrint</a> but also takes a <a>BuildState</a>.
runBuildPrintWithState :: BuildState -> Build a -> IO (Maybe a)

-- | Discard the resulting value of a compuation. Used like
--   <tt>successfully . runBuild ...</tt>
successfully :: IO a -> IO ()

-- | The errors we recognise.
data BuildError

-- | Some generic error
ErrorOther :: String -> BuildError

-- | Some system command fell over, and it barfed out the given stdout and
--   stderr.
ErrorSystemCmdFailed :: String -> ExitCode -> Log -> Log -> BuildError
[buildErrorCmd] :: BuildError -> String
[buildErrorCode] :: BuildError -> ExitCode
[buildErrorStdout] :: BuildError -> Log
[buildErrorStderr] :: BuildError -> Log

-- | Some miscellanous IO action failed.
ErrorIOError :: IOError -> BuildError

-- | Some property <tt>check</tt> was supposed to return the given boolean
--   value, but it didn't.
ErrorCheckFailed :: Bool -> prop -> BuildError

-- | A build command needs the following file to continue. This can be used
--   for writing make-like bots.
ErrorNeeds :: FilePath -> BuildError

-- | Alias for <a>throwM</a> from Control.Monad.Catch.
throw :: (MonadThrow m, Exception e) => e -> m a

-- | Provide a handler for exceptions thrown during execution of the first
--   action. Note that type of the type of the argument to the handler will
--   constrain which exceptions are caught. See <a>Control.Exception</a>'s
--   <a>catch</a>.
catch :: (MonadCatch m, Exception e) => m a -> e -> m a -> m a

-- | Throw a needs error saying we needs the given file. A catcher could
--   then usefully create the file, or defer the compuation until it has
--   been created.
needs :: FilePath -> Build ()

-- | Lift an IO action into the build monad. If the action throws any
--   exceptions they get caught and turned into <a>ErrorIOError</a>
--   exceptions in our <a>Build</a> monad.
io :: IO a -> Build a

-- | Like <a>when</a>, but with teh monadz.
whenM :: Monad m => m Bool -> m () -> m ()

-- | Print some text to stdout.
out :: Text -> Build ()

-- | Print some text to stdout followed by a newline.
outLn :: Text -> Build ()

-- | Print a blank line to stdout
outBlank :: Build ()

-- | Print a <tt>-----</tt> line to stdout
outLine :: Build ()

-- | Print a <tt>=====</tt> line to stdout
outLINE :: Build ()

-- | Log a system command to the handle in our <tt>BuildConfig</tt>, if
--   any.
logSystem :: String -> Build ()


-- | Running system commands. On some platforms this may cause the command
--   to be executed directly, so shell tricks won't work. The <a>Build</a>
--   monad can be made to log commands executed with all versions of
--   <a>system</a> by setting <tt>buildConfigLogSystem</tt> in the
--   <tt>BuildConfig</tt> passed to <tt>runBuildPrintWithConfig</tt>.
--   
--   We define a lot of wrappers because executing system commands is the
--   bread-and-butter of buildbots, and we usually need all the versions...
module BuildBox.Command.System

-- | Run a system command, returning its exit code and what it wrote to
--   <tt>stdout</tt> and <tt>stderr</tt>.
system :: String -> Build (ExitCode, String, String)

-- | Quietly run a system command, returning its exit code and what it
--   wrote to <tt>stdout</tt> and <tt>stderr</tt>.
systemq :: String -> Build (ExitCode, String, String)

-- | Run a successful system command, returning what it wrote to
--   <tt>stdout</tt> and <tt>stderr</tt>. If the exit code is
--   <a>ExitFailure</a> then throw an error in the <a>Build</a> monad.
ssystem :: String -> Build (String, String)

-- | Quietly run a successful system command, returning what it wrote to
--   <tt>stdout</tt> and <tt>stderr</tt>. If the exit code is
--   <a>ExitFailure</a> then throw an error in the <a>Build</a> monad.
ssystemq :: String -> Build (String, String)

-- | Run a successful system command, returning what it wrote to its
--   <tt>stdout</tt>. If anything was written to <tt>stderr</tt> then treat
--   that as failure. If it fails due to writing to <tt>stderr</tt> or
--   returning <a>ExitFailure</a> then throw an error in the <a>Build</a>
--   monad.
sesystem :: String -> Build String

-- | Quietly run a successful system command, returning what it wrote to
--   its <tt>stdout</tt>. If anything was written to <tt>stderr</tt> then
--   treat that as failure. If it fails due to writing to <tt>stderr</tt>
--   or returning <a>ExitFailure</a> then throw an error in the
--   <a>Build</a> monad.
sesystemq :: String -> Build String

-- | Like <a>systemTeeIO</a>, but in the <a>Build</a> monad.
systemTee :: Bool -> String -> String -> Build (ExitCode, String, String)

-- | Like <a>systemTeeLogIO</a>, but in the <a>Build</a> monad.
systemTeeLog :: Bool -> String -> Log -> Build (ExitCode, Log, Log)

-- | Like <a>systemTeeIO</a>, but in the <a>Build</a> monad and throw an
--   error if it returns <a>ExitFailure</a>.
ssystemTee :: Bool -> String -> String -> Build ()

-- | Like <a>systemTeeLogIO</a>, but with strings.
systemTeeIO :: Bool -> String -> String -> IO (ExitCode, String, String)

-- | Run a system command, returning its <a>ExitCode</a> and what was
--   written to <tt>stdout</tt> and <tt>stderr</tt>.
systemTeeLogIO :: Bool -> String -> Log -> IO (ExitCode, Log, Log)


-- | What do build 'bots dream about?
module BuildBox.Command.Sleep

-- | Sleep for a given number of seconds.
sleep :: Int -> Build ()

-- | Sleep for a given number of milliseconds.
msleep :: Int -> Build ()


-- | A simple '<tt>cron'</tt> loop. Used for running commands according to
--   a given schedule.
module BuildBox.Control.Cron

-- | Given a schedule of commands, run them when their time is due. Only
--   one command is run at a time. If several commands could be started at
--   a specific moment, then we take the one with the earliest potential
--   start time. If any command throws an error in the <a>Build</a> monad
--   then the whole loop does.
cronLoop :: Schedule (Build ()) -> Build ()


-- | Working with the file system.
module BuildBox.Command.File

-- | Properties of the file system we can test for.
data PropFile

-- | Some executable is in the current path.
HasExecutable :: String -> PropFile

-- | Some file exists.
HasFile :: FilePath -> PropFile

-- | Some directory exists.
HasDir :: FilePath -> PropFile

-- | Some file is empty.
FileEmpty :: FilePath -> PropFile

-- | Run a command in a different working directory. Throws an error if the
--   directory doesn't exist.
inDir :: FilePath -> Build a -> Build a

-- | Create a new directory with the given name, run a command within it,
--   then change out and recursively delete the directory. Throws an error
--   if a directory with the given name already exists.
inScratchDir :: FilePath -> Build a -> Build a

-- | Delete a dir recursively if it's there, otherwise do nothing.
clobberDir :: FilePath -> Build ()

-- | Create a new directory if it isn't already there, or return
--   successfully if it is.
ensureDir :: FilePath -> Build ()

-- | Create a temp file, pass it to some command, then delete the file
--   after the command finishes.
withTempFile :: (FilePath -> Build a) -> Build a

-- | Atomically write a file by first writing it to a tmp file then
--   renaming it. This prevents concurrent processes from reading
--   half-written files.
atomicWriteFile :: FilePath -> String -> Build ()

-- | The file extension for an executable on the current system.
exe :: String
instance GHC.Show.Show BuildBox.Command.File.PropFile
instance BuildBox.Build.Testable.Testable BuildBox.Command.File.PropFile


-- | Working with the network.
module BuildBox.Command.Network
data PropNetwork

-- | The given host is reachable with <tt>ping</tt>.
HostReachable :: HostName -> PropNetwork

-- | Use <tt>wget</tt> to check if a web-page is gettable. The page is
--   deleted after downloading.
UrlGettable :: URL -> PropNetwork
instance GHC.Show.Show BuildBox.Command.Network.PropNetwork
instance BuildBox.Build.Testable.Testable BuildBox.Command.Network.PropNetwork


-- | Gathering information about the build environment.
module BuildBox.Command.Environment

-- | The environment consists of the <a>Platform</a>, and some tool
--   versions.
data Environment
Environment :: Platform -> [(String, String)] -> Environment
[environmentPlatform] :: Environment -> Platform
[environmentVersions] :: Environment -> [(String, String)]

-- | Get the current environment, including versions of these tools.
getEnvironmentWith :: [(String, Build String)] -> Build Environment

-- | Generic information about the platform we're running on.
data Platform
Platform :: String -> String -> String -> String -> String -> Platform
[platformHostName] :: Platform -> String
[platformHostArch] :: Platform -> String
[platformHostProcessor] :: Platform -> String
[platformHostOS] :: Platform -> String
[platformHostRelease] :: Platform -> String

-- | Get information about the host platform.
getHostPlatform :: Build Platform

-- | Get the name of this host, using <tt>uname</tt>.
getHostName :: Build String

-- | Get the host architecture, using <tt>uname</tt>.
getHostArch :: Build String

-- | Get the host processor name, using <tt>uname</tt>.
getHostProcessor :: Build String

-- | Get the host operating system, using <tt>uname</tt>.
getHostOS :: Build String

-- | Get the host operating system release, using <tt>uname</tt>.
getHostRelease :: Build String

-- | Get the version of this GHC, or throw an error if it can't be found.
getVersionGHC :: FilePath -> Build String

-- | Get the version of this GCC, or throw an error if it can't be found.
getVersionGCC :: FilePath -> Build String
instance GHC.Read.Read BuildBox.Command.Environment.Environment
instance GHC.Show.Show BuildBox.Command.Environment.Environment
instance GHC.Read.Read BuildBox.Command.Environment.Platform
instance GHC.Show.Show BuildBox.Command.Environment.Platform
instance BuildBox.Pretty.Pretty BuildBox.Command.Environment.Environment
instance BuildBox.Pretty.Pretty BuildBox.Command.Environment.Platform


-- | Sending email. If you're on a system with a working <tt>sendmail</tt>
--   then use that. Otherwise, the stand-alone <tt>msmtp</tt> server is
--   easy to set up. Get <tt>msmtp</tt> here:
--   <a>http://msmtp.sourceforge.net</a>
module BuildBox.Command.Mail

-- | An email message that we can send.
data Mail
Mail :: String -> String -> String -> UTCTime -> TimeZone -> String -> String -> Mail
[mailFrom] :: Mail -> String
[mailTo] :: Mail -> String
[mailSubject] :: Mail -> String
[mailTime] :: Mail -> UTCTime
[mailTimeZone] :: Mail -> TimeZone
[mailMessageId] :: Mail -> String
[mailBody] :: Mail -> String

-- | An external mailer that can send messages. Also contains mail server
--   info if needed.
data Mailer

-- | Send the mail by writing to the stdin of this command. On many systems
--   the command <tt>sendmail</tt> will be aliased to an appropriate
--   wrapper for whatever Mail Transfer Agent (MTA) you have installed.
MailerSendmail :: FilePath -> [String] -> Mailer
[mailerPath] :: Mailer -> FilePath
[mailerExtraFlags] :: Mailer -> [String]

-- | Send mail via MSMTP, which is a stand-alone SMTP sender. This might be
--   be easier to set up if you don't have a real MTA installed. Get it
--   from <a>http://msmtp.sourceforge.net/</a>
MailerMSMTP :: FilePath -> Maybe Int -> Mailer
[mailerPath] :: Mailer -> FilePath
[mailerPort] :: Mailer -> Maybe Int

-- | Create a mail with a given from, to, subject and body. Fill in the
--   date and message id based on the current time. Valid dates and message
--   ids are needed to prevent the mail being bounced by anti-spam systems.
createMailWithCurrentTime :: String -> String -> String -> String -> Build Mail

-- | Render an email message as a string.
renderMail :: Mail -> Text

-- | Send a mail message.
sendMailWithMailer :: Mail -> Mailer -> Build ()
instance GHC.Show.Show BuildBox.Command.Mail.Mailer
instance GHC.Show.Show BuildBox.Command.Mail.Mail


-- | Querying a darcs repository
module BuildBox.Command.Darcs
type EmailAddress = String
type DarcsPath = String
data DarcsPatch
DarcsPatch :: LocalTime -> EmailAddress -> Log -> DarcsPatch
[darcsTimestamp] :: DarcsPatch -> LocalTime
[darcsAuthor] :: DarcsPatch -> EmailAddress
[darcsComment] :: DarcsPatch -> Log

-- | List all patches in the given repository. If no repository is given,
--   the current working directory is used.
changes :: Maybe DarcsPath -> Build [DarcsPatch]

-- | Retrieve the last N changes from the repository
changesN :: Maybe DarcsPath -> Int -> Build [DarcsPatch]

-- | Retrieve all patches submitted to the repository after the given time
changesAfter :: Maybe DarcsPath -> LocalTime -> Build [DarcsPatch]
instance GHC.Show.Show BuildBox.Command.Darcs.DarcsPatch

module BuildBox

-- | The builder monad encapsulates and IO action that can fail with an
--   error, and also read some global configuration info.
type Build a = StateT BuildState IO a

-- | Run a build command. The first argument is a directory that can be
--   used for temporary files (like "/tmp")
runBuild :: FilePath -> Build a -> IO (Either BuildError a)

-- | Like <a>runBuild</a> but also takes a <a>BuildState</a>.
runBuildWithState :: BuildState -> Build a -> IO (Maybe a)

-- | The errors we recognise.
data BuildError

-- | Some generic error
ErrorOther :: String -> BuildError

-- | Some system command fell over, and it barfed out the given stdout and
--   stderr.
ErrorSystemCmdFailed :: String -> ExitCode -> Log -> Log -> BuildError
[buildErrorCmd] :: BuildError -> String
[buildErrorCode] :: BuildError -> ExitCode
[buildErrorStdout] :: BuildError -> Log
[buildErrorStderr] :: BuildError -> Log

-- | Some miscellanous IO action failed.
ErrorIOError :: IOError -> BuildError

-- | Some property <tt>check</tt> was supposed to return the given boolean
--   value, but it didn't.
ErrorCheckFailed :: Bool -> prop -> BuildError

-- | A build command needs the following file to continue. This can be used
--   for writing make-like bots.
ErrorNeeds :: FilePath -> BuildError

-- | Alias for <a>throwM</a> from Control.Monad.Catch.
throw :: (MonadThrow m, Exception e) => e -> m a

-- | Provide a handler for exceptions thrown during execution of the first
--   action. Note that type of the type of the argument to the handler will
--   constrain which exceptions are caught. See <a>Control.Exception</a>'s
--   <a>catch</a>.
catch :: (MonadCatch m, Exception e) => m a -> e -> m a -> m a

-- | Throw a needs error saying we needs the given file. A catcher could
--   then usefully create the file, or defer the compuation until it has
--   been created.
needs :: FilePath -> Build ()

-- | Lift an IO action into the build monad. If the action throws any
--   exceptions they get caught and turned into <a>ErrorIOError</a>
--   exceptions in our <a>Build</a> monad.
io :: IO a -> Build a

-- | Print some text to stdout.
out :: Text -> Build ()

-- | Print some text to stdout followed by a newline.
outLn :: Text -> Build ()


-- | Time utils useful for writing buildbots.
module BuildBox.Time

-- | Read a time of day string like <tt>17:34:05</tt> in the local time
--   zone and convert that to a UTC time of day. Good for parsing command
--   line args to buildbots.
readLocalTimeOfDayAsUTC :: String -> IO TimeOfDay

-- | Get a local time stamp with format YYYYMMDD_HHMMSS. Good for naming
--   files with.
getStampyTime :: IO String

-- | Get the local midnight we've just had as a <a>LocalTime</a>.
getMidnightTodayLocal :: IO LocalTime

-- | Get the local midnight that we've just had, as a <a>UTCTime</a>.
getMidnightTodayUTC :: IO UTCTime

-- | Get the local midnight we're about to have as a <a>LocalTime</a>.
getMidnightTomorrowLocal :: IO LocalTime

-- | Get the local midnight we're about to have as a <a>UTCTime</a>.
getMidnightTomorrowUTC :: IO UTCTime