penum is a procedural macro that is used for enum conformity and
static dispatch. This is done by specifying a declarative pattern
that expresses how we should interpret the enum. It's a tool for
asserting how enums should look and behave through simple
expressive rust grammar.
More details
Patterns — can be thought of as a toy shape sorter that sorts
through enum variants and makes sure they fit. So each variant has a
certain shape that must satisfy the patterns we've specified. There
are 3 shapes to choose from, tuples (), structs {} and
units.
Predicates — are used in combination with patterns to assert
what the matched variants field types should implement. They can be
expressed like a regular where clause, e.g where T: Trait<Type>. The
generic parameters needs to be introduced inside a pattern fragment.
Smart dispatch — lets us express how an enum should behave in
respect to its variants. The symbol that is used to express this is
^ and should be put in front of the trait you wish to be dispatched,
e.g. (T) where T: ^AsRef<str>. The dispatcher is smart enough to
figure out certain return types for methods such that non-matching
variants can be assigned with a default return statement. i.e types
like Option<_>, Result<_, E> and many other types (including
Primitive Types) can get defaulted automatically for us instead of
returning them with panic. This is currently limited to rust std
library traits, but there are plans to extend support for custom trait
definitions soon.
This crate is available on crates.io
and can be used by adding the following to your project's Cargo.toml:
toml
[dependencies]
penum = "0.1.24"
Or run this command in your cargo project:
sh
$ cargo add penum
Penum is smart enough to infer certain return types for non-matching
variants. e.g Option<T>, &Option<T>, String, &str. It can even
handle &String, referenced non-const types. The goal is to support any
type, which we could potentially do by checking for types implementing
the Default trait.
Note, when dispatching traits with associated types, it's important to
declare them. e.g Add<i32, Output = i32>.
A Penum expression can look like this:
```rust
// Dispatch symbol.
// |
// ^^^ ^^^^^^^^^
// | |
// | Predicate bound.
// |
// Pattern fragment.
```
Alternative syntax
```rust
// ^^^^
// |
// Shorthand for _ where expression which allows + bounds.
```
```rust
// ^^^^ ^^^
// | |
// Shorthand for _ where Type: ^Trait expression.
// Useful when you only want to implement one trait at the time.
```
Here we have an enum with one unary and one binary tuple variant where
the field type Storage and Something implements the trait Trait.
The goal is to be able to call the trait method through Foo. This
can be accomplished automatically by marking the trait with a dispatch
symbol ^.
Supported std traits
Any, Borrow, BorrowMut, Eq, AsMut, AsRef, From, Into,
TryFrom, TryInto, Default, Binary, Debug, Display,
LowerExp, LowerHex, Octal, Pointer, UpperExp, UpperHex,
Future, IntoFuture, FromIterator, FusedIterator, IntoIterator,
Product, Sum, Copy, Sized, ToSocketAddrs, Add, AddAssign,
BitAnd, BitAndAssign, BitOr, BitOrAssign, BitXor,
BitXorAssign, Deref, DerefMut, Div, DivAssign, Drop, Fn,
FnMut, FnOnce, Index, IndexMut, Mul, MulAssign,
MultiMethod, Neg, Not, Rem, RemAssign, Shl, ShlAssign,
Shr, ShrAssign, Sub, SubAssign, Termination, SliceIndex,
FromStr, ToString
```rust
enum Store {
V0(),
V1(i32),
V2(String, i32),
V3(i32, usize, String),
V4(i32, String, usize),
V5 { age: usize, name: String },
V6,
}
- Will turn into this:
rust
impl AsRef
There is also support for user defined traits, but make sure that they are tagged before the enum. ```rust
trait Trait { fn method(&self, text: &str) -> &Option<&str>; } ```
Under development
For non-std types we rely on the Default trait, which means, if we can
prove that a type implements Default we can automatically add them as
return types for non-matching variants,
Used penum to force every variant to be a tuple with one field that must
implement Trait.
```rust
enum Guard {
Bar(String),
^^^^^^
// ERROR: String doesn't implement Trait
Bor(Option<String>),
^^^^^^^^^^^^^^
// ERROR: `Option<String>` doesn't implement `Trait`
Bur(Vec<String>),
^^^^^^^^^^^
// ERROR: `Vec<String>` doesn't implement `Trait`
Byr(),
^^^^^
// ERROR: `Byr()` doesn't match pattern `(T)`
Bxr { name: usize },
^^^^^^^^^^^^^^^
// ERROR: `{ nname: usize }` doesn't match pattern `(T)`
Brr,
^^^
// ERROR: `Brr` doesn't match pattern `(T)`
Bir(i32, String), // Works!
Beer(i32) // Works!
} ```
If you don't care about the actual pattern matching, then you could use
_ to automatically infer every shape and field. Combine this with
concrete dispatch types, and you got yourself a auto dispatcher.
```rust
enum Foo { V1(Al), V2(i32, Be), V3(Ce), V4 { name: String, age: Be }, }
// Will create these implementations impl Special for Foo { fn ret(&self) -> Option<&String> { match self { Foo::V3(val) => val.ret(), _ => None, } } }
impl AsInner
```
Impls — can be seen as a shorthand for a concrete type that
implements this trait, and are primarily used as a substitute for
regular generic trait bound expressions. They look something like
this, (impl Copy, impl Copy) | {name: impl Clone}
Placeholders — are single unbounded wildcards, or if you are
familiar with rust, it's the underscore _ identifier and usually
means that something is ignored, which means that they will satisfy
any type (_, _) | {num: _}.
Variadic — are similar to placeholders, but instead of only being
able to substitute one type, variadics can be substituted by 0 or more
types. Like placeholders, they are a way to express that we don't care
about the rest of the parameters in a pattern. The look something like
this(T, U, ..) | {num: T, ..}.