Crate xylem 

xylem

Xylem is a stateful type conversion framework for Rust.

Concepts

Xylem provides the Xylem trait, which is similar to the std::convert::TryFrom trait, but with the following differences:

Stateful context

Xylem::convert passes a mutable Context, enabling stateful operations throughout the conversion process. See Context documentation for details.

Fixed concersion source

Unlike std::convert::TryFrom, Xylem takes the conversion source type as an associated type Xylem::From instead of a generic parameter. This means each type can only be converted from exactly one other specific type under a given Schema.

Schemas

Xylem accepts a type parameter S (“schema”), which acts as a namespace defining the set of conversion rules. This allows different downstream crates to define their own conversion rules without conflicting with each other. For example, if crate foo wants to convert bool from String and crate bar wants to convert bool from i32, they can separately define schema types foo::Xylem and bar::Xylem, then separately implement

impl Xylem<foo::Schema> for bool {
    type From = String;
    // fn convert() omitted
}
impl Xylem<bar::Schema> for bool {
    type From = i32;
    // fn convert() omitted
}

Furthermore, since foo::Schema and bar::Schema are declared in their own crates, Xylem<S> is not considered a foreign trait, so implementing custom conversion rules for std types will not result in error E0220 or error E0119.

To use the default conversion rules defined by xylem, make the schema implement the SchemaExt trait. There is a convenience macro declare_schema for this:

xylem::declare_schema!(Schema: xylem::SchemaExt);

// we defined a schema type called `Schema`.

It is recommended to use Schema as the schema name and declare it at the crate level, because the Xylem macro uses crate::Schema as the default schema type.

The Xylem macro

Xylem provides a Xylem macro, which derives the corresponding Xylem::From type from a struct or enum by replacing each type with the corresponding Xylem::From type, as well as a Xylem implementation. See the Xylem documentation for details.

Note that the order of fields matters because xylem type conversion is stateful, i.e. previous conversions may affect subsequent ones.

The id feature

With the id feature enabled, xylem provides the Id type, which is the motivational use case for xylem: Deserialize a config file that references other fields by string ID, replace each declaring ID with an integer storing its occurrence order, and replace each referencing ID with the occurrence order of the declaring ID.

The Id type takes two generic parameters, S and X. The type S is just the schema type, while the type X is the subject of identification. X must also implement the Identifiable trait, which has an associated type Identifiable::Scope used to provide a namespace for the ID. The declaring Id field must be declared under X, and X must occur as a (transitive) child of the scope. Further references to the ID of X must occur also as transitive children of the scope, because the scope is dropped when it completes parsing.

Declaring IDs are marked with the argument new = true. If the ID is to be cross-referenced after the scope drops, also mark track = true. Referencing IDs do not need to be marked, but if they serve to import a scope, they should be marked as import = true.

See tests/id.rs and tests/cross_id.rs for example usage.

Note that it is not a design goal for xylem to support lookahead IDs. Due to the stateful nature of xylem, IDs are only indexed when the declaration has been scanned. There is currently no plan to implement multiple passes to pre-index IDs.

Re-exports

pub use id::Id;

pub use id::IdArgs;

pub use id::IdString;

pub use id::Identifiable;

Modules

id

Generates dynamically resolved identifiers.

Macros

declare_schema

Declare a normal schema type.

Structs

DefaultContext

A Context implementation based on typemap::TypeMap.

NoArgs

The default empty argument type.

Traits

AbstractError

The error type for a schema.

ArcSchemaExt

Implement this trait for a schema type to support standard Arc conversion.

BTreeMapSchemaExt

Implement this trait for a schema type to support standard HashMap conversion.

BoxSchemaExt

Implement this trait for a schema type to support standard box conversion.

Context

The context of a conversion.

HashMapSchemaExt

Implement this trait for a schema type to support standard HashMap conversion.

OptionSchemaExt

Implement this trait for a schema type to support standard Option conversion.

Processable

Preprocessor and postprocessor extensions for Xylem.

RcSchemaExt

Implement this trait for a schema type to support standard Rc conversion.

Schema

The schema type for a specific set of conversion rules.

SchemaExt

Implement this trait for a schema type to implement “standard” conversions.

VecSchemaExt

Implement this trait for a schema type to support standard Vec conversion.

Xylem

Implementors of this trait have a special conversion rule under the schema Schema.

Derive Macros

Xylem

Derives a Xylem implementation for a struct or enum and the corresponding Xylem::From type.