uqa-cli 0.6.1

usql: interactive REPL for UQA
Documentation
//
// Unified Query Algebra
//
// Copyright (c) 2023-2026 Cognica, Inc.
//

//! Tabular and expanded query-result rendering.

use super::{ColumnType, PathBuf, SQLResult, Value, Write, HISTORY_FILE};
use uqa_sql::{expr::EngineHook, SQLError};

pub(super) fn print_result(result: &SQLResult, out: &mut (impl Write + ?Sized)) {
    if let Err(error) = print_result_impl(result, None, out) {
        let _ = writeln!(out, "ERROR: {}", super::diagnostics::sql_error_text(&error));
    }
}

fn print_result_impl(
    result: &SQLResult,
    engine: Option<&dyn EngineHook>,
    out: &mut (impl Write + ?Sized),
) -> Result<(), SQLError> {
    let table = super::printing::DisplayTable::from_result(result, engine)?;
    let _ = write!(
        out,
        "{}",
        super::printing::PrintOptions::default().render_terminal(&table, false)
    );
    Ok(())
}

/// Emit rows in `PostgreSQL` `COPY TO STDOUT` text format.
#[cfg(test)]
fn print_result_copy_text(result: &SQLResult, out: &mut (impl Write + ?Sized)) {
    print_result_copy_text_impl(result, None, out).unwrap();
}

pub(super) fn print_result_copy_text_with_engine(
    result: &SQLResult,
    engine: &dyn EngineHook,
    out: &mut (impl Write + ?Sized),
) -> Result<(), SQLError> {
    print_result_copy_text_impl(result, Some(engine), out)
}

fn print_result_copy_text_impl(
    result: &SQLResult,
    engine: Option<&dyn EngineHook>,
    out: &mut (impl Write + ?Sized),
) -> Result<(), SQLError> {
    let columns: Vec<String> = if result.columns.is_empty() {
        let mut keys: std::collections::BTreeSet<&String> = std::collections::BTreeSet::new();
        for row in &result.rows {
            keys.extend(row.keys());
        }
        keys.into_iter().cloned().collect()
    } else {
        result.columns.clone()
    };
    for row_index in 0..result.rows.len() {
        let cells = columns
            .iter()
            .enumerate()
            .map(|(column_index, _)| {
                copy_text_cell_typed(
                    result.value_at(row_index, column_index),
                    result
                        .column_types
                        .get(column_index)
                        .and_then(Option::as_ref),
                    engine,
                )
            })
            .collect::<Result<Vec<_>, _>>()?;
        let _ = writeln!(out, "{}", cells.join("\t"));
    }
    Ok(())
}

#[cfg(test)]
fn copy_text_cell(value: Option<&Value>) -> String {
    copy_text_cell_typed(value, None, None).unwrap()
}

fn copy_text_cell_typed(
    value: Option<&Value>,
    ty: Option<&ColumnType>,
    engine: Option<&dyn EngineHook>,
) -> Result<String, SQLError> {
    let Some(value) = value.filter(|value| !matches!(value, Value::Null)) else {
        return Ok("\\N".to_string());
    };
    let text = match value {
        Value::Bool(true) => "t".to_string(),
        Value::Bool(false) => "f".to_string(),
        other => value_to_display_typed(Some(other), ty, engine)?,
    };
    let mut escaped = String::new();
    for character in text.chars() {
        match character {
            '\u{0008}' => escaped.push_str("\\b"),
            '\u{000c}' => escaped.push_str("\\f"),
            '\n' => escaped.push_str("\\n"),
            '\r' => escaped.push_str("\\r"),
            '\t' => escaped.push_str("\\t"),
            '\u{000b}' => escaped.push_str("\\v"),
            '\\' => escaped.push_str("\\\\"),
            other => escaped.push(other),
        }
    }
    Ok(escaped)
}

pub(super) fn value_to_display_typed(
    value: Option<&Value>,
    ty: Option<&ColumnType>,
    engine: Option<&dyn EngineHook>,
) -> Result<String, SQLError> {
    if let Some((value, ty)) = value.zip(ty) {
        if !matches!(value, Value::Null) {
            return uqa_sql::result::format_postgres_text(value, ty, engine);
        }
    }
    if let Some(value @ Value::LegacyVector(_)) = value {
        return uqa_sql::expr::vector_value_to_string(value)?
            .ok_or_else(|| SQLError::Internal("invalid vector display carrier".into()));
    }
    // Enum values display their current catalog labels, as the type's output function does.
    if let Some(value) = value.filter(|value| uqa_sql::expr::enums::contains_enum_carrier(value)) {
        return match ty {
            Some(ty) => uqa_sql::result::format_postgres_text(value, ty, engine),
            None => value_to_display(Some(&uqa_sql::expr::enums::render_enum_labels(
                engine.and_then(EngineHook::enum_labels),
                value,
            )?)),
        };
    }
    value_to_display(value)
}

