Struct FormatContext

pub struct FormatContext { /* private fields */ }

Context object for formatting Gordian Envelopes with annotations.

The FormatContext provides information about CBOR tags, known values, functions, and parameters that are used to annotate the output of envelope formatting functions. This context enables human-readable output when converting envelopes to string representations like diagnostic notation.

This type is central to the diagnostic capabilities of Gordian Envelope, translating numeric CBOR tags into meaningful names and providing context-specific formatting for special values.

Format Context Content

A FormatContext contains:

• CBOR tag registry (always present)
• Known Values store (when known_value feature is enabled)
• Functions store (when expression feature is enabled)
• Parameters store (when expression feature is enabled)
• A flag indicating whether the format should be flat or structured

Global Context

A global format context is available through the with_format_context! and with_format_context_mut! macros. This global context is initialized with standard tags and registries.

Example

Using the global format context to produce annotated CBOR diagnostic notation:

assert_eq!(e.diagnostic_annotated(),
indoc! {r#"
200(   / envelope /
    201("Hello.")   / leaf /
)
"#}.trim()
);

The annotations (comments after the / characters) provide human-readable context for the CBOR tags and structure.

Implementations

impl FormatContext

pub fn new( flat: bool, tags: Option<&TagsStore>, known_values: Option<&KnownValuesStore>, functions: Option<&FunctionsStore>, parameters: Option<&ParametersStore>, ) -> Self

Creates a new format context with the specified components.

This constructor allows full customization of the format context by providing optional components. Any component not provided will be initialized with its default.

Parameters

• flat - If true, formatting will be flattened without indentation and structure
• tags - Optional CBOR tag registry for mapping tag numbers to names
• known_values - Optional known values registry (requires known_value feature)
• functions - Optional functions registry (requires expression feature)
• parameters - Optional parameters registry (requires expression feature)

Returns

A new FormatContext instance initialized with the provided components.

pub fn is_flat(&self) -> bool

Returns whether flat formatting is enabled.

When flat formatting is enabled, envelope formatting functions produce more compact output without indentation and structural formatting.

pub fn set_flat(self, flat: bool) -> Self

Sets whether flat formatting should be enabled and returns the modified context.

This method allows fluent-style modification of the context’s flat formatting setting.

Parameters

• flat - If true, flat formatting will be enabled

Returns

A new FormatContext with the updated flat setting

pub fn tags(&self) -> &TagsStore

Returns a reference to the CBOR tags registry.

The tags registry maps CBOR tag numbers to human-readable names and provides summarizers for tag-specific formatting.

pub fn tags_mut(&mut self) -> &mut TagsStore

Returns a mutable reference to the CBOR tags registry.

This allows modifying the tags registry to add or change tag mappings.

pub fn known_values(&self) -> &KnownValuesStore

Returns a reference to the known values registry.

The known values registry maps symbolic values (like “true”, “false”, etc.) to their canonical string representations.

This method is only available when the known_value feature is enabled.

pub fn functions(&self) -> &FunctionsStore

Returns a reference to the functions registry.

The functions registry maps function identifiers to their human-readable names for use in expression formatting.

This method is only available when the expression feature is enabled.

pub fn parameters(&self) -> &ParametersStore

Returns a reference to the parameters registry.

The parameters registry maps parameter identifiers to their human-readable names for use in expression formatting.

This method is only available when the expression feature is enabled.

Trait Implementations

impl Clone for FormatContext

fn clone(&self) -> FormatContext

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Default for FormatContext

Default implementation for FormatContext, creating an instance with default components.

fn default() -> Self

Creates a default FormatContext with:

• Flat formatting disabled (structured formatting)
• Default tag registry
• Default known values store (when known_value feature is enabled)
• Default functions store (when expression feature is enabled)
• Default parameters store (when expression feature is enabled)

impl TagsStoreTrait for FormatContext

Implementation of TagsStoreTrait for FormatContext, delegating to the internal TagsStore.

This implementation allows a FormatContext to be used anywhere a TagsStoreTrait is required, providing the tag resolution functionality directly.

fn assigned_name_for_tag(&self, tag: &Tag) -> Option<String>

Returns the assigned name for a tag if one exists.

fn name_for_tag(&self, tag: &Tag) -> String

Returns a name for a tag, either the assigned name or a generic representation.

fn tag_for_name(&self, name: &str) -> Option<Tag>

Looks up a tag by its name.

fn tag_for_value(&self, value: u64) -> Option<Tag>

Looks up a tag by its numeric value.

fn summarizer(&self, tag: TagValue) -> Option<&CBORSummarizer>

Returns a CBOR summarizer for a tag value if one exists.

fn name_for_value(&self, value: u64) -> String

Returns a name for a tag value, either the assigned name or a generic representation.

fn name_for_tag_opt<T>(tag: &Tag, tags: Option<&T>) -> String

where T: TagsStoreTrait, Self: Sized,