Flat directory/module structure

src/export/asciidoc.rs

@@ -0,0 +1,237 @@
+use super::Exporter;
+
+use crate::benchmark_result::BenchmarkResult;
+use crate::format::format_duration_value;
+use crate::units::Unit;
+
+use std::io::Result;
+
+#[derive(Default)]
+pub struct AsciidocExporter {}
+
+impl Exporter for AsciidocExporter {
+    fn serialize(&self, results: &[BenchmarkResult], unit: Option<Unit>) -> Result<Vec<u8>> {
+        let unit = if let Some(unit) = unit {
+            // Use the given unit for all entries.
+            unit
+        } else if let Some(first_result) = results.first() {
+            // Use the first BenchmarkResult entry to determine the unit for all entries.
+            format_duration_value(first_result.mean, None).1
+        } else {
+            // Default to `Second`.
+            Unit::Second
+        };
+
+        let mut res: Vec<u8> = Vec::new();
+        res.append(&mut table_open());
+        res.append(&mut table_startend());
+        res.append(&mut table_header(unit));
+        for result in results {
+            res.push(b'\n');
+            res.append(&mut table_row(result, unit));
+        }
+        res.append(&mut table_startend());
+
+        Ok(res)
+    }
+}
+
+fn table_open() -> Vec<u8> {
+    "[cols=\"<,>,>\"]\n".bytes().collect()
+}
+
+fn table_startend() -> Vec<u8> {
+    "|===\n".bytes().collect()
+}
+
+fn table_header(unittype: Unit) -> Vec<u8> {
+    let unit_short_name = unittype.short_name();
+    format!(
+        "| Command | Mean [{unit}] | Min…Max [{unit}]\n",
+        unit = unit_short_name
+    )
+    .into_bytes()
+}
+
+fn table_row(entry: &BenchmarkResult, unit: Unit) -> Vec<u8> {
+    let form = |val| format_duration_value(val, Some(unit));
+    format!(
+        "| `{}`\n\
+         | {} ± {}\n\
+         | {}…{}\n",
+        entry.command.replace("|", "\\|"),
+        form(entry.mean).0,
+        form(entry.stddev).0,
+        form(entry.min).0,
+        form(entry.max).0
+    )
+    .into_bytes()
+}
+
+/// Ensure various options for the header generate correct results
+#[test]
+fn test_asciidoc_header() {
+    let conms: Vec<u8> = "| Command | Mean [ms] | Min…Max [ms]\n".bytes().collect();
+    let cons: Vec<u8> = "| Command | Mean [s] | Min…Max [s]\n".bytes().collect();
+    let genms = table_header(Unit::MilliSecond);
+    let gens = table_header(Unit::Second);
+
+    assert_eq!(conms, genms);
+    assert_eq!(cons, gens);
+}
+
+/// Ensure each table row is generated properly
+#[test]
+fn test_asciidoc_table_row() {
+    use std::collections::BTreeMap;
+    let result = BenchmarkResult::new(
+        String::from("sleep 1"), // command
+        0.10491992406666667,     // mean
+        0.00397851689425097,     // stddev
+        0.10491992406666667,     // median
+        0.005182013333333333,    // user
+        0.0,                     // system
+        0.1003342584,            // min
+        0.10745223440000001,     // max
+        vec![
+            // times
+            0.1003342584,
+            0.10745223440000001,
+            0.10697327940000001,
+        ],
+        vec![Some(0), Some(0), Some(0)], // exit codes
+        BTreeMap::new(),                 // param
+    );
+
+    let expms = format!(
+        "| `{}`\n\
+         | {} ± {}\n\
+         | {}…{}\n",
+        result.command,
+        Unit::MilliSecond.format(result.mean),
+        Unit::MilliSecond.format(result.stddev),
+        Unit::MilliSecond.format(result.min),
+        Unit::MilliSecond.format(result.max)
+    )
+    .into_bytes();
+    let exps = format!(
+        "| `{}`\n\
+         | {} ± {}\n\
+         | {}…{}\n",
+        result.command,
+        Unit::Second.format(result.mean),
+        Unit::Second.format(result.stddev),
+        Unit::Second.format(result.min),
+        Unit::Second.format(result.max)
+    )
+    .into_bytes();
+
+    let genms = table_row(&result, Unit::MilliSecond);
+    let gens = table_row(&result, Unit::Second);
+
+    assert_eq!(expms, genms);
+    assert_eq!(exps, gens);
+}
+
+/// Ensure commands get properly escaped
+#[test]
+fn test_asciidoc_table_row_command_escape() {
+    use std::collections::BTreeMap;
+    let result = BenchmarkResult::new(
+        String::from("sleep 1|"), // command
+        0.10491992406666667,      // mean
+        0.00397851689425097,      // stddev
+        0.10491992406666667,      // median
+        0.005182013333333333,     // user
+        0.0,                      // system
+        0.1003342584,             // min
+        0.10745223440000001,      // max
+        vec![
+            // times
+            0.1003342584,
+            0.10745223440000001,
+            0.10697327940000001,
+        ],
+        vec![Some(0), Some(0), Some(0)], // exit codes
+        BTreeMap::new(),                 // param
+    );
+    let exps = format!(
+        "| `sleep 1\\|`\n\
+         | {} ± {}\n\
+         | {}…{}\n",
+        Unit::Second.format(result.mean),
+        Unit::Second.format(result.stddev),
+        Unit::Second.format(result.min),
+        Unit::Second.format(result.max)
+    )
+    .into_bytes();
+    let gens = table_row(&result, Unit::Second);
+
+    assert_eq!(exps, gens);
+}
+
+/// Integration test
+#[test]
+fn test_asciidoc() {
+    use std::collections::BTreeMap;
+    let exporter = AsciidocExporter::default();
+    // NOTE: results are fabricated, unlike above
+    let results = vec![
+        BenchmarkResult::new(
+            String::from("FOO=1 BAR=2 command | 1"),
+            1.0,
+            2.0,
+            1.0,
+            3.0,
+            4.0,
+            5.0,
+            6.0,
+            vec![7.0, 8.0, 9.0],
+            vec![Some(0), Some(0), Some(0)],
+            {
+                let mut params = BTreeMap::new();
+                params.insert("foo".into(), "1".into());
+                params.insert("bar".into(), "2".into());
+                params
+            },
+        ),
+        BenchmarkResult::new(
+            String::from("FOO=1 BAR=7 command | 2"),
+            11.0,
+            12.0,
+            11.0,
+            13.0,
+            14.0,
+            15.0,
+            16.0,
+            vec![17.0, 18.0, 19.0],
+            vec![Some(0), Some(0), Some(0)],
+            {
+                let mut params = BTreeMap::new();
+                params.insert("foo".into(), "1".into());
+                params.insert("bar".into(), "7".into());
+                params
+            },
+        ),
+    ];
+    // NOTE: only testing with s, s/ms is tested elsewhere
+    let exps: String = String::from(
+        "[cols=\"<,>,>\"]\n\
+         |===\n\
+         | Command | Mean [s] | Min…Max [s]\n\
+         \n\
+         | `FOO=1 BAR=2 command \\| 1`\n\
+         | 1.000 ± 2.000\n\
+         | 5.000…6.000\n\
+         \n\
+         | `FOO=1 BAR=7 command \\| 2`\n\
+         | 11.000 ± 12.000\n\
+         | 15.000…16.000\n\
+         |===\n\
+         ",
+    );
+    let gens =
+        String::from_utf8(exporter.serialize(&results, Some(Unit::Second)).unwrap()).unwrap();
+
+    assert_eq!(exps, gens);
+}

