Crate enumscribe

Traits for converting between enums and strings. Intended to be used alongside the enumscribe_derive crate, which provides derive macros for these traits.

Here is a basic usage example:

use enumscribe::{ScribeStaticStr, TryUnscribe};

#[derive(ScribeStaticStr, TryUnscribe, PartialEq, Eq, Debug)]
enum Airport {
    #[enumscribe(str = "LHR")]
    Heathrow,
    #[enumscribe(str = "LGW")]
    Gatwick,
    #[enumscribe(str = "LTN")]
    Luton,
}

// Convert an Airport to a &'static str
assert_eq!(Airport::Heathrow.scribe(), "LHR");

// Convert a &str to a Option<Airport>
assert_eq!(Airport::try_unscribe("LGW"), Some(Airport::Gatwick));

The #[enumscribe(str = "...")] allows us to specify what string should be used to represent a particular variant. If this is omitted, the name of the variant will be used instead.

The #[enumscribe(case_insensitive)] attribute can be used to make the “Unscribe” traits perform case-insensitive matching for a variant:

use enumscribe::TryUnscribe;

#[derive(TryUnscribe, PartialEq, Eq, Debug)]
enum Website {
    #[enumscribe(str = "github.com", case_insensitive)]
    Github,
    #[enumscribe(str = "crates.io", case_insensitive)]
    CratesDotIo,
}

assert_eq!(Website::try_unscribe("GiThUb.CoM"), Some(Website::Github));

You can also have a variant which stores strings that could not be matched to any other variant. This is done using the #[enumscribe(other)] attribute. The variant should have a single field, which is a String.

use std::borrow::Cow;

use enumscribe::{Unscribe, ScribeCowStr};

#[derive(ScribeCowStr, Unscribe, PartialEq, Eq, Debug)]
enum Website {
    #[enumscribe(str = "github.com", case_insensitive)]
    Github,
    #[enumscribe(str = "crates.io", case_insensitive)]
    CratesDotIo,
    #[enumscribe(other)]
    Other(String),
}

// Note that we don't need to use an Option anymore!
assert_eq!(Website::unscribe("github.com"),
           Website::Github);

// Unbelievably, websites exist other than github and crates.io
assert_eq!(Website::unscribe("stackoverflow.com"),
           Website::Other("stackoverflow.com".to_owned()));

// We can't scribe to a &'static str anymore, so we use a Cow<'static, str> instead
assert_eq!(Website::Github.scribe(),
           Cow::Borrowed::<'static, str>("github.com"));

assert_eq!(Website::Other("owasp.org".to_owned()).scribe(),
           Cow::Owned::<'static, str>("owasp.org".to_owned()));

If you need to, you can use #[enumscribe(ignore)] to prevent a variant from being used by Scribe or Unscribe traits.

However, this means that converting the enum to a string can fail, so you must use TryScribe instead of Scribe in this case.

use enumscribe::TryScribeStaticStr;

#[derive(TryScribeStaticStr, PartialEq, Eq, Debug)]
enum Airport {
    #[enumscribe(str = "LHR")]
    Heathrow,
    #[enumscribe(str = "LGW")]
    Gatwick,
    #[enumscribe(str = "LTN")]
    Luton,
    #[enumscribe(ignore)]
    SecretExtraVariant(i32), // we have to ignore this variant because of the i32 field
}

assert_eq!(Airport::SecretExtraVariant(123).try_scribe(), None);

assert_eq!(Airport::Luton.try_scribe(), Some("LTN"));

You can derive serde::Serialize and serde::Deserialize using the same syntax:

use serde::{Serialize, Deserialize};

use enumscribe::{EnumSerialize, EnumDeserialize};

#[derive(EnumSerialize, EnumDeserialize, PartialEq, Eq, Clone, Copy, Debug)]
enum Airport {
    #[enumscribe(str = "LHR")]
    Heathrow,
    #[enumscribe(str = "LGW")]
    Gatwick,
    #[enumscribe(str = "LTN")]
    Luton,
}

#[derive(Serialize, Deserialize, PartialEq, Eq, Debug)]
struct Flight {
    takeoff: Airport,
    landing: Airport,
}

// There are probably much more economical ways of making this journey
let flight = Flight {
    takeoff: Airport::Heathrow,
    landing: Airport::Gatwick,
};

let flight_json = r#"{"takeoff":"LHR","landing":"LGW"}"#;

assert_eq!(serde_json::to_string(&flight)?,
           flight_json.to_owned());

assert_eq!(serde_json::from_str::<Flight>(flight_json)?,
           flight);

Here is a table to show which traits you should derive for your enum:

ignore used?	other used?	Conversion to string	Conversion from string
No	No	ScribeStaticStr	TryUnscribe
No	Yes	ScribeCowStr	Unscribe
Yes	No	TryScribeStaticStr	TryUnscribe
Yes	Yes	TryScribeCowStr	Unscribe

There are also ScribeString and TryScribeString traits which can be used in the same situations as ScribeCowStr and TryScribeCowStr, respectively. These traits produce a String rather than a Cow<'static, str>, so they will always perform an allocation. Therefore, you should prefer the ScribeCowStr traits over the ScribeString traits, unless you really don’t want to use a Cow for whatever reason.

Traits

ScribeCowStr	Trait for converting an enum to a clone-on-write string.
ScribeStaticStr	Trait for converting an enum to a static string slice.
ScribeString	Trait for converting an enum to an allocated string. Generally, ScribeCowStr should be preferred over this trait because it avoids unnecessary allocations.
TryScribeCowStr	Trait for converting an enum to a clone-on-write string, or None if the conversion fails.
TryScribeStaticStr	Trait for converting an enum to a static string slice, or None if the conversion fails.
TryScribeString	Trait for converting an enum to an allocated string, or None if the conversion fails. Generally, TryScribeCowStr should be preferred over this trait because it avoids unnecessary allocations.
TryUnscribe	Trait for converting from a string to an enum, or None if the conversion fails.
Unscribe	Trait for converting from a string to an enum.

Derive Macros

EnumDeserialize	Derives serde::Deserialize for an enum.
EnumSerialize	Derives serde::Serialize for an enum.
ScribeCowStr	Derives enumscribe::ScribeCowStr for an enum. This allows the enum to be converted to a Cow<'static, str> using the scribe() method.
ScribeStaticStr	Derives enumscribe::ScribeStaticStr for an enum. This allows the enum to be converted to a &'static str using the scribe() method.
ScribeString	Derives enumscribe::ScribeString for an enum. This allows the enum to be converted to a String using the scribe() method.
TryScribeCowStr	Derives enumscribe::TryScribeCowStr for an enum. This allows the enum to be converted to a Option<Cow<'static, str>> using the try_scribe() method.
TryScribeStaticStr	Derives enumscribe::TryScribeStaticStr for an enum. This allows the enum to be converted to a Option<&'static str> using the try_scribe() method.
TryScribeString	Derives enumscribe::TryScribeString for an enum. This allows the enum to be converted to a Option<String> using the try_scribe() method.
TryUnscribe	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.
Unscribe	Derives enumscribe::Unscribe for an enum. This allows a &str to be converted to the enum using the unscribe() associated function.