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


-- | Continuous integration system
--   
--   Bake is a continuous integration server, designed for large,
--   productive, semi-trusted teams.
--   
--   <ul>
--   <li><i>Large teams</i> where there are at least several contributors
--   working full-time on a single code base.</li>
--   <li><i>Productive teams</i> which are regularly pushing code, many
--   times a day.</li>
--   <li><i>Semi-trusted teams</i> where code does not go through manual
--   code review, but code does need to pass a test suite and perhaps some
--   static analysis. People are assumed not to be malicious, but are
--   fallible.</li>
--   </ul>
@package bake
@version 0.5


-- | A continuous integration system. For an example of how to get started
--   see <a>https://github.com/ndmitchell/bake#readme</a>.
module Development.Bake

-- | The entry point to the system. Usually you will define:
--   
--   <pre>
--   main = bake myOven
--   </pre>
--   
--   Where <tt>myOven</tt> defines details about the server. The program
--   deals with command line arguments, run <tt>--help</tt> for details.
bake :: (Stringy state, Stringy patch, Stringy test) => Oven state patch test -> IO ()

-- | The central type defining a continuous integration system. Usually
--   constructed with <a>defaultOven</a> then filled out with other
--   <a>Oven</a> modifiers such as <tt>ovenGit</tt> and <a>ovenTest</a>.
--   
--   The types are: <tt>state</tt> is the base state of the system (think
--   HEAD on the master branch); <tt>patch</tt> is a change that is
--   proposed (think a diff); <tt>test</tt> is the type of tests that are
--   run.
--   
--   All IO operations will be called in a direct subdirectory of the
--   directory you start <tt>bake</tt> from. In particular: <a>ovenInit</a>
--   will always be called single-threaded from <tt>bake-init</tt>;
--   <a>ovenUpdate</a> will always be called single-threaded from
--   <tt>bake-update-<i>hash</i></tt>; <a>ovenPatchExtra</a> will always be
--   called from <tt>bake-extra-<i>hash</i></tt>; <a>ovenPrepare</a> and
--   <a>run</a> will always be called from <tt>bake-test-<i>hash</i></tt>.
data Oven state patch test
Oven :: IO state -> (state -> [patch] -> IO state) -> (state -> [patch] -> IO [test]) -> (test -> TestInfo test) -> (Author -> String -> String -> IO ()) -> (state -> Maybe patch -> IO (String, String)) -> (Host, Port) -> (patch -> patch -> Bool) -> Oven state patch test

-- | Get an initial state
[ovenInit] :: Oven state patch test -> IO state

-- | Given a state, and a set of candiates that have passed, merge to
--   create a new state
[ovenUpdate] :: Oven state patch test -> state -> [patch] -> IO state

-- | Prepare a candidate to be run, produces the tests that must pass
[ovenPrepare] :: Oven state patch test -> state -> [patch] -> IO [test]

-- | Produce information about a test
[ovenTestInfo] :: Oven state patch test -> test -> TestInfo test

-- | Tell an author some information. The first <a>String</a> is a subject
--   line, the second an HTML fragment.
[ovenNotify] :: Oven state patch test -> Author -> String -> String -> IO ()

-- | Extra information about a patch, a single line (HTML span), and a
--   longer chunk (HTML block)
[ovenPatchExtra] :: Oven state patch test -> state -> Maybe patch -> IO (String, String)

-- | Default server to use
[ovenServer] :: Oven state patch test -> (Host, Port)

-- | Given two patches (first on submitted first) is the first now
--   redundant
[ovenSupersede] :: Oven state patch test -> patch -> patch -> Bool

-- | The default oven, which doesn't do anything interesting. Usually the
--   starting point.
defaultOven :: Oven () () ()

-- | A type representing a translation between a value and a string, which
--   can be produced by <tt>readShowStringy</tt> if the type has both
--   <a>Read</a> and <a>Show</a> instances. The functions <a>stringyTo</a>
--   and <a>stringyFrom</a> should be inverses of each other. The function
--   <a>stringyPretty</a> shows a value in a way suitable for humans, and
--   can discard uninteresting information.
class Stringy s where stringyPretty = stringyTo
stringyTo :: Stringy s => s -> String
stringyFrom :: Stringy s => String -> s
stringyPretty :: Stringy s => s -> String