pub(super) fn history_path() -> Option<PathBuf> {
    // Honour the Rust test override if present; otherwise mirror
    // legacy `usql` ~/.cognica/uqa/.usql_history default.
    if let Ok(custom) = std::env::var("UQA_HISTORY") {
        if !custom.is_empty() {
            return Some(PathBuf::from(custom));
        }
    }
    if let Ok(home) = std::env::var("HOME") {
        if !home.is_empty() {
            return Some(
                PathBuf::from(home)
                    .join(".cognica")
                    .join("uqa")
                    .join(HISTORY_FILE),
            );
        }
    }
    None
}

pub(super) fn value_to_display(v: Option<&Value>) -> Result<String, SQLError> {
    Ok(match v {
        Some(Value::Datum(datum)) => {
            return value_to_display(Some(&uqa_sql::expr::datums::read(datum)?))
        }
        Some(Value::Null) | None => "NULL".to_string(),
        Some(Value::Void) => String::new(),
        Some(Value::Bool(b)) => b.to_string(),
        Some(Value::Int(n)) => n.to_string(),
        Some(Value::Float(f)) => uqa_graph::agtype::format_float_pg(*f),
        Some(Value::Decimal(d)) => d.to_sql_string(),
        Some(Value::Str(s) | Value::FixedChar(s)) => s.clone(),
        // Typed result columns format labels through the engine catalog; an untyped carrier has no label source.
        Some(Value::Enum(value)) => return Err(uqa_sql::expr::catalog_output_required(value)),
        // PostgreSQL bytea hex output form.
        Some(Value::Bytes(b)) => {
            const HEX: &[u8; 16] = b"0123456789abcdef";
            let mut out = String::new();
            out.push_str("\\x");
            for byte in b {
                out.push(char::from(HEX[usize::from(byte >> 4)]));
                out.push(char::from(HEX[usize::from(byte & 0x0f)]));
            }
            out
        }
        Some(Value::Temporal(t)) => t.to_sql_string(),
        Some(Value::Json(text) | Value::JsonB(text)) => text.clone(),
        Some(Value::List(items)) => pg_array_display(items)?,
        Some(
            value @ (Value::BitString(_)
            | Value::Array(_)
            | Value::Row(_)
            | Value::Record(_)
            | Value::LegacyVector(_)),
        ) => uqa_sql::expr::value_to_string(value)?,
        // Maps come from JSON/JSONB values: render canonical JSON the
        // way psql prints jsonb, not a Rust-debug-ish map.
        Some(value @ Value::Map(_)) => json_value_display(value)?,
    })
}

/// `PostgreSQL` array-literal output: `{1,2,3}`, strings quoted when
/// they contain structural characters, `NULL` for nulls, booleans as
/// `t`/`f`, nested arrays recursive.
pub(super) fn pg_array_display(items: &[Value]) -> Result<String, SQLError> {
    fn element(v: &Value) -> Result<String, SQLError> {
        Ok(match v {
            Value::Null => "NULL".to_string(),
            Value::Bool(b) => if *b { "t" } else { "f" }.to_string(),
            Value::List(items) => pg_array_display(items)?,
            Value::Map(_) => json_value_display(v)?,
            other => {
                let s = value_to_display(Some(other))?;
                let needs_quotes = s.is_empty()
                    || s.eq_ignore_ascii_case("null")
                    || s.chars()
                        .any(|c| c.is_whitespace() || matches!(c, ',' | '{' | '}' | '"' | '\\'));
                if needs_quotes {
                    format!("\"{}\"", s.replace('\\', "\\\\").replace('"', "\\\""))
                } else {
                    s
                }
            }
        })
    }
    let inner: Vec<String> = items.iter().map(element).collect::<Result<_, _>>()?;
    Ok(format!("{{{}}}", inner.join(",")))
}