src/export/csv.rs

@@ -0,0 +1,107 @@
+use super::Exporter;
+
+use crate::benchmark_result::BenchmarkResult;
+use crate::units::Unit;
+
+use std::borrow::Cow;
+use std::io::{Error, ErrorKind, Result};
+
+use csv::WriterBuilder;
+
+#[derive(Default)]
+pub struct CsvExporter {}
+
+impl Exporter for CsvExporter {
+    fn serialize(&self, results: &[BenchmarkResult], _unit: Option<Unit>) -> Result<Vec<u8>> {
+        let mut writer = WriterBuilder::new().from_writer(vec![]);
+
+        {
+            let mut headers: Vec<Cow<[u8]>> = [
+                // The list of times and exit codes cannot be exported to the CSV file - omit them.
+                "command", "mean", "stddev", "median", "user", "system", "min", "max",
+            ]
+            .iter()
+            .map(|x| Cow::Borrowed(x.as_bytes()))
+            .collect();
+            if let Some(res) = results.first() {
+                for param_name in res.parameters.keys() {
+                    headers.push(Cow::Owned(format!("parameter_{}", param_name).into_bytes()));
+                }
+            }
+            writer.write_record(headers)?;
+        }
+
+        for res in results {
+            let mut fields = vec![Cow::Borrowed(res.command.as_bytes())];
+            for f in &[
+                res.mean, res.stddev, res.median, res.user, res.system, res.min, res.max,
+            ] {
+                fields.push(Cow::Owned(f.to_string().into_bytes()))
+            }
+            for v in res.parameters.values() {
+                fields.push(Cow::Borrowed(v.as_bytes()))
+            }
+            writer.write_record(fields)?;
+        }
+
+        writer
+            .into_inner()
+            .map_err(|e| Error::new(ErrorKind::Other, e))
+    }
+}
+
+#[test]
+fn test_csv() {
+    use std::collections::BTreeMap;
+    let exporter = CsvExporter::default();
+
+    // NOTE: results are fabricated
+    let results = vec![
+        BenchmarkResult::new(
+            String::from("FOO=one BAR=two command | 1"),
+            1.0,
+            2.0,
+            1.0,
+            3.0,
+            4.0,
+            5.0,
+            6.0,
+            vec![7.0, 8.0, 9.0],
+            vec![Some(0), Some(0), Some(0)],
+            {
+                let mut params = BTreeMap::new();
+                params.insert("foo".into(), "one".into());
+                params.insert("bar".into(), "two".into());
+                params
+            },
+        ),
+        BenchmarkResult::new(
+            String::from("FOO=one BAR=seven command | 2"),
+            11.0,
+            12.0,
+            11.0,
+            13.0,
+            14.0,
+            15.0,
+            16.5,
+            vec![17.0, 18.0, 19.0],
+            vec![Some(0), Some(0), Some(0)],
+            {
+                let mut params = BTreeMap::new();
+                params.insert("foo".into(), "one".into());
+                params.insert("bar".into(), "seven".into());
+                params
+            },
+        ),
+    ];
+    let exps: String = String::from(
+        "command,mean,stddev,median,user,system,min,max,parameter_bar,parameter_foo\n\
+        FOO=one BAR=two command | 1,1,2,1,3,4,5,6,two,one\n\
+        FOO=one BAR=seven command | 2,11,12,11,13,14,15,16.5,seven,one\n\
+        ",
+    );
+    let gens =
+        String::from_utf8(exporter.serialize(&results, Some(Unit::Second)).unwrap()).unwrap();
+
+    assert_eq!(exps, gens);
+}

