Module warning 

These types are the basis for writing functions that can emit a set of Warnings based on the value they are trying to create.

The aim is for functions to be as resilient as possible while creating the value and emit commentary on their progress in the form of a growing set of Warnings.

The caller of the function can use the set of Warnings to decide whether the operation was a success or failure and whether the value can be used or needs to be modified.

A concrete example is the conversion of a JSON json::Element into a country::Code. The json::Element may be the incorrect type and so the function issues a Warning and exits as it cannot continue with the given data. The signature of this fn is something like:

// file: country.rs
  
pub enum Warning {
    InvalidType,
    ...
}

pub enum Expect {
    Alpha2,
    Alpha3
}

pub enum Code {
    fn from_json_element(json: json::Element, expect: Expect) -> Verdict<Code, Warning> {
        ...
    }
}

A Verdict is a Result where both the Ok and Err variants return a potential set of Warnings. The Ok variant is Caveat<T>, where a Caveat contains a value but potentially contains cautionary details to be taken into account when using the value. Hence, the name.

The Err variant is Warnings<K>, a collection of Warnings. A Warning can be converted into an Error by the caller. A Caveat<T> is more completely described as Caveat<T, K> where the Caveat contains a value T and a set of Warnings<K>.

All of this is to say that a resilient function can always return Warnings and the caller can gather them together into a new set or fail.

Returning to the example of the country::Code, if the json::Element is the expected string type, then processing continues. The string may contain control chars or escape chars and both these cases will emit a Warning. The string may be made up of three chars when two were expected. This is the interesting case, as some country::Code fields are alpha-3 where others are alpha-2. Processing can still continue, as an alpha-3 code can be converted to an alpha-2 simply, while emitting a Warning.

The caller can decide whether this is acceptable or not.

Structs

Caveat

A value that may have associated Warnings.

Group

A group of warning Kinds associated with an Element.

GroupByElem

An iterator of borrowed warning Kinds grouped by json::Element.

IntoGroup

A group of warning Kinds associated with an Element.

IntoGroupByElem

An iterator of owned warning Kinds grouped by json::Element.

Set

A set of Warnings transported through the system using a Verdict or Caveat.

SetWriter

A Display object for writing a set of warnings.

Warning

Groups together a module’s Kind and the associated json::Element.

Traits

IntoCaveat

Converts a value T into a Caveat.

Kind

Each mod defines warnings for the type that it’s trying to parse or lint from a json::Element.

OptionExt

Convert an Option into a Verdict ready to exit the fn.

VerdictExt

Verdict specific extension methods for the Result type.

Type Aliases

Verdict

A Verdict is a standard Result with Warnings potentially issued for both the Ok and Err variants.