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


-- | 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 :: 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>ovenUpdateState</a> will always be called single-threaded from
--   <tt>bake-server</tt>; <a>ovenPatchExtra</a> will always be called from
--   <tt>bake-patch-<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 :: (Maybe (state, [patch]) -> IO state) -> (state -> [patch] -> IO [test]) -> (test -> TestInfo test) -> ([Author] -> String -> IO ()) -> (state -> Maybe patch -> IO (String, String)) -> (Host, Port) -> Stringy state -> Stringy patch -> Stringy test -> Oven state patch test

-- | Given a state, and a set of candiates that have passed, merge to
--   create a new state.
ovenUpdateState :: Oven state patch test -> Maybe (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 contained in the string (usually an
--   email)
ovenNotify :: Oven state patch test -> [Author] -> 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)
ovenStringyState :: Oven state patch test -> Stringy state
ovenStringyPatch :: Oven state patch test -> Stringy patch
ovenStringyTest :: Oven state patch test -> Stringy test

-- | 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 <a>readShowStringy</a> 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.
data Stringy s
Stringy :: (s -> String) -> (String -> s) -> (s -> String) -> Stringy s
stringyTo :: Stringy s -> s -> String
stringyFrom :: Stringy s -> String -> s
stringyPretty :: Stringy s -> s -> String

-- | Produce a <a>Stringy</a> for a type with <a>Read</a> and <a>Show</a>.
readShowStringy :: (Show s, Read s) => Stringy s

-- | 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 :: Stringy test -> IO [test] -> (test -> TestInfo test) -> Oven state patch () -> Oven state patch test

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

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

-- | Email notifications when users should be notified about
--   success/failure. Requires the host/port of an SMTP server. Not yet
--   implemented, will always crash.
ovenNotifyEmail :: (Host, Port) -> Oven state patch test -> Oven state patch test
ovenPretty :: Show patch => String -> Oven state 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
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.
require :: [test] -> TestInfo test -> TestInfo test

-- | Is a particular client capable of running a test. Usually an OS check.
suitable :: IO Bool -> TestInfo test -> TestInfo test
startServer :: Port -> FilePath -> Author -> String -> Double -> Oven state patch test -> IO ()
startClient :: (Host, Port) -> Author -> String -> Int -> Double -> Oven state patch test -> IO ()
sendPause :: (Host, Port) -> Author -> IO ()
sendUnpause :: (Host, Port) -> Author -> IO ()
sendAddPatch :: (Host, Port) -> Author -> String -> IO ()
sendDelPatch :: (Host, Port) -> Author -> String -> IO ()
sendDelAllPatches :: (Host, Port) -> Author -> IO ()
type Host = String
type Port = Int
type Author = String