src/export/json.rs

@@ -0,0 +1,27 @@
+use super::Exporter;
+use crate::benchmark_result::BenchmarkResult;
+use crate::units::Unit;
+
+use std::io::{Error, ErrorKind, Result};
+
+use serde::*;
+use serde_json::to_vec_pretty;
+
+#[derive(Serialize, Debug)]
+struct HyperfineSummary<'a> {
+    results: &'a [BenchmarkResult],
+}
+
+#[derive(Default)]
+pub struct JsonExporter {}
+
+impl Exporter for JsonExporter {
+    fn serialize(&self, results: &[BenchmarkResult], _unit: Option<Unit>) -> Result<Vec<u8>> {
+        let mut output = to_vec_pretty(&HyperfineSummary { results });
+        for content in output.iter_mut() {
+            content.push(b'\n');
+        }
+
+        output.map_err(|e| Error::new(ErrorKind::Other, e))
+    }
+}

src/export/markdown.rs

@@ -0,0 +1,293 @@
+use super::Exporter;
+
+use crate::benchmark_result::BenchmarkResult;
+use crate::format::format_duration_value;
+use crate::internal::{compute_relative_speed, BenchmarkResultWithRelativeSpeed};
+use crate::units::Unit;
+
+use std::io::{Error, ErrorKind, Result};
+
+#[derive(Default)]
+pub struct MarkdownExporter {}
+
+impl Exporter for MarkdownExporter {
+    fn serialize(&self, results: &[BenchmarkResult], unit: Option<Unit>) -> Result<Vec<u8>> {
+        let unit = if let Some(unit) = unit {
+            // Use the given unit for all entries.
+            unit
+        } else if let Some(first_result) = results.first() {
+            // Use the first BenchmarkResult entry to determine the unit for all entries.
+            format_duration_value(first_result.mean, None).1
+        } else {
+            // Default to `Second`.
+            Unit::Second
+        };
+
+        if let Some(annotated_results) = compute_relative_speed(results) {
+            let mut destination = start_table(unit);
+
+            for result in annotated_results {
+                add_table_row(&mut destination, &result, unit);
+            }
+
+            Ok(destination)
+        } else {
+            Err(Error::new(
+                ErrorKind::Other,
+                "Relative speed comparison is not available for Markdown export.",
+            ))
+        }
+    }
+}
+
+fn table_header(unit_short_name: String) -> String {
+    format!(
+        "| Command | Mean [{unit}] | Min [{unit}] | Max [{unit}] | Relative |\n|:---|---:|---:|---:|---:|\n",
+        unit = unit_short_name
+    )
+}
+
+fn start_table(unit: Unit) -> Vec<u8> {
+    table_header(unit.short_name()).bytes().collect()
+}
+
+fn add_table_row(dest: &mut Vec<u8>, entry: &BenchmarkResultWithRelativeSpeed, unit: Unit) {
+    let result = &entry.result;
+    let mean_str = format_duration_value(result.mean, Some(unit)).0;
+    let stddev_str = format_duration_value(result.stddev, Some(unit)).0;
+    let min_str = format_duration_value(result.min, Some(unit)).0;
+    let max_str = format_duration_value(result.max, Some(unit)).0;
+    let rel_str = format!("{:.2}", entry.relative_speed);
+    let rel_stddev_str = if entry.is_fastest {
+        "".into()
+    } else {
+        format!(" ± {:.2}", entry.relative_speed_stddev)
+    };
+
+    dest.extend(
+        format!(
+            "| `{command}` | {mean} ± {stddev} | {min} | {max} | {rel}{rel_stddev} |\n",
+            command = result.command.replace("|", "\\|"),
+            mean = mean_str,
+            stddev = stddev_str,
+            min = min_str,
+            max = max_str,
+            rel = rel_str,
+            rel_stddev = rel_stddev_str,
+        )
+        .as_bytes(),
+    );
+}
+
+/// Ensure the markdown output includes the table header and the multiple
+/// benchmark results as a table. The list of actual times is not included
+/// in the output.
+///
+/// This also demonstrates that the first entry's units (ms) are used to set
+/// the units for all entries when the time unit is not given.
+#[test]
+fn test_markdown_format_ms() {
+    use std::collections::BTreeMap;
+    let exporter = MarkdownExporter::default();
+
+    let mut timing_results = vec![];
+
+    timing_results.push(BenchmarkResult::new(
+        String::from("sleep 0.1"),
+        0.1057,                          // mean
+        0.0016,                          // std dev
+        0.1057,                          // median
+        0.0009,                          // user_mean
+        0.0011,                          // system_mean
+        0.1023,                          // min
+        0.1080,                          // max
+        vec![0.1, 0.1, 0.1],             // times
+        vec![Some(0), Some(0), Some(0)], // exit codes
+        BTreeMap::new(),                 // parameter
+    ));
+
+    timing_results.push(BenchmarkResult::new(
+        String::from("sleep 2"),
+        2.0050,                          // mean
+        0.0020,                          // std dev
+        2.0050,                          // median
+        0.0009,                          // user_mean
+        0.0012,                          // system_mean
+        2.0020,                          // min
+        2.0080,                          // max
+        vec![2.0, 2.0, 2.0],             // times
+        vec![Some(0), Some(0), Some(0)], // exit codes
+        BTreeMap::new(),                 // parameter
+    ));
+
+    let formatted = String::from_utf8(exporter.serialize(&timing_results, None).unwrap()).unwrap();
+
+    let formatted_expected = format!(
+        "{}\
+| `sleep 0.1` | 105.7 ± 1.6 | 102.3 | 108.0 | 1.00 |
+| `sleep 2` | 2005.0 ± 2.0 | 2002.0 | 2008.0 | 18.97 ± 0.29 |
+",
+        table_header("ms".to_string())
+    );
+
+    assert_eq!(formatted_expected, formatted);
+}
+
+/// This (again) demonstrates that the first entry's units (s) are used to set
+/// the units for all entries when the time unit is not given.
+#[test]
+fn test_markdown_format_s() {
+    use std::collections::BTreeMap;
+    let exporter = MarkdownExporter::default();
+
+    let mut timing_results = vec![];
+
+    timing_results.push(BenchmarkResult::new(
+        String::from("sleep 2"),
+        2.0050,                          // mean
+        0.0020,                          // std dev
+        2.0050,                          // median
+        0.0009,                          // user_mean
+        0.0012,                          // system_mean
+        2.0020,                          // min
+        2.0080,                          // max
+        vec![2.0, 2.0, 2.0],             // times
+        vec![Some(0), Some(0), Some(0)], // exit codes
+        BTreeMap::new(),                 // parameter
+    ));
+
+    timing_results.push(BenchmarkResult::new(
+        String::from("sleep 0.1"),
+        0.1057,                          // mean
+        0.0016,                          // std dev
+        0.1057,                          // median
+        0.0009,                          // user_mean
+        0.0011,                          // system_mean
+        0.1023,                          // min
+        0.1080,                          // max
+        vec![0.1, 0.1, 0.1],             // times
+        vec![Some(0), Some(0), Some(0)], // exit codes
+        BTreeMap::new(),                 // parameter
+    ));
+
+    let formatted = String::from_utf8(exporter.serialize(&timing_results, None).unwrap()).unwrap();
+
+    let formatted_expected = format!(
+        "{}\
+| `sleep 2` | 2.005 ± 0.002 | 2.002 | 2.008 | 18.97 ± 0.29 |
+| `sleep 0.1` | 0.106 ± 0.002 | 0.102 | 0.108 | 1.00 |
+",
+        table_header("s".to_string())
+    );
+
+    assert_eq!(formatted_expected, formatted);
+}
+
+/// The given time unit (s) is used to set the units for all entries.
+#[test]
+fn test_markdown_format_time_unit_s() {
+    use std::collections::BTreeMap;
+    let exporter = MarkdownExporter::default();
+
+    let mut timing_results = vec![];
+
+    timing_results.push(BenchmarkResult::new(
+        String::from("sleep 0.1"),
+        0.1057,                          // mean
+        0.0016,                          // std dev
+        0.1057,                          // median
+        0.0009,                          // user_mean
+        0.0011,                          // system_mean
+        0.1023,                          // min
+        0.1080,                          // max
+        vec![0.1, 0.1, 0.1],             // times
+        vec![Some(0), Some(0), Some(0)], // exit codes
+        BTreeMap::new(),                 // parameter
+    ));
+
+    timing_results.push(BenchmarkResult::new(
+        String::from("sleep 2"),
+        2.0050,                          // mean
+        0.0020,                          // std dev
+        2.0050,                          // median
+        0.0009,                          // user_mean
+        0.0012,                          // system_mean
+        2.0020,                          // min
+        2.0080,                          // max
+        vec![2.0, 2.0, 2.0],             // times
+        vec![Some(0), Some(0), Some(0)], // exit codes
+        BTreeMap::new(),                 // parameter
+    ));
+
+    let formatted = String::from_utf8(
+        exporter
+            .serialize(&timing_results, Some(Unit::Second))
+            .unwrap(),
+    )
+    .unwrap();
+
+    let formatted_expected = format!(
+        "{}\
+| `sleep 0.1` | 0.106 ± 0.002 | 0.102 | 0.108 | 1.00 |
+| `sleep 2` | 2.005 ± 0.002 | 2.002 | 2.008 | 18.97 ± 0.29 |
+",
+        table_header("s".to_string())
+    );
+
+    assert_eq!(formatted_expected, formatted);
+}
+
+/// This (again) demonstrates that the given time unit (ms) is used to set
+/// the units for all entries.
+#[test]
+fn test_markdown_format_time_unit_ms() {
+    use std::collections::BTreeMap;
+    let exporter = MarkdownExporter::default();
+
+    let mut timing_results = vec![];
+
+    timing_results.push(BenchmarkResult::new(
+        String::from("sleep 2"),
+        2.0050,                          // mean
+        0.0020,                          // std dev
+        2.0050,                          // median
+        0.0009,                          // user_mean
+        0.0012,                          // system_mean
+        2.0020,                          // min
+        2.0080,                          // max
+        vec![2.0, 2.0, 2.0],             // times
+        vec![Some(0), Some(0), Some(0)], // exit codes
+        BTreeMap::new(),                 // parameter
+    ));
+
+    timing_results.push(BenchmarkResult::new(
+        String::from("sleep 0.1"),
+        0.1057,                          // mean
+        0.0016,                          // std dev
+        0.1057,                          // median
+        0.0009,                          // user_mean
+        0.0011,                          // system_mean
+        0.1023,                          // min
+        0.1080,                          // max
+        vec![0.1, 0.1, 0.1],             // times
+        vec![Some(0), Some(0), Some(0)], // exit codes
+        BTreeMap::new(),                 // parameter
+    ));
+
+    let formatted = String::from_utf8(
+        exporter
+            .serialize(&timing_results, Some(Unit::MilliSecond))
+            .unwrap(),
+    )
+    .unwrap();
+
+    let formatted_expected = format!(
+        "{}\
+| `sleep 2` | 2005.0 ± 2.0 | 2002.0 | 2008.0 | 18.97 ± 0.29 |
+| `sleep 0.1` | 105.7 ± 1.6 | 102.3 | 108.0 | 1.00 |
+",
+        table_header("ms".to_string())
+    );
+
+    assert_eq!(formatted_expected, formatted);
+}