-- | Given a <a>Stringy</a> for <tt>test</tt>, and a function that when run
--   on a code base returns the list of tests that need running, and a
--   function to populate a <a>TestInfo</a>, modify the <a>Oven</a> with a
--   test type.
ovenTest :: IO [test] -> (test -> TestInfo test) -> Oven state patch () -> Oven state patch test
data SHA1

-- | Modify an <a>Oven</a> to work with the Git version control system.
--   Requires the name of the repo (e.g.
--   <tt>https://github.com/ndmitchell/bake.git</tt>) and the name of a
--   branch (e.g. <tt>master</tt>). You can optionally give a path fragment
--   which is used to clone into.
ovenGit :: String -> String -> Maybe FilePath -> Oven () () test -> Oven SHA1 SHA1 test

-- | Oven creation for modules using git with the step strategy. Note that
--   any files not in .gitignore will be removed at each step, so make sure
--   your incremental build-products are properly ignored.
ovenStepGit :: IO [FilePath] -> String -> String -> Maybe FilePath -> [String] -> Oven () () test -> Oven SHA1 SHA1 test

-- | Add an additional notification to the list.
ovenNotifyAdd :: (Author -> String -> String -> IO ()) -> Oven state patch test -> Oven state patch test

-- | Produce notifications on <tt>stdout</tt> when users should be notified
--   about success/failure.
ovenNotifyStdout :: Oven state patch test -> Oven state patch test

-- | Send notifications using the given SMTP host/port.
ovenNotifyEmail :: (Host, Port) -> Oven state patch test -> Oven state patch test

-- | Define an oven that allows <tt>foo=...</tt> annotations to be added to
--   the strings. These can be used to annotate important information, e.g.
--   instead of talking about Git SHA1's, you can talk about
--   <tt>person=SHA1</tt> or <tt>branch=SHA1</tt>.
ovenPretty :: Oven state patch test -> Oven state (Pretty patch) test

-- | An oven suitable for use with <a>ovenPretty</a> that supersedes
--   patches which have the same pretty name.
ovenPrettyMerge :: Oven state (Pretty patch) test -> Oven state (Pretty patch) test

-- | This requires a version of <tt>cp</tt>. On Windows, you can get that
--   here: <a>http://gnuwin32.sourceforge.net/packages/coreutils.htm</a>
ovenIncremental :: Oven state patch test -> Oven state patch test
incrementalStart :: IO ()
incrementalDone :: IO ()

-- | Information about a test.
data TestInfo test

-- | The action associated with a <tt>test</tt>.
run :: IO () -> TestInfo test

-- | Change the number of threads a test requires, defaults to 1.
threads :: Int -> TestInfo test -> TestInfo test

-- | Record that a test requires all available threads on a machine,
--   typically used for the build step. Use <tt>getNumCapabilities</tt> to
--   find out how many threads you were allocated.
threadsAll :: TestInfo test -> TestInfo test

-- | Require the following tests have been evaluated on this machine before
--   this test is run. Typically used to require compilation before running
--   most tests.
depend :: [test] -> TestInfo test -> TestInfo test

-- | Is a particular client capable of running a test. Usually an OS check.
--   To run a test must have all its requirements met. Clients can satisfy
--   a requirement by passing <tt>--provide=...</tt> on the command line.
require :: [String] -> TestInfo test -> TestInfo test

-- | Set the priority of a test, those with higher priority are run first.
--   Tests have a default priority of 0.
priority :: Int -> TestInfo test -> TestInfo test
startServer :: (Stringy state, Stringy patch, Stringy test) => Port -> [Author] -> Seconds -> String -> Bool -> Oven state patch test -> IO ()
startClient :: (Stringy state, Stringy patch, Stringy test) => (Host, Port) -> Author -> String -> Int -> [String] -> Double -> Oven state patch test -> IO ()

-- | Garbage collect enough files to satisfy the requirements.
garbageCollect :: Integer -> Double -> Seconds -> [FilePath] -> IO ()
sendAddPatch :: (Host, Port) -> Author -> String -> IO ()
sendDelPatch :: (Host, Port) -> String -> IO ()
sendSetState :: (Host, Port) -> Author -> String -> IO ()
sendPause :: (Host, Port) -> IO ()
sendUnpause :: (Host, Port) -> IO ()
sendRequeue :: (Host, Port) -> IO ()
sendAddSkip :: (Host, Port) -> Author -> String -> IO ()
sendDelSkip :: (Host, Port) -> String -> IO ()
type Host = String
type Port = Int
type Author = String
