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


-- | Automates the recording and graphing of criterion benchmarks
--   
--   Progression is a library that builds on the criterion benchmarking
--   library. It stores the results of running your benchmarks and graphs
--   the performance of different versions of your program against each
--   other. See the <a>Progression.Main</a> module, and the original blog
--   post at
--   <a>http://chplib.wordpress.com/2010/02/04/progression-supporting-optimisation-in-haskell/</a>
--   to get started.
@package progression
@version 0.2


-- | Some helper functions for dealing with the results (CSV) files.
module Progression.Files

-- | Finds all the results files in the working directory, and returns a
--   list of their labels.
findResultFiles :: IO [String]

-- | Given a label for a result-set, turns it into a CSV file name.
--   
--   Currently this is done by prepending "bench-" and appending ".csv".
makeFileName :: String -> FilePath


-- | A module exposing the configuration for progression.
--   
--   Each item is either a Maybe type or a list. The values Nothing or the
--   empty list indicate a lack of preference and will be over-ridden by
--   the other setting in an mappend; settings can be joined together using
--   their monoid instances.
module Progression.Config

-- | The settings for running benchmarks; which prefixes to run (empty list
--   means no preference, i.e. all -- not none) and where to put the
--   result.
data RunSettings
RunSettings :: [String] -> Maybe String -> RunSettings
runPrefixes :: RunSettings -> [String]
runStoreAs :: RunSettings -> Maybe String

-- | The settings for plotting graphs; which labels (besides the one
--   created by the current run, if applicable) to feature in the graph,
--   and where to store the file (plot.png, by default).
data GraphSettings m
GraphSettings :: m [String] -> m String -> m (Int, Int) -> m Bool -> m ([String] -> [String]) -> GraphSettings m
graphCompareTo :: GraphSettings m -> m [String]
graphFilename :: GraphSettings m -> m String
graphSize :: GraphSettings m -> m (Int, Int)
graphLogY :: GraphSettings m -> m Bool
graphOrder :: GraphSettings m -> m ([String] -> [String])

-- | The mode; just running and recording a benchmark, just graphing
--   existing results, or running a benchmark and produce a graph (the
--   default).
data Mode
JustRun :: Mode
RunAndGraph :: Mode
JustGraph :: Mode

-- | The mode (RunAndGraph, by default), the run settings and the graph
--   settings.
data Config
Config :: Maybe Mode -> RunSettings -> GraphSettings Maybe -> Config
cfgMode :: Config -> Maybe Mode
cfgRun :: Config -> RunSettings
cfgGraph :: Config -> GraphSettings Maybe

-- | The identity functor
newtype Definite a
Definite :: a -> Definite a
definite :: Definite a -> a
override :: GraphSettings Definite -> GraphSettings Maybe -> GraphSettings Definite

-- | Processes the given arguments (got from getArgs, typically) to adjust
--   the given default configuration, returning the resulting
--   configuration. Exits the whole program with an error if there is a
--   problem, or if the user specified <a>-h</a> (in which case it exits
--   after printing the options).
processArgs :: Config -> [String] -> IO Config
instance Eq Mode
instance Monad OptM
instance Monoid (GraphSettings Maybe)
instance Monoid RunSettings
instance Monoid Config


-- | A helper module for plotting.
module Progression.Plot

-- | Plots to the given destination file (using its extension as the
--   terminal type), the given list of labels.
plotMulti :: GraphSettings Definite -> IO ()
instance Applicative FailM
instance Functor FailM
instance Monad FailM


-- | The primary module in Progression; contains methods that you can use
--   as the main method of your wrapper program. Typically, to use
--   Progression, you create a Haskell program that defines/imports the
--   benchmarks, and passes them to the <a>defaultMain</a> method below.
--   You then compile that program and run it to record and graph your
--   benchmarks.
module Progression.Main

-- | Takes the given benchmark (which is likely a benchmark group) and runs
--   it as part of Progression, recording the results and producing graphs.
--   The Benchmark type is imported from the Criterion library, so see the
--   documentation for Criterion to find out what can be benchmarked and
--   any issues that might arise in the benchmarking.
--   
--   This function will process the command-line arguments of the program,
--   consuming any progression arguments, and passing any arguments that
--   occur after a "--" argument on to Criterion. If you want to perform
--   further argument processing, it is best to do this before the call,
--   and wrap the call in <a>withArgs</a>.
defaultMain :: Benchmark -> IO ()

-- | Like <a>defaultMain</a> but you can specify the default configuration.
--   Command-line argument processing is still performed, and command-line
--   settings will take precedence over the config passed in.
defaultMainWith :: Config -> Benchmark -> IO ()