Struct DefaultContext 

pub struct DefaultContext<A, T, C>
where
    A: Allocator,
    T: TraceMode,
{ /* private fields */ }

The default context which uses an allocator to track the location of errors.

This is typically constructed using new and by default uses the Global allocator to allocate memory. To customized the allocator to use new_in can be used during construction.

The default constructor is only available when the alloc feature is enabled, and will use the Global allocator.

Implementations

impl<A, T, C> DefaultContext<A, T, C>

where A: Allocator, T: TraceMode, C: ErrorMode<A>,

pub fn with_trace(self) -> DefaultContext<A, Trace, C>

Enable tracing through the current allocator A.

Note that this makes diagnostics methods such as report and errors available on the type.

Tracing requires the configured allocator to work, if for example the Disabled allocator was in use, no diagnostics would be collected.

Examples

use musli::context;

let cx = context::new().with_trace();
// Use cx for encoding/decoding to get detailed error information

pub fn with_capture<E>(self) -> DefaultContext<A, T, Capture<E>>

where E: ContextError<A>,

Capture the specified error type.

This gives access to the last captured error through DefaultContext::unwrap and DefaultContext::result.

Capturing instead of forwarding the error might be beneficial if the error type is large.

Examples

use musli::{Decode, Encode};
use musli::alloc::Global;
use musli::context;
use musli::json::{Encoding, Error};

const ENCODING: Encoding = Encoding::new();

#[derive(Decode, Encode)]
struct Person {
    name: String,
    age: u32,
}

let cx = context::new().with_capture::<Error>();

let mut data = Vec::new();

ENCODING.encode_with(&cx, &mut data, &Person {
    name: "Aristotle".to_string(),
    age: 61,
})?;

assert!(cx.result().is_ok());

let _: Result<Person, _> = ENCODING.from_slice_with(&cx, &data[..data.len() - 2]);
assert!(cx.result().is_err());
Ok::<_, musli::context::ErrorMarker>(())

pub fn with_error<E>(self) -> DefaultContext<A, T, Emit<E>>

where E: ContextError<A>,

Emit the specified error type E.

This causes the method receiving the context to return the specified error type directly instead through Context::Error.

Examples

use musli::{Decode, Encode};
use musli::alloc::Global;
use musli::context;
use musli::json::{Encoding, Error};

const ENCODING: Encoding = Encoding::new();

#[derive(Decode, Encode)]
struct Person {
    name: String,
    age: u32,
}

let cx = context::new().with_error();

let mut data = Vec::new();

ENCODING.encode_with(&cx, &mut data, &Person {
    name: "Aristotle".to_string(),
    age: 61,
})?;

let person: Person = ENCODING.from_slice_with(&cx, &data[..])?;
assert_eq!(person.name, "Aristotle");
assert_eq!(person.age, 61);
Ok::<_, Error>(())

impl<A, C> DefaultContext<A, Trace, C>

where A: Allocator,

pub fn with_type(self) -> Self

If tracing is enabled through DefaultContext::with_trace, this configured the context to visualize type information, and not just variant and fields.

Examples

use musli::context;

let cx = context::new().with_trace().with_type();

pub fn report(&self) -> Report<'_, A>

Generate a line-separated report of all reported errors.

This can be useful if you want a quick human-readable overview of errors. The line separator used will be platform dependent.

Examples

use musli::context::{self, ErrorMarker};
use musli::value::Value;
use musli::json::Encoding;

const ENCODING: Encoding = Encoding::new();

let cx = context::new().with_trace();

let ErrorMarker = ENCODING.from_str_with::<_, Value<_>>(&cx, "not json").unwrap_err();
let report = cx.report();
println!("{report}");

pub fn errors(&self) -> Errors<'_, A>

Iterate over all reported errors.

Examples

use musli::context::{self, ErrorMarker};
use musli::value::Value;
use musli::json::Encoding;

const ENCODING: Encoding = Encoding::new();

let cx = context::new().with_trace();

let ErrorMarker = ENCODING.from_str_with::<_, Value<_>>(&cx, "not json").unwrap_err();
assert!(cx.errors().count() > 0);

impl<A, T, E> DefaultContext<A, T, Capture<E>>

where A: Allocator, T: TraceMode, E: ContextError<A>,

pub fn unwrap(&self) -> E

Unwrap the error marker or panic if there is no error.

Examples

use musli::context;

let cx = context::new().with_capture::<String>();
// This will panic since no error has been captured
let error = cx.unwrap();

pub fn result(&self) -> Result<(), E>

Coerce a captured error into a result.

Examples

use musli::context;

let cx = context::new().with_capture::<String>();
let result = cx.result();
assert!(result.is_ok());

Trait Implementations

impl<A, T, C> Context for &DefaultContext<A, T, C>

where A: Allocator, T: TraceMode, C: ErrorMode<A>,

type Error = <C as ErrorMode<A>>::Error

Error produced by the context.

type Mark = <<T as TraceMode>::Impl<A> as TraceImpl<A>>::Mark

A mark during processing.

type Allocator = A

The allocator associated with the context.

fn clear(self)

Clear the state of the context, allowing it to be re-used.

fn alloc(self) -> Self::Allocator

Access the underlying allocator.

fn custom<E>(self, message: E) -> Self::Error

where E: 'static + Send + Sync + Error,

Report a custom error, which is not encapsulated by the error type expected by the context. This is essentially a type-erased way of reporting error-like things out from the context.

fn message<M>(self, message: M) -> Self::Error

where M: Display,

Report a message as an error.

fn message_at<M>(self, mark: &Self::Mark, message: M) -> Self::Error

where M: Display,

Report an error based on a mark.

fn custom_at<E>(self, mark: &Self::Mark, message: E) -> Self::Error

where E: 'static + Send + Sync + Error,

Report an error based on a mark.

fn mark(self) -> Self::Mark

Return a mark which acts as a checkpoint at the current encoding state.

fn restore(self, mark: &Self::Mark)

Restore the state of the context to the specified mark.

fn advance(self, n: usize)

Advance the context by n bytes of input.

fn enter_named_field<F>(self, name: &'static str, field: F)

where F: Display,

Trace that we’ve entered the given named field.

fn enter_unnamed_field<F>(self, index: u32, name: F)

where F: Display,

Trace that we’ve entered the given unnamed field.

fn leave_field(self)

Trace that we’ve left the last field that was entered.

fn enter_struct(self, name: &'static str)

Indicate that we’ve entered a struct with the given name.

fn leave_struct(self)

Trace that we’ve left the last struct that was entered.

fn enter_enum(self, name: &'static str)

Indicate that we’ve entered an enum with the given name.

fn leave_enum(self)

Trace that we’ve left the last enum that was entered.

fn enter_variant<V>(self, name: &'static str, tag: V)

where V: Display,

Trace that we’ve entered the given variant in an enum.

fn leave_variant(self)

Trace that we’ve left the last variant that was entered.

fn enter_sequence_index(self, index: usize)

Trace a sequence field.

fn leave_sequence_index(self)

Trace that we’ve left the last sequence index that was entered.

fn enter_map_key<F>(self, field: F)

where F: Display,

Trace a that a map key has been entered.

fn leave_map_key(self)

Trace that we’ve left the last map field that was entered.

fn map<E>(self) -> impl FnOnce(E) -> Self::Error

where E: 'static + Send + Sync + Error,

Generate a map function which maps an error using the custom function.

impl Default for DefaultContext<Global, NoTrace, Ignore>

Available on crate feature alloc only.

fn default() -> Self

Returns the “default value” for a type.