https://github.com/taiki-e/easy-ext
A lightweight attribute macro for easily writing extension trait pattern.
https://github.com/taiki-e/easy-ext
no-std proc-macro rust
Last synced: 10 months ago
JSON representation
A lightweight attribute macro for easily writing extension trait pattern.
- Host: GitHub
- URL: https://github.com/taiki-e/easy-ext
- Owner: taiki-e
- License: apache-2.0
- Created: 2019-02-20T18:49:55.000Z (almost 7 years ago)
- Default Branch: main
- Last Pushed: 2024-10-20T18:54:23.000Z (over 1 year ago)
- Last Synced: 2024-10-20T23:28:17.871Z (over 1 year ago)
- Topics: no-std, proc-macro, rust
- Language: Rust
- Homepage: https://docs.rs/easy-ext
- Size: 412 KB
- Stars: 45
- Watchers: 4
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE-APACHE
Awesome Lists containing this project
README
# easy-ext
[](https://crates.io/crates/easy-ext)
[](https://docs.rs/easy-ext)
[](#license)
[](https://www.rust-lang.org)
[](https://github.com/taiki-e/easy-ext/actions)
A lightweight attribute macro for easily writing [extension trait pattern][rfc0445].
```toml
[dependencies]
easy-ext = "1"
```
## Examples
```rust
use easy_ext::ext;
#[ext(ResultExt)]
pub impl Result {
fn err_into(self) -> Result
where
E: Into,
{
self.map_err(Into::into)
}
}
```
Code like this will be generated:
```rust
pub trait ResultExt {
fn err_into(self) -> Result
where
E: Into;
}
impl ResultExt for Result {
fn err_into(self) -> Result
where
E: Into,
{
self.map_err(Into::into)
}
}
```
You can elide the trait name.
```rust
use easy_ext::ext;
#[ext]
impl Result {
fn err_into(self) -> Result
where
E: Into,
{
self.map_err(Into::into)
}
}
```
Note that in this case, `#[ext]` assigns a random name, so you cannot
import/export the generated trait.
### Visibility
There are two ways to specify visibility.
#### Impl-level visibility
The first way is to specify visibility at the impl level. For example:
```rust
use easy_ext::ext;
// unnamed
#[ext]
pub impl str {
fn foo(&self) {}
}
// named
#[ext(StrExt)]
pub impl str {
fn bar(&self) {}
}
```
#### Associated-item-level visibility
Another way is to specify visibility at the associated item level.
For example, if the method is `pub` then the trait will also be `pub`:
```rust
use easy_ext::ext;
#[ext(ResultExt)] // generate `pub trait ResultExt`
impl Result {
pub fn err_into(self) -> Result
where
E: Into,
{
self.map_err(Into::into)
}
}
```
This is useful when migrate from an inherent impl to an extension trait.
Note that the visibility of all the associated items in the `impl` must be identical.
Note that you cannot specify impl-level visibility and associated-item-level visibility at the same time.
### [Supertraits](https://doc.rust-lang.org/reference/items/traits.html#supertraits)
If you want the extension trait to be a subtrait of another trait,
add `Self: SubTrait` bound to the `where` clause.
```rust
use easy_ext::ext;
#[ext(Ext)]
impl T
where
Self: Default,
{
fn method(&self) {}
}
```
### Supported items
#### [Associated functions (methods)](https://doc.rust-lang.org/reference/items/associated-items.html#associated-functions-and-methods)
```rust
use easy_ext::ext;
#[ext]
impl T {
fn method(&self) {}
}
```
#### [Associated constants](https://doc.rust-lang.org/reference/items/associated-items.html#associated-constants)
```rust
use easy_ext::ext;
#[ext]
impl T {
const MSG: &'static str = "Hello!";
}
```
#### [Associated types](https://doc.rust-lang.org/reference/items/associated-items.html#associated-types)
```rust
use easy_ext::ext;
#[ext]
impl str {
type Owned = String;
fn method(&self) -> Self::Owned {
self.to_owned()
}
}
```
[rfc0445]: https://rust-lang.github.io/rfcs/0445-extension-trait-conventions.html
## License
Licensed under either of [Apache License, Version 2.0](LICENSE-APACHE) or
[MIT license](LICENSE-MIT) at your option.
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.