auto_enums

A library for to allow multiple return types by automatically generated enum.

This crate is a procedural macro implementation of the features discussions in rust-lang/rfcs#2414.

This library provides the following attribute macros:

• #[auto_enum]

  Parses syntax, creates the enum, inserts variants, and passes specified traits to #[enum_derive].

• #[enum_derive]

  Implements specified traits to the enum.

Usage

Add this to your Cargo.toml:

[dependencies]
auto_enums = "0.6"

The current auto_enums requires Rust 1.31 or later.

Examples

#[auto_enum]'s basic feature is to wrap the value returned by the obvious branches (match, if, return, etc..) by an enum that implemented the specified traits.

use auto_enums::auto_enum;

#[auto_enum(Iterator)]
fn foo(x: i32) -> impl Iterator<Item = i32> {
    match x {
        0 => 1..10,
        _ => vec![5, 10].into_iter(),
    }
}

#[auto_enum] generates code in two stages.

First, #[auto_enum] will do the following.

• parses syntax
• creates the enum
• inserts variants

Code like this will be generated:

fn foo(x: i32) -> impl Iterator<Item = i32> {
    #[::auto_enums::enum_derive(Iterator)]
    enum __Enum1<__T1, __T2> {
        __T1(__T1),
        __T2(__T2),
    }

    match x {
        0 => __Enum1::__T1(1..10),
        _ => __Enum1::__T2(vec![5, 10].into_iter()),
    }
}

Next, #[enum_derive] implements the specified traits.

Code like this will be generated

#[auto_enum] can also parse nested arms/branches by using the #[nested] attribute.

use auto_enums::auto_enum;
#[auto_enum(Iterator)]
fn foo(x: i32) -> impl Iterator<Item = i32> {
    match x {
        0 => 1..10,
        #[nested]
        _ => match x {
            1 => vec![5, 10].into_iter(),
            _ => 0..=x,
        },
    }
}

See API Documentation for more details.

Supported traits

#[enum_derive] implements the supported traits and passes unsupported traits to #[derive].

If you want to use traits that are not supported by #[enum_derive], you can use another crate that provides proc_macro_derive, or you can define proc_macro_derive yourself (derive_utils probably can help it).

Basic usage of #[enum_derive]

use auto_enums::enum_derive;

// `#[enum_derive]` implements `Iterator`, and `#[derive]` implements `Clone`.
#[enum_derive(Iterator, Clone)]
enum Foo<A, B> {
    A(A),
    B(B),
}

[std|core] libraries

Some traits support is disabled by default. Note that some traits have aliases.

When using features that depend on unstable APIs, the "unstable" feature must be explicitly enabled

[std|core]::iter

• Iterator - generated code
• DoubleEndedIterator - generated code
• ExactSizeIterator - generated code
• FusedIterator - generated code
• Extend - generated code
• TrustedLen - generated code (requires "trusted_len" and "unstable" crate features)

[std|core]::future

• Future - generated code

std::io

• Read (alias: io::Read) - generated code
• BufRead (alias: io::BufRead) - generated code
• Write (alias: io::Write) - generated code
• Seek (alias: io::Seek) - generated code

[std|core]::ops

• Deref (requires "ops" crate feature)
• DerefMut (requires "ops" crate feature)
• Index (requires "ops" crate feature)
• IndexMut (requires "ops" crate feature)
• RangeBounds (requires "ops" crate feature)
• Fn (requires "fn_traits" and "unstable" crate features)
• FnMut (requires "fn_traits" and "unstable" crate features)
• FnOnce (requires "fn_traits" and "unstable" crate features)
• Generator (requires "generator_trait" and "unstable" crate features)

[std|core]::convert

• AsRef (requires "convert" crate feature)
• AsMut (requires "convert" crate feature)

[std|core]::fmt

• Debug (alias: fmt::Debug) - generated code
• Display (alias: fmt::Display)
• fmt::Binary (requires "fmt" crate feature)
• fmt::LowerExp (requires "fmt" crate feature)
• fmt::LowerHex (requires "fmt" crate feature)
• fmt::Octal (requires "fmt" crate feature)
• fmt::Pointer (requires "fmt" crate feature)
• fmt::UpperExp (requires "fmt" crate feature)
• fmt::UpperHex (requires "fmt" crate feature)
• fmt::Write

std::error

• Error - generated code

External libraries

You can add support for external library by activating the each crate feature.

futures(v0.3) (requires "futures" and "unstable" crate features)

• futures::Stream - generated code
• futures::Sink - generated code
• futures::AsyncRead - generated code
• futures::AsyncWrite - generated code
• futures::AsyncSeek - generated code
• futures::AsyncBufRead - generated code

futures(v0.1) (requires "futures01" crate feature)

• futures01::Future
• futures01::Stream
• futures01::Sink

rayon (requires "rayon" crate feature)

• rayon::ParallelIterator - generated code
• rayon::IndexedParallelIterator - generated code
• rayon::ParallelExtend - generated code

serde (requires "serde" crate feature)

• serde::Serialize - generated code

License

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.