API Reference#

Links to detailed API documentation and developer resources.

Rustdoc Documentation#

The complete API documentation is available in the rustdoc section of this site.

Public API Overview#

Core Functions#

• rows_to_strings() - Convert database rows to string vectors (delegates to TypeTransformer internally)
• get_extension_from_filename() - Extract file extensions for format detection

TypeTransformer#

• TypeTransformer - Canonical hub for safe MySQL value conversion

Associated Functions#

• TypeTransformer::value_to_string() - Convert mysql::Value to String for CSV/TSV output. Returns error for invalid date/time values.
• TypeTransformer::value_to_json() - Convert mysql::Value to serde_json::Value for JSON output. Returns error for invalid date/time values.
• TypeTransformer::row_to_strings() - Convert entire row to vector of strings.
• TypeTransformer::row_to_json() - Convert entire row to JSON object with deterministic key ordering (BTreeMap).

Output Modules#

• csv::write() - CSV output generation
• json::write() - JSON output generation
• json::write_typed() - JSON output with native type conversion (requires json feature)
• tab::write() - TSV output generation

CLI Interface#

• cli::Cli - Command-line argument structure
• cli::Commands - Available subcommands

Usage Examples#

Basic Library Usage#

use gold_digger::{csv, rows_to_strings};
use mysql::{Pool, Row};
use std::fs::File;

fn example() -> anyhow::Result<()> {
    // Convert database rows and write CSV
    let rows: Vec<Row> = vec![]; // query results would go here
    let string_rows = rows_to_strings(rows)?;
    let output = File::create("output.csv")?;
    csv::write(string_rows, output)?;
    Ok(())
}

Using TypeTransformer for Value Conversion#

use gold_digger::TypeTransformer;
use mysql::Value;

fn convert_value(value: &Value) -> anyhow::Result<()> {
    // Convert to string for CSV/TSV output
    let s = TypeTransformer::value_to_string(value)?;
    println!("String: {}", s);

    // Convert to JSON value
    let json = TypeTransformer::value_to_json(value)?;
    println!("JSON: {}", serde_json::to_string(&json)?);

    Ok(())
}

Using JSON with Native Types#

#[cfg(feature = "json")]
use gold_digger::write_typed;
use mysql::{Pool, Row};
use std::fs::File;

fn example_json() -> anyhow::Result<()> {
    let rows: Vec<Row> = vec![]; // query results
    let output = File::create("output.json")?;
    write_typed(rows, output, false)?;
    Ok(())
}

Custom Format Implementation#

use anyhow::Result;
use std::io::Write;

pub fn write<W: Write>(rows: Vec<Vec<String>>, mut output: W) -> Result<()> {
    for row in rows {
        writeln!(output, "{}", row.join("|"))?;
    }
    Ok(())
}

Type Definitions#

Key types used throughout the codebase:

• Vec<Vec<String>> - Standard row format for output modules
• anyhow::Result<T> - Error handling pattern
• mysql::Row - Database result row type
• mysql::Value - MySQL value type (used by TypeTransformer)
• serde_json::Value - JSON value type (output of TypeTransformer::value_to_json)
• BTreeMap<String, serde_json::Value> - JSON object with deterministic key ordering (output of TypeTransformer::row_to_json)

Safety Guarantees#

TypeTransformer provides the following safety guarantees for MySQL value conversion:

• NULL handling: NULL values convert to empty strings (CSV/TSV) or serde_json::Value::Null (JSON)
• Invalid UTF-8: Binary data that is not valid UTF-8 is hex-encoded instead of causing panics (e.g., 0xfffefd)
• Special floats: NaN and Infinity values are represented as strings ("NaN", "Infinity", "-Infinity")
• Date/time validation: Date and time components are validated before formatting; invalid values return errors for both value_to_string and value_to_json
• Deterministic output: JSON objects use BTreeMap for alphabetical key ordering

Error Handling#

All public functions return anyhow::Result<T> for consistent error handling:

use anyhow::Result;

fn example_function() -> Result<()> {
    // Function implementation
    Ok(())
}

Feature Flags#

Conditional compilation based on Cargo features:

#[cfg(feature = "csv")]
pub mod csv;

#[cfg(feature = "json")]
pub mod json;

#[cfg(feature = "verbose")]
println!("Debug information");