Add Asciidoc export option

Signed-off-by: Chloe Kudryavtsev <toast@toastin.space>

src/hyperfine/app.rs

@@ -146,6 +146,13 @@ fn build_app() -> App<'static, 'static> {
                 .possible_values(&["millisecond", "second"])
                 .help("Set the time unit used. Possible values: millisecond, second."),
         )
+        .arg(
+            Arg::with_name("export-asciidoc")
+                .long("export-asciidoc")
+                .takes_value(true)
+                .value_name("FILE")
+                .help("Export the timing summary statistics as an Asciidoc table to the given FILE."),
+        )
         .arg(
             Arg::with_name("export-csv")
                 .long("export-csv")

src/hyperfine/export/asciidoc.rs

@@ -0,0 +1,207 @@
+use super::Exporter;
+
+use hyperfine::format::format_duration_value;
+use hyperfine::types::BenchmarkResult;
+use hyperfine::units::Unit;
+
+use std::io::Result;
+
+#[derive(Default)]
+pub struct AsciidocExporter {}
+
+impl Exporter for AsciidocExporter {
+    fn serialize(&self, results: &Vec<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('\n' as u8);
+            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() {
+    let result = BenchmarkResult::new(
+        String::from("sleep 1"), // command
+        0.10491992406666667,     // mean
+        0.00397851689425097,     // stddev
+        0.005182013333333333,    // user
+        0.0,                     // system
+        0.1003342584,            // min
+        0.10745223440000001,     // max
+        vec![                    // times
+            0.1003342584,
+            0.10745223440000001,
+            0.10697327940000001
+        ],
+        None                     // 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() {
+    let result = BenchmarkResult::new(
+        String::from("sleep 1|"), // command
+        0.10491992406666667,      // mean
+        0.00397851689425097,      // stddev
+        0.005182013333333333,     // user
+        0.0,                      // system
+        0.1003342584,             // min
+        0.10745223440000001,      // max
+        vec![                     // times
+            0.1003342584,
+            0.10745223440000001,
+            0.10697327940000001
+        ],
+        None                      // 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() {
+    let exporter = AsciidocExporter::default();
+    // NOTE: results are fabricated, unlike above
+    let results = vec![
+        BenchmarkResult::new(
+            String::from("command | 1"),
+            1.0,
+            2.0,
+            3.0,
+            4.0,
+            5.0,
+            6.0,
+            vec![
+                7.0,
+                8.0,
+                9.0
+            ],
+            None
+        ),
+        BenchmarkResult::new(
+            String::from("command | 2"),
+            11.0,
+            12.0,
+            13.0,
+            14.0,
+            15.0,
+            16.0,
+            vec![
+                17.0,
+                18.0,
+                19.0
+            ],
+            None
+        )
+    ];
+    // 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\
+         | `command \\| 1`\n\
+         | 1.000 ± 2.000\n\
+         | 5.000…6.000\n\
+         \n\
+         | `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/hyperfine/export/mod.rs

@@ -1,7 +1,9 @@
+mod asciidoc;
 mod csv;
 mod json;
 mod markdown;
 
+use self::asciidoc::AsciidocExporter;
 use self::csv::CsvExporter;
 use self::json::JsonExporter;
 use self::markdown::MarkdownExporter;
@@ -15,6 +17,9 @@ use hyperfine::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,
 
@@ -52,6 +57,7 @@ impl ExportManager {
     /// Add an additional exporter to the ExportManager
     pub fn add_exporter(&mut self, export_type: ExportType, filename: &str) {
         let exporter: Box<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()),

src/main.rs

@@ -216,6 +216,9 @@ fn build_hyperfine_options(matches: &ArgMatches) -> Result<HyperfineOptions, Opt
 /// in the given ArgMatches
 fn build_export_manager(matches: &ArgMatches) -> ExportManager {
     let mut export_manager = ExportManager::new();
+    if let Some(filename) = matches.value_of("export-asciidoc") {
+        export_manager.add_exporter(ExportType::Asciidoc, filename);
+    }
     if let Some(filename) = matches.value_of("export-json") {
         export_manager.add_exporter(ExportType::Json, filename);
     }