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


-- | Testing By Convention
--   
--   TBC is a harness for running tests, relying on other libraries such as
--   QuickCheck and HUnit to do the actual testing. TBC lets you skip a lot
--   of boilerplate by adopting naming conventions for tests. It also
--   supports test-driven development (TDD) by running as many tests as it
--   can compile, whatever the state of the project as a whole. For further
--   information see the examples that accompany the distribution.
@package TBC
@version 0.0.3

module Test.TBC

-- | The test should yield the string <a>True</a>. This should work for
--   tests of type <tt>Bool</tt>, <tt>IO Bool</tt>, <tt>IO ()</tt> with a
--   <tt>putStrLn</tt>, ...
--   
--   Note the <a>seq</a> in its implementation is not entirely useless: the
--   test may use <tt>unsafePerformIO</tt> or <tt>trace</tt> to
--   incidentally output things after <a>True</a>.
booltest :: TestConvention

-- | The <a>seq</a>ed test should throw an exception.
exception :: TestConvention

-- | A HUnit unit test.
hunit :: TestConvention

-- | A QuickCheck test. We use the <a>quickCheck</a> driver, i.e., the
--   default settings.
quickcheck :: TestConvention

-- | Skip <tt>.darcs</tt> and <tt>.git</tt> directories, and Cabal's
--   <tt>dist</tt> directory.
--   
--   Could also imagine skipping subproject directories.
stdDirectoryConv :: DirectoryConvention s

-- | Skip Cabal's <tt>Setup.hs</tt>.
stdTestFileConv :: TestFileConvention s

-- | The standard set of conventions.
std :: Conventions s

-- | A <i>directory convention</i> maps a directory name into an action.
type DirectoryConvention s = FilePath -> s -> (Action, s)

-- | A <i>test file convention</i> maps a file name into an action.
type TestFileConvention s = FilePath -> s -> (Action, s)

-- | A <i>test convention</i> maps a line in a <tt>TestFile</tt> into a
--   function that runs the test.
type TestConvention = String -> Maybe (Driver -> IO Result)

-- | An <i>action</i> tells TBC what to do when it (recursively) encounters
--   a directory or file.
data Action

-- | Cease testing.
Stop :: Action

-- | Skip this file or directory.
Skip :: Action

-- | Process this file or directory.
Cont :: Action

-- | A single test.
data Test
Test :: String -> Location -> (Driver -> IO Result) -> Test

-- | Each <a>Test</a> in a <tt>TestFile</tt> must have a different name.
tName :: Test -> String
tLocation :: Test -> Location
tRun :: Test -> Driver -> IO Result

-- | The result of a single <a>Test</a>.
data Result

-- | Skip this test.
TestResultSkip :: Result

-- | This test has not yet been written.
TestResultToDo :: Result

-- | Cease testing.
TestResultStop :: Result

-- | The test succeeded.
TestResultSuccess :: Result

-- | The test failed with this explanation.
TestResultFailure :: [String] -> Result
msg :: Result -> [String]

-- | A renderer maps a verbosity level into a bunch of functions that tells
--   the user of various events.
type Renderer s = Verbosity -> RenderFns s

-- | The collection of rendering functions.
data RenderFns s
RenderFns :: IO s -> (FilePath -> [Test] -> [String] -> s -> IO s) -> (FilePath -> s -> IO s) -> (FilePath -> s -> IO s) -> (Test -> s -> Result -> IO s) -> (s -> IO ExitCode) -> RenderFns s

-- | Allocate a new test state.
rInitialState :: RenderFns s -> IO s

-- | Render a compilation failure. FIXME refine: skipped a file, skipped
--   some tests, some tests told us to skip, ...
rCompilationFailure :: RenderFns s -> FilePath -> [Test] -> [String] -> s -> IO s

-- | Render a skipped directory or file.
rSkip :: RenderFns s -> FilePath -> s -> IO s

-- | Handle being told to stop.
rStop :: RenderFns s -> FilePath -> s -> IO s

