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;
pub const ABSENT: &str = r"\N";
#[derive(Debug, Default)]
pub struct Tsv {
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],
applied: Option<&crate::output::envelope::Applied>,
) -> Result<()> {
if applied.is_some_and(|applied| applied.output_truncated) {
return Ok(());
}
let causes = super::causes_of(gaps);
let declared = if causes.is_empty() {
ABSENT.to_owned()
} else {
escape(&causes)
};
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 {
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)
}
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(())
}
}
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);
}
}
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())),
}
}
#[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");
}
#[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}"
);
}
#[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}"#);
}
}