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 (const: unstable) · 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 Eq for EnvelopeConfig

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 (const: unstable) · 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 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.