tom
/
enumscribe
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Documentation

Browse Source
rename
Pantonshire 5 years ago
parent 13c6b78698
commit 11a5777eab
2 changed files with 179 additions and 10 deletions
Show Stats Download Patch File Download Diff File

24
enumscribe/src/lib.rs
Unescape Escape View File

@ -169,7 +169,8 @@ use std::borrow::Cow;
/// Trait for converting an enum to a static string slice.
///
/// Like all of the traits provided by enumscribe, this should not be implemented manually; use
/// `#[derive(ScribeStaticStr)]` provided by the [enumscribe_derive] crate instead.
/// [`#[derive(ScribeStaticStr)]`](derive.ScribeStaticStr.html) provided by the
/// [enumscribe_derive] crate instead.
///
/// When deriving this trait, you may specify the string that a particular variant should be
/// converted to by annotating it with `#[enumscribe(str = "foo")]`. If this is omitted, the name
@ -185,7 +186,8 @@ pub trait ScribeStaticStr {
/// Trait for converting an enum to a static string slice, or `None` if the conversion fails.
///
/// Like all of the traits provided by enumscribe, this should not be implemented manually; use
/// `#[derive(TryScribeStaticStr)]` provided by the [enumscribe_derive] crate instead.
/// [`#[derive(TryScribeStaticStr)]`](derive.TryScribeStaticStr.html) provided by the
/// [enumscribe_derive] crate instead.
///
/// When deriving this trait, you may specify the string that a particular variant should be
/// converted to by annotating it with `#[enumscribe(str = "foo")]`. If this is omitted, the name
@ -204,7 +206,8 @@ pub trait TryScribeStaticStr {
/// preferred over this trait because it avoids unnecessary allocations.
///
/// Like all of the traits provided by enumscribe, this should not be implemented manually; use
/// `#[derive(ScribeString)]` provided by the [enumscribe_derive] crate instead.
/// [`#[derive(ScribeString)]`](derive.ScribeString.html) provided by the
/// [enumscribe_derive] crate instead.
///
/// This trait can only be used if none of the enum's variants use `ignore`.
pub trait ScribeString {
@ -216,7 +219,8 @@ pub trait ScribeString {
/// allocations.
///
/// Like all of the traits provided by enumscribe, this should not be implemented manually; use
/// `#[derive(TryScribeString)]` provided by the [enumscribe_derive] crate instead.
/// [`#[derive(TryScribeString)]`](derive.TryScribeString.html) provided by the
/// [enumscribe_derive] crate instead.
pub trait TryScribeString {
fn try_scribe(&self) -> Option<String>;
}
@ -224,7 +228,8 @@ pub trait TryScribeString {
/// Trait for converting an enum to a clone-on-write string.
///
/// Like all of the traits provided by enumscribe, this should not be implemented manually; use
/// `#[derive(ScribeCowStr)]` provided by the [enumscribe_derive] crate instead.
/// [`#[derive(ScribeCowStr)]`](derive.ScribeCowStr.html) provided by the
/// [enumscribe_derive] crate instead.
///
/// When deriving this trait, you may specify the string that a particular variant should be
/// converted to by annotating it with `#[enumscribe(str = "foo")]`. If this is omitted, the name
@ -243,7 +248,8 @@ pub trait ScribeCowStr {
/// Trait for converting an enum to a clone-on-write string, or `None` if the conversion fails.
///
/// Like all of the traits provided by enumscribe, this should not be implemented manually; use
/// `#[derive(TryScribeCowStr)]` provided by the [enumscribe_derive] crate instead.
/// [`#[derive(TryScribeCowStr)]`](derive.TryScribeCowStr.html) provided by the
/// [enumscribe_derive] crate instead.
///
/// When deriving this trait, you may specify the string that a particular variant should be
/// converted to by annotating it with `#[enumscribe(str = "foo")]`. If this is omitted, the name
@ -262,7 +268,8 @@ pub trait TryScribeCowStr {
/// Trait for converting from a string to an enum.
///
/// Like all of the traits provided by enumscribe, this should not be implemented manually; use
/// `#[derive(Unscribe)]` provided by the [enumscribe_derive] crate instead.
/// [`#[derive(Unscribe)]`](derive.Unscribe.html) provided by the
/// [enumscribe_derive] crate instead.
///
/// When deriving this trait, you may specify the string that should map to a particular variant
/// by annotating it with `#[enumscribe(str = "foo")]`. If this is omitted, the name of the variant
@ -280,7 +287,8 @@ pub trait Unscribe: Sized {
/// Trait for converting from a string to an enum, or `None` if the conversion fails.
///
/// Like all of the traits provided by enumscribe, this should not be implemented manually; use
/// `#[derive(TryUnscribe)]` provided by the [enumscribe_derive] crate instead.
/// [`#[derive(TryUnscribe)]`](derive.TryUnscribe.html) provided by the
/// [enumscribe_derive] crate instead.
///
/// Annotating a variant with `#[enumscribe(case_insensitive)]` will cause case insensitive matching
/// to be used for that variant. If it is omitted, matching will be case sensitive.

165
enumscribe_derive/src/lib.rs
Unescape Escape View File

@ -1,6 +1,7 @@
//! Derive macros for the traits provided by `enumscribe`, to help you easily convert your enums
//! to strings and vice-versa. See the `enumscribe` crate's documentation for information on
//! deriving these traits.
//! to strings and vice-versa.
//!
//! See the documentation for the `enumscribe` crate for usage examples.
use proc_macro::TokenStream;
@ -269,6 +270,30 @@ fn gen_unscribe_match<F, G, E>(
Ok(main_match)
}
/// Derives `enumscribe::ScribeStaticStr` for an enum. This allows the enum to be converted to
/// a `&'static str` using the `scribe()` method.
///
/// You may annotate variants with `#[enumscribe(str = "foo")]` to specify what string the variant
/// should be converted to (replacing `"foo"` with a string of your choice). If this is omitted,
/// the name of the variant will be used instead. Using the same string for two variants of the
/// same enum will cause a compile-time error.
///
/// Other derive macros in this crate allow you to use attributes like `#[enumscribe(other)]`
/// and `#[enumscribe(ignore)]`, where `other` allows you to specify a variant that should be used
/// to store strings that could not be matched to any other variant, and `ignore` lets you tell
/// `enumscribe` not to consider a particular variant when deriving traits. However, using either
/// of these attributes when deriving `ScribeStaticStr` will cause a compile-time error; if these
/// attributes are used, then there are some cases where it would be impossible to return
/// a meaningful `&'static str`.
///
/// If you want to use `#[enumscribe(other)]`, try deriving
/// [`ScribeCowStr`](derive.ScribeCowStr.html) instead.
///
/// If you want to use `#[enumscribe(ignore)]`, try deriving
/// [`TryScribeStaticStr`](derive.TryScribeStaticStr.html) instead.
///
/// If you want to use both, try deriving
/// [`TryScribeCowStr`](derive.TryScribeCowStr.html) instead.
#[proc_macro_derive(ScribeStaticStr, attributes(enumscribe))]
pub fn derive_scribe_static_str(input: TokenStream) -> TokenStream {
gen_scribe_impl(
@ -296,6 +321,21 @@ pub fn derive_scribe_static_str(input: TokenStream) -> TokenStream {
)
}
/// Derives `enumscribe::TryScribeStaticStr` for an enum. This allows the enum to be converted to
/// a `Option<&'static str>` using the `try_scribe()` method.
///
/// You may annotate variants with `#[enumscribe(str = "foo")]` to specify what string the variant
/// should be converted to (replacing `"foo"` with a string of your choice). If this is omitted,
/// the name of the variant will be used instead. Using the same string for two variants of the
/// same enum will cause a compile-time error.
///
/// This is a version of [`ScribeStaticStr`](derive.ScribeStaticStr.html) intended to be used if
/// you have one or more variants annotated with `#[enumscribe(ignore)]`. Calling `try_scribe()`
/// on an ignored variant will always return `None`.
///
/// Like [`ScribeStaticStr`](derive.ScribeStaticStr.html), you may not use `#[enumscribe(other)]`
/// when deriving this trait. If you want to use `other`, try deriving
/// [`TryScribeCowStr`](derive.TryScribeCowStr.html) instead.
#[proc_macro_derive(TryScribeStaticStr, attributes(enumscribe))]
pub fn derive_try_scribe_static_str(input: TokenStream) -> TokenStream {
gen_try_scribe_impl(
@ -319,6 +359,15 @@ pub fn derive_try_scribe_static_str(input: TokenStream) -> TokenStream {
)
}
/// Derives `enumscribe::ScribeString` for an enum. This allows the enum to be converted to
/// a `String` using the `scribe()` method.
///
/// This behaves almost identically to [`ScribeCowStr`](derive.ScribeCowStr.html), except the
/// return type is `String` instead of `Cow<'static, str>`.
///
/// Since a `String` is returned, an allocation must always be performed, which is wasteful.
/// [`ScribeCowStr`](derive.ScribeCowStr.html) should be preferred because it avoids unnecessary
/// allocations.
#[proc_macro_derive(ScribeString, attributes(enumscribe))]
pub fn derive_scribe_string(input: TokenStream) -> TokenStream {
gen_scribe_impl(
@ -345,6 +394,15 @@ pub fn derive_scribe_string(input: TokenStream) -> TokenStream {
)
}
/// Derives `enumscribe::TryScribeString` for an enum. This allows the enum to be converted to
/// a `Option<String>` using the `try_scribe()` method.
///
/// This behaves almost identically to [`TryScribeCowStr`](derive.TryScribeCowStr.html), except the
/// return type is `Option<String>` instead of `Option<Cow<'static, str>>`.
///
/// Since a `String` is returned, an allocation must always be performed, which is wasteful.
/// [`TryScribeCowStr`](derive.TryScribeCowStr.html) should be preferred because it avoids
/// unnecessary allocations.
#[proc_macro_derive(TryScribeString, attributes(enumscribe))]
pub fn derive_try_scribe_string(input: TokenStream) -> TokenStream {
gen_try_scribe_impl(
@ -369,6 +427,25 @@ pub fn derive_try_scribe_string(input: TokenStream) -> TokenStream {
)
}
/// Derives `enumscribe::ScribeCowStr` for an enum. This allows the enum to be converted to
/// a `Cow<'static, str>` using the `scribe()` method.
///
/// You may annotate variants with `#[enumscribe(str = "foo")]` to specify what string the variant
/// should be converted to (replacing `"foo"` with a string of your choice). If this is omitted,
/// the name of the variant will be used instead. Using the same string for two variants of the
/// same enum will cause a compile-time error.
///
/// This derive also supports annotating a variant with `#[enumscibe(other)]`, which is useful
/// because it is required to derive [`Unscribe`](derive.Unscribe.html). This allows you to
/// specify that a variant should be used to store strings that could not be matched to any other
/// variant when unscribing. The variant should have a single field, which should have type
/// `String`.
///
/// If you do not want to use `#[enumscribe(other)]`, you should derive
/// [`ScribeStaticStr`](derive.ScribeStaticStr.html) instead.
///
/// This derive does not support ignoring variants with `#[enumscribe(ignore)]`. If you want to
/// ignore variants, try deriving [`TryScribeCowStr`](derive.TryScribeCowStr.html) instead.
#[proc_macro_derive(ScribeCowStr, attributes(enumscribe))]
pub fn derive_scribe_cow_str(input: TokenStream) -> TokenStream {
gen_scribe_impl(
@ -397,6 +474,26 @@ pub fn derive_scribe_cow_str(input: TokenStream) -> TokenStream {
)
}
/// Derives `enumscribe::TryScribeCowStr` for an enum. This allows the enum to be converted to
/// a `Option<Cow<'static, str>>` using the `try_scribe()` method.
///
/// You may annotate variants with `#[enumscribe(str = "foo")]` to specify what string the variant
/// should be converted to (replacing `"foo"` with a string of your choice). If this is omitted,
/// the name of the variant will be used instead. Using the same string for two variants of the
/// same enum will cause a compile-time error.
///
/// This is a version of [`ScribeCowStr`](derive.ScribeCowStr.html) intended to be used if
/// you have one or more variants annotated with `#[enumscribe(ignore)]`. Calling `try_scribe()`
/// on an ignored variant will always return `None`.
///
/// This derive also supports annotating a variant with `#[enumscibe(other)]`, which is useful
/// because it is required to derive [`Unscribe`](derive.Unscribe.html). This allows you to
/// specify that a variant should be used to store strings that could not be matched to any other
/// variant when unscribing. The variant should have a single field, which should have type
/// `String`.
///
/// If you do not want to use `#[enumscribe(other)]`, you should derive
/// [`TryScribeStaticStr`](derive.TryScribeStaticStr.html) instead.
#[proc_macro_derive(TryScribeCowStr, attributes(enumscribe))]
pub fn derive_try_scribe_cow_str(input: TokenStream) -> TokenStream {
gen_try_scribe_impl(
@ -423,6 +520,27 @@ pub fn derive_try_scribe_cow_str(input: TokenStream) -> TokenStream {
)
}
/// Derives `enumscribe::Unscribe` for an enum. This allows a `&str` to be converted to the
/// enum using the `unscribe()` associated function.
///
/// You may annotate variants with `#[enumscribe(str = "foo")]` to specify what string should
/// convert to the variant (replacing `"foo"` with a string of your choice). If this is omitted,
/// the name of the variant will be used instead. Using the same string for two variants of the
/// same enum will cause a compile-time error.
///
/// You may annotate a variant with `#[enumscribe(case_insensitive)]` to use case-insensitive
/// matching for that variant. For example, if a variant is annotated with
/// `#[enumscribe(str = "baa", case_insensitive)]`, then strings like `"baa"`, `"BAA"`, `"bAa"`
/// etc. will all be matched to that variant.
///
/// In order to derive this trait, you must have exactly one variant annotated with
/// `#[enumscribe(other)]`. This variant will be used to store any string that could not be matched
/// to any of the other variants. The variant must have exactly one field, which should have type
/// `String`. Both named (`Variant { name: String }`) and unnamed (`Variant(String)`) fields are
/// allowed.
///
/// If you do not want to use `#[enumscribe(other)]`, try deriving
/// [`TryUnscribe`](derive.TryUnscribe.html) instead.
#[proc_macro_derive(Unscribe, attributes(enumscribe))]
pub fn derive_unscribe(input: TokenStream) -> TokenStream {
gen_unscribe_impl(
@ -446,6 +564,24 @@ pub fn derive_unscribe(input: TokenStream) -> TokenStream {
)
}
/// Derives `enumscribe::TryUnscribe` for an enum. This allows a `&str` to be converted to an
/// `Option` of the enum using the `try_unscribe()` associated function.
///
/// You may annotate variants with `#[enumscribe(str = "foo")]` to specify what string should
/// convert to the variant (replacing `"foo"` with a string of your choice). If this is omitted,
/// the name of the variant will be used instead. Using the same string for two variants of the
/// same enum will cause a compile-time error.
///
/// You may annotate a variant with `#[enumscribe(case_insensitive)]` to use case-insensitive
/// matching for that variant. For example, if a variant is annotated with
/// `#[enumscribe(str = "baa", case_insensitive)]`, then strings like `"baa"`, `"BAA"`, `"bAa"`
/// etc. will all be matched to that variant.
///
/// Unlike [`Unscribe`](derive.Unscribe.html), there is no requirement to have a variant annotated
/// with `#[enumscribe(other)]`, although you may use it if you want. If there is an `other`
/// variant, then the `other` variant will be returned when a string could not be matched to any
/// other variant. If there is no `other` variant, `None` will be returned when a string could not
/// be matched to any other variant.
#[proc_macro_derive(TryUnscribe, attributes(enumscribe))]
pub fn derive_try_unscribe(input: TokenStream) -> TokenStream {
gen_unscribe_impl(
@ -463,6 +599,15 @@ pub fn derive_try_unscribe(input: TokenStream) -> TokenStream {
)
}
/// Derives `serde::Serialize` for an enum.
///
/// The enum will be serialized to a string. You can specify what string should be used to
/// represent a particular variant by using `#[enumscribe(str = "foo")]`, just like the other
/// derive macros in this crate.
///
/// This derive also allows you to use `#[enumscribe(other)]` and `#[enumscribe(ignore)]`.
/// Trying to serialize an ignored variant will result in an error being returned. Serializing
/// an `other` variant will simply use whatever the value of its field is.
#[cfg(feature = "serde")]
#[proc_macro_derive(EnumSerialize, attributes(enumscribe))]
pub fn derive_enum_serialize(input: TokenStream) -> TokenStream {
@ -540,6 +685,22 @@ pub fn derive_enum_serialize(input: TokenStream) -> TokenStream {
}).into()
}
/// Derives `serde::Deserialize` for an enum.
///
/// The enum will be deserialized from a string. If the input was not a valid string, an error
/// will be returned. You can specify what string should map to a particular variant by using
/// `#[enumscribe(str = "foo")]`, just like the other derive macros in this crate. You can also
/// use `#[enumscribe(case_insensitive)]` to use case-insensitive matching for a variant, like
/// [`Unscribe`](derive.Unscribe.html) and [`TryUnscribe`](derive.TryUnscribe.html).
///
/// Also like [`Unscribe`](derive.Unscribe.html), you can annotate a variant with
/// `#[enumscribe(other)]`. If included, the `other` variant will be used to store strings that
/// could not be matched to any other variant. The `other` variant should have a single field,
/// which should have type `String`. If an `other` variant is not included, an error will be
/// returned when a string could not be matched to any variant.
///
/// This derive also allows you to use `#[enumscribe(ignore)]`. No string will ever deserialize
/// to an ignored variant.
#[cfg(feature = "serde")]
#[proc_macro_derive(EnumDeserialize, attributes(enumscribe))]
pub fn derive_enum_deserialize(input: TokenStream) -> TokenStream {

Write Preview
Loading…
Cancel
Save