mariadb-cli 0.1.1

One-shot agent-native command line client for MariaDB servers
Documentation
//! Tab separated values, with the escaping written down.
//!
//! A separated shape is only useful if the rules are stated, because a value
//! containing the separator otherwise silently becomes two values. The rules
//! here are fixed:
//!
//! * A backslash inside a value becomes two backslashes. This is done first,
//!   so the escapes below can never be confused with content that already
//!   looked like one.
//! * A tab becomes backslash `t`, a line feed backslash `n` and a carriage
//!   return backslash `r`. None of the three ever reaches the channel raw, so
//!   a row is always exactly one line and a value is never split.
//! * Absence of value is the two characters backslash `N`. A value that really
//!   held that text would have arrived as backslash backslash `N`, so absence
//!   and empty text are told apart, and neither is confused with content.
//! * The first line is the column names, escaped by the same rules.
//!
//! A structure is written as its compact document form and then escaped, so a
//! nested value never breaks the row it sits in.

use super::{emit_line, to_compact, Formatter, END_OF_STREAM_KEY};
use crate::error::Result;
use crate::output::envelope::{Envelope, Row};
use serde_json::Value;
use std::io::Write;

/// The marker that stands for absence of value.
pub const ABSENT: &str = r"\N";

/// The tab separated shape.
#[derive(Debug, Default)]
pub struct Tsv {
    /// Whether the header line has already been written.
    wrote_header: bool,
}

impl Formatter for Tsv {
    fn name(&self) -> &'static str {
        "tsv"
    }

    fn write_envelope(&mut self, writer: &mut dyn Write, envelope: &Envelope) -> Result<()> {
        let Some(key) = envelope.payload_array_key() else {
            return self.write_field_table(writer, &envelope.data);
        };
        let Some(elements) = envelope.data.get(key).and_then(Value::as_array) else {
            return self.write_field_table(writer, &envelope.data);
        };
        let columns = super::column_names(elements);
        self.write_header(writer, &columns)?;
        let mut line = String::new();
        for element in elements {
            line.clear();
            join(
                &mut line,
                columns.iter().map(|name| cell(element.get(name))),
            );
            emit_line(writer, &line)?;
        }
        Ok(())
    }

    fn begin_stream(
        &mut self,
        writer: &mut dyn Write,
        _head: &Envelope,
        columns: &[String],
    ) -> Result<()> {
        self.wrote_header = false;
        self.write_header(writer, columns)
    }

    fn write_row(&mut self, writer: &mut dyn Write, row: &Row, line: &mut String) -> Result<()> {
        line.clear();
        join(line, row.values().map(|value| cell(Some(value))));
        emit_line(writer, line)
    }

    fn end_stream(
        &mut self,
        writer: &mut dyn Write,
        tail: &Envelope,
        emitted: u64,
        gaps: &[crate::output::envelope::Gap],
        // Read for one thing only: whether the set was cut. What the pipeline
        // did in full belongs to the shape that has room for an object, and
        // this one still has to avoid claiming a cut set is whole.
        applied: Option<&crate::output::envelope::Applied>,
    ) -> Result<()> {
        // FR-132, by the same argument the line-per-row shape makes: the
        // closing record IS the statement that the set is whole, so writing it
        // after the volume ceiling cut the answer states something false.
        //
        // This shape used to write it anyway, on the grounds that it has no
        // room for the pipeline's report. That confused two different things:
        // reporting WHAT was dropped needs an object, and declining to claim
        // completeness needs nothing at all.
        if applied.is_some_and(|applied| applied.output_truncated) {
            return Ok(());
        }

        // The fourth cell is always written, and a flow that left nothing out
        // fills it with the marker this shape reserves for absence. An empty
        // cell would say the flow declared a gap whose cause was empty text,
        // which is a different claim from declaring no gap at all, and telling
        // those two apart is the whole reason the marker exists.
        let causes = super::causes_of(gaps);
        let declared = if causes.is_empty() {
            ABSENT.to_owned()
        } else {
            escape(&causes)
        };
        // The fifth cell carries the destination (FR-143). This shape has no
        // room for an object, so it arrives as text, and a flow that reached no
        // destination fills the cell with the same marker for absence rather
        // than inventing a second convention for it.
        let destination =
            super::destination_of(tail).map_or_else(|| ABSENT.to_owned(), |text| escape(&text));
        emit_line(
            writer,
            &format!("{ABSENT}\t{END_OF_STREAM_KEY}\t{emitted}\t{declared}\t{destination}"),
        )
    }
}

impl Tsv {
    /// Writes the column names, once.
    fn write_header(&mut self, writer: &mut dyn Write, columns: &[String]) -> Result<()> {
        if self.wrote_header || columns.is_empty() {
            return Ok(());
        }
        self.wrote_header = true;
        let mut line = String::new();
        join(&mut line, columns.iter().map(|name| escape(name)));
        emit_line(writer, &line)
    }

    /// Writes a payload that carries no rows as a table of its own fields.
    fn write_field_table(&mut self, writer: &mut dyn Write, payload: &Value) -> Result<()> {
        let names = vec!["key".to_owned(), "value".to_owned()];
        self.write_header(writer, &names)?;
        let Some(fields) = payload.as_object() else {
            return emit_line(writer, &cell(Some(payload)));
        };
        for (name, value) in fields {
            emit_line(writer, &format!("{}\t{}", escape(name), cell(Some(value))))?;
        }
        Ok(())
    }
}

/// Joins already-escaped cells with the separator.
fn join(line: &mut String, cells: impl Iterator<Item = String>) {
    for (index, text) in cells.enumerate() {
        if index > 0 {
            line.push('\t');
        }
        line.push_str(&text);
    }
}