src/export/mod.rs

@@ -0,0 +1,89 @@
+mod asciidoc;
+mod csv;
+mod json;
+mod markdown;
+
+use self::asciidoc::AsciidocExporter;
+use self::csv::CsvExporter;
+use self::json::JsonExporter;
+use self::markdown::MarkdownExporter;
+
+use std::fs::{File, OpenOptions};
+use std::io::{Result, Write};
+
+use crate::benchmark_result::BenchmarkResult;
+use crate::units::Unit;
+
+/// The desired form of exporter to use for a given file.
+#[derive(Clone)]
+pub enum ExportType {
+    /// Asciidoc Table
+    Asciidoc,
+
+    /// CSV (comma separated values) format
+    Csv,
+
+    /// JSON format
+    Json,
+
+    /// Markdown table
+    Markdown,
+}
+
+/// Interface for different exporters.
+trait Exporter {
+    /// Export the given entries in the serialized form.
+    fn serialize(&self, results: &[BenchmarkResult], unit: Option<Unit>) -> Result<Vec<u8>>;
+}
+
+struct ExporterWithFilename {
+    exporter: Box<dyn Exporter>,
+    filename: String,
+}
+
+/// Handles the management of multiple file exporters.
+pub struct ExportManager {
+    exporters: Vec<ExporterWithFilename>,
+}
+
+impl ExportManager {
+    /// Create a new ExportManager
+    pub fn new() -> ExportManager {
+        ExportManager {
+            exporters: Vec::new(),
+        }
+    }
+
+    /// Add an additional exporter to the ExportManager
+    pub fn add_exporter(&mut self, export_type: ExportType, filename: &str) -> Result<()> {
+        let _ = File::create(filename)?;
+
+        let exporter: Box<dyn Exporter> = match export_type {
+            ExportType::Asciidoc => Box::new(AsciidocExporter::default()),
+            ExportType::Csv => Box::new(CsvExporter::default()),
+            ExportType::Json => Box::new(JsonExporter::default()),
+            ExportType::Markdown => Box::new(MarkdownExporter::default()),
+        };
+        self.exporters.push(ExporterWithFilename {
+            exporter,
+            filename: filename.to_string(),
+        });
+
+        Ok(())
+    }
+
+    /// Write the given results to all Exporters contained within this manager
+    pub fn write_results(&self, results: &[BenchmarkResult], unit: Option<Unit>) -> Result<()> {
+        for e in &self.exporters {
+            let file_content = e.exporter.serialize(results, unit)?;
+            write_to_file(&e.filename, &file_content)?;
+        }
+        Ok(())
+    }
+}
+
+/// Write the given content to a file with the specified name
+fn write_to_file(filename: &str, content: &[u8]) -> Result<()> {
+    let mut file = OpenOptions::new().write(true).open(filename)?;
+    file.write_all(content)
+}