-- 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, as well as the later post
--   <a>http://chplib.wordpress.com/2010/03/02/progression-0-3-bar-charts-and-normalisation/</a>.
@package progression
@version 0.3


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

-- | A type that holds the value for a mean with bounds.
data BoundedMean
BoundedMean :: Double -> Double -> Double -> BoundedMean
meanLB :: BoundedMean -> Double
mean :: BoundedMean -> Double
meanUB :: BoundedMean -> Double

-- | 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 GraphType -> m GraphDataMapping -> GraphSettings m
graphCompareTo :: GraphSettings m -> m [String]
graphFilename :: GraphSettings m -> m String
graphSize :: GraphSettings m -> m (Int, Int)
graphLogY :: GraphSettings m -> m Bool
graphType :: GraphSettings m -> m GraphType
graphGroup :: GraphSettings m -> m GraphDataMapping

-- | The name of a particular group on the x-axis; depending on your
--   choice, this could be a benchmark name or a version name.
newtype GroupName
GroupName :: String -> GroupName
groupName :: GroupName -> String

-- | The name of a particular element of a group (for line graphs this is
--   the name of the line; for bar charts this is a particular recurring
--   bar colour).
newtype SubGroupName
SubGroupName :: String -> SubGroupName
subGroupName :: SubGroupName -> String

-- | Some data that is ready to graph. There are the group labels (groups
--   on the x-axis) which will be plotted in the order given in the list,
--   sub-group labels (either bar colours or lines), and a function that
--   gets the data for a given group label and sub-group label.
--   
--   It is expected that <a>graphData</a> will only ever be called with
--   combinations of the labels in the attached lists, but that it should
--   return a sensible (i.e. non-bottom) value in all these cases.
data GraphData
GraphData :: [GroupName] -> [SubGroupName] -> (GroupName -> SubGroupName -> BoundedMean) -> GraphData
groupLabels :: GraphData -> [GroupName]
subGroupLabels :: GraphData -> [SubGroupName]
graphData :: GraphData -> GroupName -> SubGroupName -> BoundedMean

-- | A function for mapping raw data (i.e. read from CSV files) into data
--   arranged for plotting.
--   
--   The first parameter is the name of the version most recently recorded,
--   or (if just graphing is taking place) the name of the first version
--   listed by the user.
--   
--   The second parameter is a map from version name (e.g. fused-memo) to:
--   a map from benchmark name (e.g. calculate-primes) to the recorded
--   mean.
--   
--   The return is the arranged <a>GraphData</a>.
--   
--   The default is a composition of <a>groupBench</a> and
--   <a>normalise</a>.
type GraphDataMapping = String -> Map String (Map String BoundedMean) -> GraphData

-- | The type of a graph; lines or bars
data GraphType
GraphTypeLines :: GraphType
GraphTypeBars :: GraphType

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

-- | A function that turns benchmarks into major groups, versions into
--   sub-groups, and brings the name of the latest version to the head of
--   the sub-group list.
groupBench :: GraphDataMapping

-- | A function that turns versions into major groups, benchmarks into
--   sub-groups, and brings the name of the latest version to the head of
--   the group list.
groupVersion :: GraphDataMapping

-- | A function that normalises the given data (second parameter) by
--   dividing by the time taken by the given version (first parameter).
--   Benchmarks where the divisor is zero or missing have their times left
--   untouched.
--   
--   This is intended to be applied before <a>groupBench</a> or
--   <a>groupVersion</a>.
normalise :: String -> Map String (Map String BoundedMean) -> Map String (Map String BoundedMean)
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 <tt>-h</tt> (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 in the settings. The first
--   parameter is the one passed to the <a>graphData</a> function (the most
--   recent benchmark).
plotMulti :: String -> 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 ()