/// Renders one cell, telling absence from empty text.
fn cell(value: Option<&Value>) -> String {
    match value {
        None | Some(Value::Null) => ABSENT.to_owned(),
        Some(Value::String(text)) => escape(text),
        Some(other) => escape(&to_compact(other).unwrap_or_else(|_| other.to_string())),
    }
}

/// Applies the escaping rules stated at the top of this file.
#[must_use]
pub fn escape(text: &str) -> String {
    let mut escaped = String::with_capacity(text.len());
    for character in text.chars() {
        match character {
            '\\' => escaped.push_str(r"\\"),
            '\t' => escaped.push_str(r"\t"),
            '\n' => escaped.push_str(r"\n"),
            '\r' => escaped.push_str(r"\r"),
            other => escaped.push(other),
        }
    }
    escaped
}

#[cfg(test)]
mod tests {
    use super::super::tests::{
        bare_tail, sample_row, stream_through, stream_through_from, tail_from_a_destination,
    };
    use super::*;
    use indexmap::IndexMap;
    use serde_json::json;

    #[test]
    fn a_separator_inside_a_value_is_escaped_and_never_splits_the_row() {
        assert_eq!(escape("a\tb"), r"a\tb");
        let mut row = IndexMap::new();
        row.insert("text".to_owned(), json!("a\tb"));
        let mut out = Vec::new();
        let mut line = String::new();
        Tsv::default()
            .write_row(&mut out, &row, &mut line)
            .expect("writes");
        let text = String::from_utf8(out).expect("utf8");
        assert_eq!(text, "a\\tb\n");
        assert_eq!(text.trim_end().split('\t').count(), 1, "one cell, not two");
    }

    #[test]
    fn a_line_break_inside_a_value_is_escaped_and_never_splits_the_line() {
        let mut row = IndexMap::new();
        row.insert("text".to_owned(), json!("first\nsecond\rthird"));
        let mut out = Vec::new();
        let mut line = String::new();
        Tsv::default()
            .write_row(&mut out, &row, &mut line)
            .expect("writes");
        let text = String::from_utf8(out).expect("utf8");
        assert_eq!(text, "first\\nsecond\\rthird\n");
        assert_eq!(text.lines().count(), 1, "one row is one line");
    }

    #[test]
    fn the_escape_character_itself_is_escaped_first() {
        assert_eq!(escape(r"\N"), r"\\N");
        assert_ne!(escape(r"\N"), ABSENT, "content must not be read as absence");
    }

    #[test]
    fn absence_is_told_apart_from_empty_text() {
        assert_eq!(cell(Some(&Value::Null)), ABSENT);
        assert_eq!(cell(Some(&json!(""))), "");
        assert_ne!(cell(Some(&Value::Null)), cell(Some(&json!(""))));
    }

    #[test]
    fn the_first_line_names_the_columns() {
        let rows = vec![sample_row("alpha", 1), sample_row("beta", 2)];
        let text = stream_through(&mut Tsv::default(), &rows);
        let mut lines = text.lines();
        assert_eq!(lines.next(), Some("name\tsize"));
        assert_eq!(lines.next(), Some("alpha\t1"));
        assert_eq!(lines.next(), Some("beta\t2"));
    }

    #[test]
    fn a_whole_flow_ends_with_the_record_that_declares_the_count() {
        let rows = vec![sample_row("alpha", 1)];
        let text = stream_through(&mut Tsv::default(), &rows);
        let last = text.lines().next_back().expect("a last line");
        assert_eq!(last, "\\N\tend_of_stream\t1\t\\N\t\\N");
    }

    /// The closing record carries the destination in a cell of its own, and
    /// marks its absence with the marker this shape already reserves (FR-143).
    #[test]
    fn the_closing_record_declares_the_destination_in_its_own_cell() {
        let rows = vec![sample_row("alpha", 1)];
        let served = stream_through_from(&mut Tsv::default(), &rows, &tail_from_a_destination());
        let last = served.lines().next_back().expect("a last line");
        assert_eq!(
            last,
            "\\N\tend_of_stream\t1\t\\N\tproducao@192.0.2.10:3306/loja"
        );

        let bare = stream_through(&mut Tsv::default(), &rows);
        let unserved = bare.lines().next_back().expect("a last line");
        assert_eq!(
            unserved.split('\t').next_back(),
            Some(ABSENT),
            "an undeclared destination uses the marker for absence: {unserved}"
        );
    }

    /// A flow this tool decided to end declares why in the closing record, and
    /// a flow that left nothing out fills the same cell with the marker for
    /// absence. An empty cell there would claim a gap whose cause is empty
    /// text, and this shape tells absence and empty text apart on purpose.
    #[test]
    fn the_closing_record_declares_a_gap_and_marks_its_absence() {
        let mut out = Vec::new();
        let mut formatter = Tsv::default();
        formatter
            .begin_stream(&mut out, &bare_tail(), &[])
            .expect("opens");
        formatter
            .end_stream(
                &mut out,
                &bare_tail(),
                7,
                &[crate::output::envelope::Gap::new(
                    "rows",
                    "row_ceiling",
                    "the ceiling was reached",
                )],
                None,
            )
            .expect("closes");
        let text = String::from_utf8(out).expect("utf8");
        assert_eq!(text.trim_end(), "\\N\tend_of_stream\t7\trow_ceiling\t\\N");
        assert!(
            !text.contains("\t\n"),
            "absence is never an empty cell: {text}"
        );
    }

    #[test]
    fn a_structure_is_written_as_one_escaped_cell() {
        let nested = json!({"a": 1});
        let rendered = cell(Some(&nested));
        assert!(!rendered.contains('\t'));
        assert_eq!(rendered, r#"{"a":1}"#);
    }
}