Struct Meta

Source

pub struct Meta {
    pub dry_run: Option<bool>,
    pub command: Option<String>,
    pub duration_ms: Option<u64>,
    pub timestamp: Option<String>,
    pub scope: Option<String>,
    pub version: Option<String>,
    pub extra: BTreeMap<String, Value>,
}

Expand description

Optional metadata to include inside a JSON envelope.

All fields are optional and serialised only when Some. Add arbitrary additional key-value pairs via extra.

§Examples

use scriba::envelope::Meta;

let meta = Meta::default()
    .with_dry_run(true)
    .with_command("deploy".into())
    .with_extra("region", "eu-west-1");

assert_eq!(meta.dry_run, Some(true));

Fields§

§dry_run: Option<bool>

Whether the operation was a dry run.

§command: Option<String>

The command that produced this output.

§duration_ms: Option<u64>

Execution duration in milliseconds.

§timestamp: Option<String>

RFC 3339 timestamp.

§scope: Option<String>

Logical scope or context label.

§version: Option<String>

Library/CLI version string.

§extra: BTreeMap<String, Value>

Additional arbitrary key-value pairs.

Implementations§

Source §

impl Meta

Source

pub fn with_dry_run(self, value: bool) -> Self

Set the dry_run flag.

Examples found in repository ?

examples/envelope_nested.rs (line 45)

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 36)

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 24)

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}

Source

pub fn with_command(self, value: String) -> Self

Set the command field.

Examples found in repository ?

examples/envelope_nested.rs (line 46)

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 37)

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 25)

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 58)

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_duration_ms(self, ms: u64) -> Self

Set the duration_ms field.

Examples found in repository ?

examples/envelope_flat.rs (line 38)

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}

More examples

Hide additional examples

examples/envelope_meta.rs (line 26)

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}

Source

pub fn with_timestamp(self, ts: String) -> Self

Set the timestamp field.

Examples found in repository ?

examples/envelope_nested.rs (line 47)

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 39)

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 27)

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}

Source

pub fn with_scope(self, scope: String) -> Self

Set the scope field.

Examples found in repository ?

examples/envelope_nested.rs (line 48)

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_meta.rs (line 28)

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}

Source

pub fn with_version(self, version: String) -> Self

Set the version field.

Examples found in repository ?

examples/envelope_nested.rs (line 49)

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_meta.rs (line 29)

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}

Source

pub fn with_extra(self, key: impl Into<String>, value: impl Serialize) -> Self

Add an arbitrary extra key-value pair.

§Example

use scriba::envelope::Meta;

let meta = Meta::default().with_extra("region", "eu-west-1");
assert_eq!(meta.extra.get("region").unwrap(), "eu-west-1");

Examples found in repository ?

examples/envelope_meta.rs (line 31)

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}

More examples

Hide additional examples

examples/envelope_custom_fields.rs (line 59)

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_extra_map( self, map: impl IntoIterator<Item = (String, Value)>, ) -> Self

Add multiple extra key-value pairs from any iterator of (key, value) tuples.

Useful for inserting a batch of arbitrary metadata without chaining multiple with_extra() calls.

§Example

use scriba::envelope::Meta;
use std::collections::BTreeMap;

let mut extras = BTreeMap::new();
extras.insert("region".to_string(), serde_json::json!("eu-west-1"));
extras.insert("actor".to_string(), serde_json::json!("ci-bot"));

let meta = Meta::default().with_extra_map(extras);
assert_eq!(meta.extra.get("region").unwrap(), "eu-west-1");
assert_eq!(meta.extra.get("actor").unwrap(), "ci-bot");