-- | Execute a test and render its result.
rTest :: RenderFns s -> Test -> s -> Result -> IO s

-- | Yield an <a>ExitCode</a> depending on how the tests went.
rFinal :: RenderFns s -> s -> IO ExitCode

-- | A collection of conventions.
data Conventions s
Conventions :: DirectoryConvention s -> TestFileConvention s -> [TestConvention] -> Conventions s

-- | The directory convention.
cDirectory :: Conventions s -> DirectoryConvention s

-- | The filename convention.
cTestFile :: Conventions s -> TestFileConvention s

-- | The test conventions.
cTests :: Conventions s -> [TestConvention]
data Verbosity :: *
silent :: Verbosity
normal :: Verbosity
verbose :: Verbosity
deafening :: Verbosity

-- | Non fatal conditions that may be indicative of an error or problem.
--   
--   We display these at the <a>normal</a> verbosity level.
warn :: Verbosity -> String -> IO ()

-- | Useful status messages.
--   
--   We display these at the <a>normal</a> verbosity level.
--   
--   This is for the ordinary helpful status messages that users see. Just
--   enough information to know that things are working but not floods of
--   detail.
notice :: Verbosity -> String -> IO ()
setupMessage :: Verbosity -> String -> PackageIdentifier -> IO ()

-- | More detail on the operation of some action.
--   
--   We display these messages when the verbosity level is <a>verbose</a>
info :: Verbosity -> String -> IO ()

-- | Detailed internal debugging information
--   
--   We display these messages when the verbosity level is <a>deafening</a>
debug :: Verbosity -> String -> IO ()

-- | Location of a <a>Test</a>.
data Location
Location :: FilePath -> Int -> Int -> Location
lFile :: Location -> FilePath
lLine :: Location -> Int
lColumn :: Location -> Int

-- | Construct a location.
mkLocation :: FilePath -> Int -> Int -> Location

-- | Discern a test name from a string, viz the entirety of the varid
--   starting at the start of the string. FIXME this should follow the
--   Haskell lexical conventions and perhaps be more robust.
mkTestName :: String -> String

-- | Visit all files in a directory tree. FIXME try to eliminate the
--   <a>.</a> with some refactoring.
traverseDirectories :: Conventions s -> Driver -> RenderFns s -> [FilePath] -> s -> IO s

-- | Apply a list of conventions to the guts of a <tt>TestFile</tt>.
applyTestConventions :: [TestConvention] -> FilePath -> String -> [Test]

-- | Interaction with a Haskell system.
data Driver
MkDriver :: (String -> IO [String]) -> (String -> IO [String]) -> IO () -> IO ExitCode -> Driver

-- | Execute the given Haskell code and return the response as a list of
--   lines.
hci_send_cmd :: Driver -> String -> IO [String]

-- | Load a file into the Haskell system.
hci_load_file :: Driver -> String -> IO [String]

-- | Terminate with prejudice.
hci_kill :: Driver -> IO ()

-- | Clean exit.
hci_close :: Driver -> IO ExitCode

-- | A driver for <tt>GHCi</tt> using a slave process.
ghci :: Verbosity -> String -> [String] -> IO Driver

-- | A hardwired (conventional) driver.
tbc :: Driver -> [FilePath] -> IO ()

-- | A parametrised bells-and-whistles driver.
tbcWithHooks :: Conventions s -> RenderFns s -> Driver -> [FilePath] -> IO ExitCode

-- | A driver compatible with Cabal's <tt>runTests</tt> hook.
--   
--   However the test infrastructure in Cabal has changed since this was
--   written, and its use is discouraged. Use the TBC binary instead.
--   
--   This is used by the TBC binary.
tbcCabal :: Verbosity -> Args -> Bool -> PackageDescription -> LocalBuildInfo -> IO ()

-- | This is a drop-in replacement for Cabal's <a>defaultMain</a>.
--   
--   However the test infrastructure in Cabal has changed since this was
--   written, and its use is discouraged. Use the TBC binary instead.
defaultMain :: IO ()