Struct OutputData 

#[non_exhaustive]
pub struct OutputData {
    pub headers: Option<Vec<String>>,
    pub root: Vec<OutputNode>,
    pub rich_json: Option<Value>,
}

Structured output data from a command.

This is the top-level structure for command output. It contains optional column headers and a list of root nodes.

headers is Option<Vec> because None means “not tabular” while Some(vec![]) means “tabular with no column headers.” The rendering dispatch in to_json() and the REPL formatter branch on this distinction.

Rendering Rules

Structure	Interactive	Piped/Model
Single node with text	Print text	Print text
Flat nodes, name only	Multi-column, colored	One per line
Flat nodes with cells	Aligned table	TSV or names only
Nested children	Box-drawing tree	Brace notation

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

headers: Option<Vec<String>>

Column headers (optional, for table output).

root: Vec<OutputNode>

Top-level nodes.

rich_json: Option<Value>

Render-only override for --json consumers. When Some, to_json() returns this verbatim instead of inferring from headers / root / cells. Use it when a builtin wants its --json shape to be richer than the table form (e.g. grep emitting per-match objects with submatches and byte offsets).

Skipped by serde (and thus by postcard / bincode) — this is a transient render hint, not part of the persisted shape.

Implementations

impl OutputData

pub fn new() -> Self

Create new empty output data.

pub fn text(content: impl Into<String>) -> Self

Create output data with a single text node.

This is the simplest form for commands like echo.

pub fn nodes(nodes: Vec<OutputNode>) -> Self

Create output data with named nodes (for ls, etc.).

pub fn table(headers: Vec<String>, nodes: Vec<OutputNode>) -> Self

Create output data with headers and nodes (for ls -l, ps, etc.).

pub fn with_headers(self, headers: Vec<String>) -> Self

Set column headers.

pub fn with_rich_json(self, value: Value) -> Self

Attach a render-only --json override. See rich_json field doc.

pub fn is_simple_text(&self) -> bool

Check if this output is simple text (single text-only node).

pub fn is_flat(&self) -> bool

Check if this output is a flat list (no nested children).

pub fn is_tabular(&self) -> bool

Check if this output has tabular data (nodes with cells).

pub fn as_text(&self) -> Option<&str>

Get the text content if this is simple text output.

pub fn into_text(self) -> Result<String, Self>

Extract the owned String from a single-text-node OutputData. Returns Err(self) for non-simple-text output (tables, trees, multi-node), giving the caller back the unconsumed OutputData.

pub fn estimated_byte_size(&self) -> usize

Estimate canonical string byte size without materializing.

Lower bound — actual may be slightly larger due to formatting. Mirrors to_canonical_string() structure but only accumulates sizes.

pub fn write_canonical( &self, w: &mut dyn Write, budget: Option<usize>, ) -> Result<usize>

Write canonical representation to a writer with optional byte budget.

Returns total bytes written. Stops after budget exceeded (imprecise: one write past the limit is fine — caller uses this for spill detection, not for exact truncation).

pub fn to_canonical_string(&self) -> String

Convert to canonical string output (for pipes).

This produces a simple string representation suitable for piping to other commands:

• Text nodes: their text content
• Named nodes: names joined by newlines
• Tabular nodes (name + cells): TSV format (name\tcell1\tcell2…)
• Nested nodes: brace notation

pub fn to_json(&self) -> Value

Serialize to a JSON value for --json flag handling.

Bare data, no envelope — optimized for jq patterns.

Structure	JSON
Simple text	"hello world"
Flat list (names only)	["file1", "file2"]
Table (headers + cells)	[{"col1": "v1", ...}, ...]
Tree (nested children)	{"dir": {"file": null}}

Trait Implementations

impl Clone for OutputData

fn clone(&self) -> OutputData

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for OutputData

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for OutputData

fn default() -> OutputData

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for OutputData

where OutputData: Default,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for OutputData

impl PartialEq for OutputData

fn eq(&self, other: &OutputData) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for OutputData

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for OutputData