2017-02-12 07:46:32 +01:00
|
|
|
# Strum
|
|
|
|
|
2020-09-17 20:21:41 +02:00
|
|
|
[![Build Status](https://travis-ci.com/Peternator7/strum.svg?branch=master)](https://travis-ci.com/Peternator7/strum)
|
|
|
|
[![Build status](https://ci.appveyor.com/api/projects/status/ji4f6n2m5lvu11xt?svg=true)](https://ci.appveyor.com/project/Peternator7/strum)
|
2017-02-12 08:00:43 +01:00
|
|
|
[![Latest Version](https://img.shields.io/crates/v/strum.svg)](https://crates.io/crates/strum)
|
2017-02-12 08:03:42 +01:00
|
|
|
[![Rust Documentation](https://docs.rs/strum/badge.svg)](https://docs.rs/strum)
|
2020-09-17 20:21:41 +02:00
|
|
|
![Crates.io](https://img.shields.io/crates/l/strum)
|
|
|
|
![Crates.io](https://img.shields.io/crates/d/strum)
|
2017-02-12 08:00:43 +01:00
|
|
|
|
2019-09-18 20:24:14 +02:00
|
|
|
Strum is a set of macros and traits for working with enums and strings easier in Rust.
|
2017-02-12 07:46:32 +01:00
|
|
|
|
2019-03-04 08:27:59 +01:00
|
|
|
# Compatibility
|
|
|
|
|
2019-09-18 20:24:14 +02:00
|
|
|
Strum is compatible with versions of rustc >= 1.31.0. That's the earliest version of stable rust that supports
|
2019-03-04 08:27:59 +01:00
|
|
|
impl trait. Pull Requests that improve compatibility with older versions are welcome, but new feature work
|
|
|
|
will focus on the current version of rust with an effort to avoid breaking compatibility with older versions.
|
|
|
|
|
2017-02-12 07:46:32 +01:00
|
|
|
# Including Strum in Your Project
|
|
|
|
|
|
|
|
Import strum and strum_macros into your project by adding the following lines to your
|
|
|
|
Cargo.toml. Strum_macros contains the macros needed to derive all the traits in Strum.
|
|
|
|
|
|
|
|
```toml
|
|
|
|
[dependencies]
|
2020-08-03 23:05:09 +02:00
|
|
|
strum = "0.19"
|
|
|
|
strum_macros = "0.19"
|
2017-02-12 07:46:32 +01:00
|
|
|
```
|
|
|
|
|
2019-09-18 20:24:14 +02:00
|
|
|
# Strum Macros
|
|
|
|
|
|
|
|
Strum has implemented the following macros:
|
|
|
|
|
|
|
|
| Macro | Description |
|
|
|
|
| --- | ----------- |
|
|
|
|
| [EnumString] | Converts strings to enum variants based on their name |
|
|
|
|
| [Display] | Converts enum variants to strings |
|
|
|
|
| [AsRefStr] | Converts enum variants to `&'static str` |
|
|
|
|
| [IntoStaticStr] | Implements `From<MyEnum> for &'static str` on an enum |
|
2019-12-20 00:18:17 +01:00
|
|
|
| [EnumVariantNames] | Adds an associated `VARIANTS` constant which is an array of discriminant names |
|
2019-09-18 20:24:14 +02:00
|
|
|
| [EnumIter] | Creates a new type that iterates of the variants of an enum. |
|
|
|
|
| [EnumProperty] | Add custom properties to enum variants. |
|
|
|
|
| [EnumMessage] | Add a verbose message to an enum variant. |
|
|
|
|
| [EnumDiscriminants] | Generate a new type with only the discriminant names. |
|
2019-12-12 19:54:32 +01:00
|
|
|
| [EnumCount] | Add a constant `usize` equal to the number of variants. |
|
2019-09-18 20:24:14 +02:00
|
|
|
|
2017-02-16 06:16:16 +01:00
|
|
|
# Contributing
|
|
|
|
|
2017-06-29 22:51:50 +02:00
|
|
|
Thanks for your interest in contributing. The project is divided into 3 parts, the traits are in the
|
|
|
|
`/strum` folder. The procedural macros are in the `/strum_macros` folder, and the integration tests are
|
|
|
|
in `/strum_tests`. If you are adding additional features to `strum` or `strum_macros`, you should make sure
|
2017-02-23 09:09:57 +01:00
|
|
|
to run the tests and add new integration tests to make sure the features work as expected.
|
2017-02-16 06:16:16 +01:00
|
|
|
|
|
|
|
# Debugging
|
|
|
|
|
|
|
|
To see the generated code, set the STRUM_DEBUG environment variable before compiling your code.
|
|
|
|
`STRUM_DEBUG=1` will dump all of the generated code for every type. `STRUM_DEBUG=YourType` will
|
|
|
|
only dump the code generated on a type named `YourType`.
|
|
|
|
|
2017-02-12 07:46:32 +01:00
|
|
|
# Name
|
|
|
|
|
|
|
|
Strum is short for STRing enUM because it's a library for augmenting enums with additional
|
|
|
|
information through strings.
|
|
|
|
|
2017-02-12 21:52:51 +01:00
|
|
|
Strumming is also a very whimsical motion, much like writing Rust code.
|
2019-09-18 20:24:14 +02:00
|
|
|
|
|
|
|
[Macro-Renames]: https://github.com/Peternator7/strum/wiki/Macro-Renames
|
|
|
|
[EnumString]: https://github.com/Peternator7/strum/wiki/Derive-EnumString
|
|
|
|
[Display]: https://github.com/Peternator7/strum/wiki/Derive-Display
|
|
|
|
[AsRefStr]: https://github.com/Peternator7/strum/wiki/Derive-AsRefStr
|
|
|
|
[IntoStaticStr]: https://github.com/Peternator7/strum/wiki/Derive-IntoStaticStr
|
|
|
|
[EnumVariantNames]: https://github.com/Peternator7/strum/wiki/Derive-EnumVariantNames
|
|
|
|
[EnumIter]: https://github.com/Peternator7/strum/wiki/Derive-EnumIter
|
|
|
|
[EnumProperty]: https://github.com/Peternator7/strum/wiki/Derive-EnumProperty
|
|
|
|
[EnumMessage]: https://github.com/Peternator7/strum/wiki/Derive-EnumMessage
|
|
|
|
[EnumDiscriminants]: https://github.com/Peternator7/strum/wiki/Derive-EnumDiscriminants
|
|
|
|
[EnumCount]: https://github.com/Peternator7/strum/wiki/Derive-EnumCount
|