/// Canonical JSON rendering for JSON/JSONB values inside result
/// tables: quoted keys, `": "` and `", "` separators, JSON literals
/// for nested nulls - the same shape psql prints for `jsonb`.
pub(super) fn json_value_display(v: &Value) -> Result<String, SQLError> {
    Ok(match v {
        Value::Datum(datum) => return json_value_display(&uqa_sql::expr::datums::read(datum)?),
        Value::Null => "null".to_string(),
        Value::Void => serde_json::Value::String(String::new()).to_string(),
        Value::Bool(b) => b.to_string(),
        Value::Int(n) => n.to_string(),
        Value::Float(f) => uqa_graph::agtype::format_float_pg(*f),
        Value::Decimal(d) => d.to_sql_string(),
        Value::Str(s) | Value::FixedChar(s) => serde_json::Value::String(s.clone()).to_string(),
        Value::Bytes(_) | Value::Temporal(_) | Value::BitString(_) => {
            serde_json::Value::String(value_to_display(Some(v))?).to_string()
        }
        Value::Json(text) | Value::JsonB(text) => text.clone(),
        Value::Enum(value) => return Err(uqa_sql::expr::catalog_output_required(value)),
        Value::Array(array) => {
            let inner = array
                .elements()
                .iter()
                .map(json_value_display)
                .collect::<Result<Vec<_>, SQLError>>()?;
            format!("[{}]", inner.join(", "))
        }
        Value::LegacyVector(vector) => {
            let inner = vector
                .elements()
                .iter()
                .map(json_value_display)
                .collect::<Result<Vec<_>, SQLError>>()?;
            format!("[{}]", inner.join(", "))
        }
        Value::List(items) => {
            let inner = items
                .iter()
                .map(json_value_display)
                .collect::<Result<Vec<_>, SQLError>>()?;
            format!("[{}]", inner.join(", "))
        }
        Value::Row(items) => {
            let inner = items
                .iter()
                .map(json_value_display)
                .collect::<Result<Vec<_>, SQLError>>()?;
            format!("[{}]", inner.join(", "))
        }
        Value::Record(fields) => {
            let inner: Vec<String> = fields
                .iter()
                .map(|(key, value)| {
                    let key = serde_json::Value::String(key.clone()).to_string();
                    Ok(format!("{key}: {}", json_value_display(value)?))
                })
                .collect::<Result<_, SQLError>>()?;
            format!("{{{}}}", inner.join(", "))
        }
        Value::Map(m) => {
            let inner: Vec<String> = m
                .iter()
                .map(|(k, v)| {
                    let key = serde_json::Value::String(k.clone()).to_string();
                    Ok(format!("{key}: {}", json_value_display(v)?))
                })
                .collect::<Result<_, SQLError>>()?;
            format!("{{{}}}", inner.join(", "))
        }
    })
}

#[cfg(test)]
mod tests {
    use super::{
        copy_text_cell, print_result_copy_text, print_result_copy_text_with_engine,
        value_to_display,
    };
    use uqa_core::Value;
    use uqa_engine::Engine;
    use uqa_sql::{ColumnType, SQLResult};

    #[test]
    fn float_output_matches_postgresql_special_and_scientific_spelling() {
        assert_eq!(
            value_to_display(Some(&Value::Float(f64::NAN))).unwrap(),
            "NaN"
        );
        assert_eq!(
            value_to_display(Some(&Value::Float(f64::INFINITY))).unwrap(),
            "Infinity"
        );
        assert_eq!(
            value_to_display(Some(&Value::Float(f64::NEG_INFINITY))).unwrap(),
            "-Infinity"
        );
        assert_eq!(
            value_to_display(Some(&Value::Float(7.257_415_615_307_999e306))).unwrap(),
            "7.257415615307999e+306"
        );
    }

    #[test]
    fn copy_text_cells_distinguish_null_empty_and_literal_marker() {
        assert_eq!(copy_text_cell(Some(&Value::Null)), "\\N");
        assert_eq!(copy_text_cell(Some(&Value::Str(String::new()))), "");
        assert_eq!(copy_text_cell(Some(&Value::Str("\\N".into()))), "\\\\N");
        assert_eq!(
            copy_text_cell(Some(&Value::Str("a\tb\nc\\d".into()))),
            "a\\tb\\nc\\\\d"
        );
    }

    #[test]
    fn copy_text_uses_postgresql_legacy_vector_output() {
        let result = SQLResult::from_typed_rows_with_positions(
            vec!["proargtypes".into(), "indkey".into()],
            vec![Some(ColumnType::OidVector), Some(ColumnType::Int2Vector)],
            vec![std::collections::BTreeMap::new()],
            Some(vec![vec![
                Value::List(vec![Value::Int(23), Value::Int(25)]),
                Value::List(vec![Value::Int(1), Value::Int(3)]),
            ]]),
        );
        let mut output = Vec::new();
        print_result_copy_text(&result, &mut output);
        assert_eq!(String::from_utf8(output).unwrap(), "23 25\t1 3\n");
    }

    #[test]
    fn copy_text_uses_catalog_aware_regtype_output() {
        let engine = Engine::new();
        let result = engine
            .sql(
                "SELECT 0::regproc, 1598::regproc, 1259::regclass, 11::regnamespace, 23::regtype, ARRAY[0::regtype, 23::regtype, 999999::regtype]",
                &[],
            )
            .unwrap();
        let mut output = Vec::new();
        print_result_copy_text_with_engine(&result, &engine, &mut output).unwrap();
        assert_eq!(
            String::from_utf8(output).unwrap(),
            "-\tpg_catalog.random\tpg_class\tpg_catalog\tinteger\t{-,integer,999999}\n"
        );
    }
}