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


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


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

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


-- | 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. Gang state changes to <a>GangRunning</a>.
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 Show GangState
instance Eq GangState


-- | 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 ''days'' 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 Read When
instance Show When
instance Eq When
instance Read WhenModifier
instance Show WhenModifier
instance Eq WhenModifier
instance Read Event
instance Show Event
instance Eq Event
instance Read NominalDiffTime


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

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


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

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

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

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

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

-- | Blank text. This is different different from <a>empty</a> because it
--   comes out a a newline when used in a <a>vcat</a>.
blank :: Doc

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

-- | 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 Doc
instance [incoherent] Pretty String
instance [incoherent] Pretty a => Pretty [a]
instance [incoherent] Pretty UTCTime
instance [incoherent] Pretty Integer
instance [incoherent] Pretty Int
instance [incoherent] Pretty Float
instance [incoherent] Pretty Doc

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 Read a => Read (Comparison a)
instance Show a => Show (Comparison a)
instance Pretty a => Pretty (Comparison a)


-- | 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 Eq Timed
instance Ord Timed
instance Show Timed
instance Read Timed
instance Enum Timed
instance Eq Used
instance Ord Used
instance Show Used
instance Read Used
instance Enum Used
instance Eq Sized
instance Ord Sized
instance Show Sized
instance Read Sized
instance Enum Sized
instance Eq Detail
instance Ord Detail
instance Show Detail
instance Read Detail
instance Pretty Sized
instance Pretty Used
instance Pretty Timed

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 Read a => Read (Range a)
instance Show a => Show (Range a)
instance Functor Range
instance Pretty a => Pretty (Range a)

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 Read Seconds
instance Show Seconds
instance Ord Seconds
instance Eq Seconds
instance Read Bytes
instance Show Bytes
instance Ord Bytes
instance Eq Bytes
instance Pretty Bytes
instance Num Bytes
instance Dividable Bytes
instance Real Bytes
instance Pretty Seconds
instance Num Seconds
instance Dividable Seconds
instance Real Seconds


-- | 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 -> Integer -> FilePath -> BuildState

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

-- | Uniqueish id for this build process. On POSIX we'd use the PID, but
--   that doesn't work on Windows. The id is initialised by the Haskell
--   random number generator on startup.
buildStateId :: BuildState -> Integer

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

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

-- | The default build config.
buildStateDefault :: Integer -> 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 = ErrorT BuildError (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

-- | Throw an error in the build monad.
throw :: BuildError -> Build a

-- | Run a build command, catching any exceptions it sends.
catch :: Build a -> (BuildError -> Build a) -> Build 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 :: Pretty a => a -> Build ()

-- | Print some text to stdout followed by a newline.
outLn :: Pretty a => a -> 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 ()

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 = ErrorT BuildError (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

-- | Throw an error in the build monad.
throw :: BuildError -> Build a

-- | Run a build command, catching any exceptions it sends.
catch :: Build a -> (BuildError -> Build a) -> Build 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 :: Pretty a => a -> Build ()

-- | Print some text to stdout followed by a newline.
outLn :: Pretty a => a -> 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)


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


-- | 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 Show PropFile
instance Testable PropFile


-- | 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 Show Platform
instance Read Platform
instance Show Environment
instance Read Environment
instance Pretty Platform
instance Pretty Environment


-- | 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 http:<i></i>msmtp.sourceforge.net/
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 -> Doc

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


-- | 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 Show PropNetwork
instance Testable PropNetwork


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