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


-- | Plot and compare benchmarks
--   
--   Plot benchmarks and compare them. An easy to use package to produce
--   pretty graphs from the <tt>csv</tt> file generated by
--   <tt>criterion</tt> or <tt>gauge</tt> in a few lines of code. It is
--   high level yet pretty flexible in what you can do with it e.g. you can
--   compare groups of benchmarks side by side showing full measurements or
--   a delta, or plot the performance regression of one version of your
--   package against another version.
--   
--   See the README for comprehensive documentation.
@package bench-graph
@version 0.1.2


-- | BenchGraph generates a graph from benchmarking results (CSV) generated
--   by <tt>gauge</tt> or <tt>criterion</tt>, specifically, it generates
--   comparative graphs for several groups of benchmarks that can be
--   compared. The groups could correspond to different packages providing
--   similar and comparable operations or even different versions of the
--   same package. This is a convenient tool to compare performance results
--   of alternative libraries or versions of the same package after you
--   make a change that may impact the performance benchmarks of the
--   package.
--   
--   The input is the CSV file generated by <tt>gauge
--   --csv=results.csv</tt> or a similar output generated by
--   <tt>criterion</tt>. You need to invoke the <a>bgraph</a> function with
--   an appropriate <a>Config</a> to control various parameters of graph
--   generation. Benchmark results found in the CSV file can be classified
--   into several groups using a classifier function and each group is
--   displayed side by side in the graph on the same scale for comparison.
--   The constituent benchmarks in each benchmark group are placed together
--   as a group and a legend is displayed to mark who is who.
--   
--   See the <tt>test</tt> directory for an example of how to use it. A
--   sample output can be found in the <tt>sample-charts</tt> directory.
module BenchGraph

-- | How to show the comparisons among benchmark groups.
data ComparisonStyle

-- | Show full results for all groups
CompareFull :: ComparisonStyle

-- | Show the first group with full results, show delta from the first
--   group for the subsequent groups.
CompareDelta :: ComparisonStyle

-- | Configuration governing generation of chart.
data Config
Config :: FilePath -> Maybe String -> String -> Maybe (String, String) -> [String] -> [String] -> [String] -> [String] -> Maybe (Double, Double, Int) -> ComparisonStyle -> Config

-- | The directory where the output graph should be placed.
[outputDir] :: Config -> FilePath

-- | The title to be embedded in the generated graph.
[chartTitle] :: Config -> Maybe String

-- | User supplied function that translates a benchmark name into a tuple
--   <tt>(groupname, benchname)</tt>, where <tt>groupname</tt> is the name
--   of the group the benchmark should be placed in and <tt>benchname</tt>
--   is the translated benchmark name to be displayed on the graph. If it
--   returns <a>Nothing</a> the benchmark is omitted from the results.
[classifyBenchmark] :: Config -> String -> Maybe (String, String)

-- | User supplied function to sort or reorder the list of benchmark names
--   generated by <a>classifyBenchmark</a>. These are the benchmarks to be
--   plotted for each benchmark group.
[sortBenchmarks] :: Config -> [String] -> [String]

-- | User supplied function to sort or reorder the benchmark group names
--   generated by <a>classifyBenchmark</a>.
[sortBenchGroups] :: Config -> [String] -> [String]

-- | <tt>(RangeMin, RangeMax, NumIntervals)</tt> of the plot on the
--   <tt>y</tt> (time) axis in microseconds.
[setYScale] :: Config -> Maybe (Double, Double, Int)

-- | How to show the comparisons.
[comparisonStyle] :: Config -> ComparisonStyle

-- | Default configuration. Use this as the base configuration and modify
--   the required fields. The defaults are:
--   
--   <pre>
--   outputDir         = "."
--   chartTitle        = Nothing
--   classifyBenchmark = b -&gt; Just ("default", b)
--   sortBenchmarks    = id
--   sortBenchGroups   = id
--   setYScale         = Nothing
--   comparisonStyle   = <a>CompareFull</a>
--   </pre>
defaultConfig :: Config

-- | The first parameter is an input file containing CSV data as generated
--   by <tt>gauge --csv=results.csv</tt> or a similar output generated by
--   <tt>criterion</tt>. The second parameter is the name of the output
--   file containing the graph SVG image. The third parameter is the name
--   of the field that should be plotted. The field is matched with the
--   fields in the header line of the CSV input using a case insensitive
--   match. The last parameter is the configuration to customize the graph,
--   you can start with <a>defaultConfig</a> as the base and set any of the
--   fields that you may want to change.
--   
--   For example:
--   
--   <pre>
--   bgraph "results.csv" "Plot mean time" "mean" <a>defaultConfig</a>
--   </pre>
bgraph :: FilePath -> FilePath -> String -> Config -> IO ()
instance GHC.Classes.Eq BenchGraph.ComparisonStyle