enumscribe

This crate provides derive macros for converting between simple enums and strings. It also includes derive macros for serde::Serialize and serde::Deserialize for simple enums.

Adding enumscribe to your project

Add to your Cargo.toml file:

toml [dependencies] enumscribe = "0.1"

Derive macros and serde support are enabled by default. They can be disabled by setting default-features = false.

It is also possible to use the enumscribe_derive crate on its own without using the enumscribe crate. However, doing so means that you will only be able to derive serde::Serialize and serde::Deserialize.

Usage

There are a variety of different traits that you can derive. The "Scribe" traits are for converting from an enum to a string, and the "Unscribe" traits are for converting a string to an enum.

Basic usage

```rust 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 asserteq!(Airport::tryunscribe("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.

Case insensitivity

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

```rust use enumscribe::TryUnscribe;

[derive(TryUnscribe, PartialEq, Eq, Debug)]

enum Website { #[enumscribe(str = "github.com", caseinsensitive)] Github, #[enumscribe(str = "crates.io", caseinsensitive)] CratesDotIo, }

asserteq!(Website::tryunscribe("GiThUb.CoM"), Some(Website::Github)); ```

"other" variant

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.

```rust use std::borrow::Cow;

use enumscribe::{Unscribe, ScribeCowStr};

[derive(ScribeCowStr, Unscribe, PartialEq, Eq, Debug)]

enum Website { #[enumscribe(str = "github.com", caseinsensitive)] Github, #[enumscribe(str = "crates.io", caseinsensitive)] 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 asserteq!(Website::unscribe("stackoverflow.com"), Website::Other("stackoverflow.com".toowned()));

// 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"));

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

Ignoring variants

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.

```rust 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 }

asserteq!(Airport::SecretExtraVariant(123).tryscribe(), None);

asserteq!(Airport::Luton.tryscribe(), Some("LTN")); ```

Serde

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

```rust 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"}"#;

asserteq!(serdejson::tostring(&flight).unwrap(), flightjson.to_owned());

asserteq!(serdejson::fromstr::(flightjson).unwrap(), flight); ```

Traits table

Here is a table to show which traits you should derive, depending on 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.