Skip to main content

EnvelopeConfig

scriba::envelope

Struct EnvelopeConfig 

Source 
pub struct EnvelopeConfig {
    pub mode: EnvelopeMode,
    pub layout: EnvelopeLayout,
    pub fields: EnvelopeFields,
    pub show_ok: bool,
    pub show_format: bool,
}
Expand description

Full configuration for JSON envelope wrapping.

When mode is EnvelopeMode::None (the default) nothing changes. Set mode to EnvelopeMode::Json to wrap rendered output in a JSON object.

§Examples

use scriba::envelope::{EnvelopeConfig, EnvelopeMode, EnvelopeLayout, EnvelopeFields};

let cfg = EnvelopeConfig::default()
    .with_mode(EnvelopeMode::Json)
    .with_layout(EnvelopeLayout::Nested)
    .with_show_ok(true)
    .with_show_format(true);

assert!(cfg.mode.is_json());
assert_eq!(cfg.layout, EnvelopeLayout::Nested);

Fields§

§mode: EnvelopeMode

Whether and how to wrap output.

§layout: EnvelopeLayout

Whether fields are at the top level or nested under meta_field.

§fields: EnvelopeFields

Customisable field names.

§show_ok: bool

Include the ok boolean field in the envelope (default: true).

§show_format: bool

Include the format string field in the envelope (default: true).

Implementations§

Source§

impl EnvelopeConfig

Source

pub fn with_mode(self, mode: EnvelopeMode) -> Self

Set the envelope mode.

