9 releases
0.2.7 | Nov 18, 2021 |
---|---|
0.2.6 | Nov 17, 2021 |
0.1.0 | Nov 7, 2021 |
#2002 in Database interfaces
51KB
671 lines
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.
Dependencies
~2MB
~40K SLoC