Examples found in repository?
examples/envelope_nested.rs (line 36)
25fn main() -> scriba::Result<()> {
26    let output = Output::new()
27        .title("Pipeline")
28        .data("stage", "build")
29        .data("commit", "a3f9c12")
30        .paragraph("Build succeeded in 42s.");
31
32    let ui = Ui::new()
33        .with_format(Format::Json)
34        .with_envelope(
35            EnvelopeConfig::default()
36                .with_mode(EnvelopeMode::Json)
37                .with_layout(EnvelopeLayout::Nested),
38        );
39
40    println!("=== Nested envelope, no meta ===");
41    ui.print(&output)?;
42
43    println!("\n=== Nested envelope, with meta merged in ===");
44    let meta = Meta::default()
45        .with_dry_run(true)
46        .with_command("ci run".into())
47        .with_timestamp("2026-04-13T09:30:00Z".into())
48        .with_scope("ci".into())
49        .with_version("0.3.0".into());
50    ui.print_with_meta(&output, Some(&meta), true)?;
51
52    Ok(())
53}
More examples
Hide additional examples
examples/envelope_flat.rs (line 27)
16fn main() -> scriba::Result<()> {
17    let output = Output::new()
18        .title("Deployment")
19        .data("environment", "production")
20        .data("version", "1.4.2")
21        .paragraph("All services healthy.");
22
23    let ui = Ui::new()
24        .with_format(Format::Json)
25        .with_envelope(
26            EnvelopeConfig::default()
27                .with_mode(EnvelopeMode::Json)
28                .with_layout(EnvelopeLayout::Flat),
29        );
30
31    println!("=== Flat envelope, no meta ===");
32    ui.print(&output)?;
33
34    println!("\n=== Flat envelope, with meta ===");
35    let meta = Meta::default()
36        .with_dry_run(false)
37        .with_command("deploy".into())
38        .with_duration_ms(312)
39        .with_timestamp("2026-04-13T15:00:00Z".into());
40    ui.print_with_meta(&output, Some(&meta), true)?;
41
42    println!("\n=== Flat envelope, ok: false (error case) ===");
43    let error_output = Output::new()
44        .title("Deployment")
45        .paragraph("Health check failed on eu-west-1.");
46    ui.print_with_meta(&error_output, None, false)?;
47
48    Ok(())
49}
examples/envelope_meta.rs (line 40)
17fn main() -> scriba::Result<()> {
18    let output = Output::new()
19        .title("Release")
20        .data("tag", "v0.3.0")
21        .paragraph("Release pipeline completed.");
22
23    let meta = Meta::default()
24        .with_dry_run(false)
25        .with_command("release publish".into())
26        .with_duration_ms(4821)
27        .with_timestamp("2026-04-13T18:00:00Z".into())
28        .with_scope("production".into())
29        .with_version("0.3.0".into())
30        // Arbitrary extra fields — any serialisable value
31        .with_extra("region", "eu-west-1")
32        .with_extra("actor", "github-actions")
33        .with_extra("run_id", 9_981_234_u64);
34
35    println!("=== Full meta — flat layout ===");
36    let flat_ui = Ui::new()
37        .with_format(Format::Json)
38        .with_envelope(
39            EnvelopeConfig::default()
40                .with_mode(EnvelopeMode::Json)
41                .with_layout(EnvelopeLayout::Flat),
42        );
43    flat_ui.print_with_meta(&output, Some(&meta), true)?;
44
45    println!("\n=== Full meta — nested layout (all fields merged under meta) ===");
46    let nested_ui = Ui::new()
47        .with_format(Format::Json)
48        .with_envelope(
49            EnvelopeConfig::default()
50                .with_mode(EnvelopeMode::Json)
51                .with_layout(EnvelopeLayout::Nested),
52        );
53    nested_ui.print_with_meta(&output, Some(&meta), true)?;
54
55    println!("\n=== Meta with non-JSON output format (text rendered inside envelope) ===");
56    let text_ui = Ui::new()
57        .with_format(Format::Text)
58        .with_envelope(
59            EnvelopeConfig::default()
60                .with_mode(EnvelopeMode::Json)
61                .with_layout(EnvelopeLayout::Flat),
62        );
63    text_ui.print_with_meta(&output, Some(&meta), true)?;
64
65    Ok(())
66}
examples/envelope_custom_fields.rs (line 28)
17fn main() -> scriba::Result<()> {
18    let output = Output::new()
19        .title("Users")
20        .data("count", 42u64)
21        .paragraph("Query executed successfully.");
22
23    // --- Custom flat field names ---
24    let flat_ui = Ui::new()
25        .with_format(Format::Json)
26        .with_envelope(
27            EnvelopeConfig::default()
28                .with_mode(EnvelopeMode::Json)
29                .with_layout(EnvelopeLayout::Flat)
30                .with_fields(EnvelopeFields {
31                    ok_field: "success".into(),
32                    format_field: "type".into(),
33                    content_field: "result".into(),
34                    meta_field: "context".into(),
35                }),
36        );
37
38    println!("=== Custom field names, flat ===");
39    println!(r#"  fields: success / type / result / context"#);
40    flat_ui.print(&output)?;
41
42    // --- Custom nested field names ---
43    let nested_ui = Ui::new()
44        .with_format(Format::Json)
45        .with_envelope(
46            EnvelopeConfig::default()
47                .with_mode(EnvelopeMode::Json)
48                .with_layout(EnvelopeLayout::Nested)
49                .with_fields(EnvelopeFields {
50                    ok_field: "success".into(),
51                    format_field: "type".into(),
52                    content_field: "data".into(),
53                    meta_field: "header".into(),
54                }),
55        );
56
57    let meta = Meta::default()
58        .with_command("users list".into())
59        .with_extra("region", "eu-west-1");
60
61    println!("\n=== Custom field names, nested ===");
62    println!(r#"  fields: success / type / data / header"#);
63    nested_ui.print_with_meta(&output, Some(&meta), true)?;
64
65    // --- Omit ok and format fields entirely ---
66    let minimal_ui = Ui::new()
67        .with_format(Format::Json)
68        .with_envelope(
69            EnvelopeConfig::default()
70                .with_mode(EnvelopeMode::Json)
71                .with_show_ok(false)
72                .with_show_format(false),
73        );
74
75    println!("\n=== Envelope without ok or format fields ===");
76    minimal_ui.print(&output)?;
77
78    Ok(())
79}
Source

pub fn with_layout(self, layout: EnvelopeLayout) -> Self

Set the layout style.

Examples found in repository?
examples/envelope_nested.rs (line 37)
25fn main() -> scriba::Result<()> {
26    let output = Output::new()
27        .title("Pipeline")
28        .data("stage", "build")
29        .data("commit", "a3f9c12")
30        .paragraph("Build succeeded in 42s.");
31
32    let ui = Ui::new()
33        .with_format(Format::Json)
34        .with_envelope(
35            EnvelopeConfig::default()
36                .with_mode(EnvelopeMode::Json)
37                .with_layout(EnvelopeLayout::Nested),
38        );
39
40    println!("=== Nested envelope, no meta ===");
41    ui.print(&output)?;
42
43    println!("\n=== Nested envelope, with meta merged in ===");
44    let meta = Meta::default()
45        .with_dry_run(true)
46        .with_command("ci run".into())
47        .with_timestamp("2026-04-13T09:30:00Z".into())
48        .with_scope("ci".into())
49        .with_version("0.3.0".into());
50    ui.print_with_meta(&output, Some(&meta), true)?;
51
52    Ok(())
53}
More examples
Hide additional examples
examples/envelope_flat.rs (line 28)
16fn main() -> scriba::Result<()> {
17    let output = Output::new()
18        .title("Deployment")
19        .data("environment", "production")
20        .data("version", "1.4.2")
21        .paragraph("All services healthy.");
22
23    let ui = Ui::new()
24        .with_format(Format::Json)
25        .with_envelope(
26            EnvelopeConfig::default()
27                .with_mode(EnvelopeMode::Json)
28                .with_layout(EnvelopeLayout::Flat),
29        );
30
31    println!("=== Flat envelope, no meta ===");
32    ui.print(&output)?;
33
34    println!("\n=== Flat envelope, with meta ===");
35    let meta = Meta::default()
36        .with_dry_run(false)
37        .with_command("deploy".into())
38        .with_duration_ms(312)
39        .with_timestamp("2026-04-13T15:00:00Z".into());
40    ui.print_with_meta(&output, Some(&meta), true)?;
41
42    println!("\n=== Flat envelope, ok: false (error case) ===");
43    let error_output = Output::new()
44        .title("Deployment")
45        .paragraph("Health check failed on eu-west-1.");
46    ui.print_with_meta(&error_output, None, false)?;
47
48    Ok(())
49}
examples/envelope_meta.rs (line 41)
17fn main() -> scriba::Result<()> {
18    let output = Output::new()
19        .title("Release")
20        .data("tag", "v0.3.0")
21        .paragraph("Release pipeline completed.");
22
23    let meta = Meta::default()
24        .with_dry_run(false)
25        .with_command("release publish".into())
26        .with_duration_ms(4821)
27        .with_timestamp("2026-04-13T18:00:00Z".into())
28        .with_scope("production".into())
29        .with_version("0.3.0".into())
30        // Arbitrary extra fields — any serialisable value
31        .with_extra("region", "eu-west-1")
32        .with_extra("actor", "github-actions")
33        .with_extra("run_id", 9_981_234_u64);
34
35    println!("=== Full meta — flat layout ===");
36    let flat_ui = Ui::new()
37        .with_format(Format::Json)
38        .with_envelope(
39            EnvelopeConfig::default()
40                .with_mode(EnvelopeMode::Json)
41                .with_layout(EnvelopeLayout::Flat),
42        );
43    flat_ui.print_with_meta(&output, Some(&meta), true)?;
44
45    println!("\n=== Full meta — nested layout (all fields merged under meta) ===");
46    let nested_ui = Ui::new()
47        .with_format(Format::Json)
48        .with_envelope(
49            EnvelopeConfig::default()
50                .with_mode(EnvelopeMode::Json)
51                .with_layout(EnvelopeLayout::Nested),
52        );
53    nested_ui.print_with_meta(&output, Some(&meta), true)?;
54
55    println!("\n=== Meta with non-JSON output format (text rendered inside envelope) ===");
56    let text_ui = Ui::new()
57        .with_format(Format::Text)
58        .with_envelope(
59            EnvelopeConfig::default()
60                .with_mode(EnvelopeMode::Json)
61                .with_layout(EnvelopeLayout::Flat),
62        );
63    text_ui.print_with_meta(&output, Some(&meta), true)?;
64
65    Ok(())
66}
examples/envelope_custom_fields.rs (line 29)
17fn main() -> scriba::Result<()> {
18    let output = Output::new()
19        .title("Users")
20        .data("count", 42u64)
21        .paragraph("Query executed successfully.");
22
23    // --- Custom flat field names ---
24    let flat_ui = Ui::new()
25        .with_format(Format::Json)
26        .with_envelope(
27            EnvelopeConfig::default()
28                .with_mode(EnvelopeMode::Json)
29                .with_layout(EnvelopeLayout::Flat)
30                .with_fields(EnvelopeFields {
31                    ok_field: "success".into(),
32                    format_field: "type".into(),
33                    content_field: "result".into(),
34                    meta_field: "context".into(),
35                }),
36        );
37
38    println!("=== Custom field names, flat ===");
39    println!(r#"  fields: success / type / result / context"#);
40    flat_ui.print(&output)?;
41
42    // --- Custom nested field names ---
43    let nested_ui = Ui::new()
44        .with_format(Format::Json)
45        .with_envelope(
46            EnvelopeConfig::default()
47                .with_mode(EnvelopeMode::Json)
48                .with_layout(EnvelopeLayout::Nested)
49                .with_fields(EnvelopeFields {
50                    ok_field: "success".into(),
51                    format_field: "type".into(),
52                    content_field: "data".into(),
53                    meta_field: "header".into(),
54                }),
55        );
56
57    let meta = Meta::default()
58        .with_command("users list".into())
59        .with_extra("region", "eu-west-1");
60
61    println!("\n=== Custom field names, nested ===");
62    println!(r#"  fields: success / type / data / header"#);
63    nested_ui.print_with_meta(&output, Some(&meta), true)?;
64
65    // --- Omit ok and format fields entirely ---
66    let minimal_ui = Ui::new()
67        .with_format(Format::Json)
68        .with_envelope(
69            EnvelopeConfig::default()
70                .with_mode(EnvelopeMode::Json)
71                .with_show_ok(false)
72                .with_show_format(false),
73        );
74
75    println!("\n=== Envelope without ok or format fields ===");
76    minimal_ui.print(&output)?;
77
78    Ok(())
79}
Source

pub fn with_fields(self, fields: EnvelopeFields) -> Self

Set custom field names.

Examples found in repository?
examples/envelope_custom_fields.rs (lines 30-35)
17fn main() -> scriba::Result<()> {
18    let output = Output::new()
19        .title("Users")
20        .data("count", 42u64)
21        .paragraph("Query executed successfully.");
22
23    // --- Custom flat field names ---
24    let flat_ui = Ui::new()
25        .with_format(Format::Json)
26        .with_envelope(
27            EnvelopeConfig::default()
28                .with_mode(EnvelopeMode::Json)
29                .with_layout(EnvelopeLayout::Flat)
30                .with_fields(EnvelopeFields {
31                    ok_field: "success".into(),
32                    format_field: "type".into(),
33                    content_field: "result".into(),
34                    meta_field: "context".into(),
35                }),
36        );
37
38    println!("=== Custom field names, flat ===");
39    println!(r#"  fields: success / type / result / context"#);
40    flat_ui.print(&output)?;
41
42    // --- Custom nested field names ---
43    let nested_ui = Ui::new()
44        .with_format(Format::Json)
45        .with_envelope(
46            EnvelopeConfig::default()
47                .with_mode(EnvelopeMode::Json)
48                .with_layout(EnvelopeLayout::Nested)
49                .with_fields(EnvelopeFields {
50                    ok_field: "success".into(),
51                    format_field: "type".into(),
52                    content_field: "data".into(),
53                    meta_field: "header".into(),
54                }),
55        );
56
57    let meta = Meta::default()
58        .with_command("users list".into())
59        .with_extra("region", "eu-west-1");
60
61    println!("\n=== Custom field names, nested ===");
62    println!(r#"  fields: success / type / data / header"#);
63    nested_ui.print_with_meta(&output, Some(&meta), true)?;
64
65    // --- Omit ok and format fields entirely ---
66    let minimal_ui = Ui::new()
67        .with_format(Format::Json)
68        .with_envelope(
69            EnvelopeConfig::default()
70                .with_mode(EnvelopeMode::Json)
71                .with_show_ok(false)
72                .with_show_format(false),
73        );
74
75    println!("\n=== Envelope without ok or format fields ===");
76    minimal_ui.print(&output)?;
77
78    Ok(())
79}
Source

pub fn with_show_ok(self, show: bool) -> Self

Control whether the ok field is included.

Examples found in repository?
examples/envelope_custom_fields.rs (line 71)
17fn main() -> scriba::Result<()> {
18    let output = Output::new()
19        .title("Users")
20        .data("count", 42u64)
21        .paragraph("Query executed successfully.");
22
23    // --- Custom flat field names ---
24    let flat_ui = Ui::new()
25        .with_format(Format::Json)
26        .with_envelope(
27            EnvelopeConfig::default()
28                .with_mode(EnvelopeMode::Json)
29                .with_layout(EnvelopeLayout::Flat)
30                .with_fields(EnvelopeFields {
31                    ok_field: "success".into(),
32                    format_field: "type".into(),
33                    content_field: "result".into(),
34                    meta_field: "context".into(),
35                }),
36        );
37
38    println!("=== Custom field names, flat ===");
39    println!(r#"  fields: success / type / result / context"#);
40    flat_ui.print(&output)?;
41
42    // --- Custom nested field names ---
43    let nested_ui = Ui::new()
44        .with_format(Format::Json)
45        .with_envelope(
46            EnvelopeConfig::default()
47                .with_mode(EnvelopeMode::Json)
48                .with_layout(EnvelopeLayout::Nested)
49                .with_fields(EnvelopeFields {
50                    ok_field: "success".into(),
51                    format_field: "type".into(),
52                    content_field: "data".into(),
53                    meta_field: "header".into(),
54                }),
55        );
56
57    let meta = Meta::default()
58        .with_command("users list".into())
59        .with_extra("region", "eu-west-1");
60
61    println!("\n=== Custom field names, nested ===");
62    println!(r#"  fields: success / type / data / header"#);
63    nested_ui.print_with_meta(&output, Some(&meta), true)?;
64
65    // --- Omit ok and format fields entirely ---
66    let minimal_ui = Ui::new()
67        .with_format(Format::Json)
68        .with_envelope(
69            EnvelopeConfig::default()
70                .with_mode(EnvelopeMode::Json)
71                .with_show_ok(false)
72                .with_show_format(false),
73        );
74
75    println!("\n=== Envelope without ok or format fields ===");
76    minimal_ui.print(&output)?;
77
78    Ok(())
79}
Source

pub fn with_show_format(self, show: bool) -> Self

Control whether the format field is included.

Examples found in repository?
examples/envelope_custom_fields.rs (line 72)
17fn main() -> scriba::Result<()> {
18    let output = Output::new()
19        .title("Users")
20        .data("count", 42u64)
21        .paragraph("Query executed successfully.");
22
23    // --- Custom flat field names ---
24    let flat_ui = Ui::new()
25        .with_format(Format::Json)
26        .with_envelope(
27            EnvelopeConfig::default()
28                .with_mode(EnvelopeMode::Json)
29                .with_layout(EnvelopeLayout::Flat)
30                .with_fields(EnvelopeFields {
31                    ok_field: "success".into(),
32                    format_field: "type".into(),
33                    content_field: "result".into(),
34                    meta_field: "context".into(),
35                }),
36        );
37
38    println!("=== Custom field names, flat ===");
39    println!(r#"  fields: success / type / result / context"#);
40    flat_ui.print(&output)?;
41
42    // --- Custom nested field names ---
43    let nested_ui = Ui::new()
44        .with_format(Format::Json)
45        .with_envelope(
46            EnvelopeConfig::default()
47                .with_mode(EnvelopeMode::Json)
48                .with_layout(EnvelopeLayout::Nested)
49                .with_fields(EnvelopeFields {
50                    ok_field: "success".into(),
51                    format_field: "type".into(),
52                    content_field: "data".into(),
53                    meta_field: "header".into(),
54                }),
55        );
56
57    let meta = Meta::default()
58        .with_command("users list".into())
59        .with_extra("region", "eu-west-1");
60
61    println!("\n=== Custom field names, nested ===");
62    println!(r#"  fields: success / type / data / header"#);
63    nested_ui.print_with_meta(&output, Some(&meta), true)?;
64
65    // --- Omit ok and format fields entirely ---
66    let minimal_ui = Ui::new()
67        .with_format(Format::Json)
68        .with_envelope(
69            EnvelopeConfig::default()
70                .with_mode(EnvelopeMode::Json)
71                .with_show_ok(false)
72                .with_show_format(false),
73        );
74
75    println!("\n=== Envelope without ok or format fields ===");
76    minimal_ui.print(&output)?;
77
78    Ok(())
79}

Trait Implementations§

Source§

impl Clone for EnvelopeConfig

Source§

fn clone(&self) -> EnvelopeConfig

Returns a duplicate of the value. Read more
1.0.0 · Source§

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

Performs copy-assignment from source. Read more
Source§

impl Debug for EnvelopeConfig

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Default for EnvelopeConfig

Source§

fn default() -> Self

Returns the “default value” for a type. Read more
Source§

impl PartialEq for EnvelopeConfig

Source§

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

Tests for self and other values to be equal, and is used by ==.
1.0.0 · Source§

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

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

impl Eq for EnvelopeConfig

Source§

impl StructuralPartialEq for EnvelopeConfig

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.