Skip to content

Latest commit

 

History

History
116 lines (88 loc) · 3.79 KB

README.md

File metadata and controls

116 lines (88 loc) · 3.79 KB

qualifier_attr

Latest Version Downloads Documentation License Dependency Status

Procedural macro attributes for adding "qualifiers" to various items.

At the moment, the crate supports the following "qualifiers":

  • pub, pub(crate), etc. - visibility and restriction
  • default - default implementations (a feature of specialization)
  • async - asynchronous code, e.g. async fn
  • unsafe - unsafe code, e.g. unsafe fn, unsafe trait
  • const - code that may run at compile time, e.g. const fn
  • extern "ABI" - specifying an ABI, e.g. extern "C" fn

Limitations

Examples

#[macro_use]
extern crate qualifier_attr;

// We can add a qualifier to a function
// with an attribute.
#[qualifiers(const)]
fn const_fn() -> u32 {
    42
}

const CONST_RES: u32 = const_fn();

// It's not so impressive on its own,
// but with `cfg_attr`, it can be conditional.
#[cfg_attr(feature = "extern_c", no_mangle, qualifiers(pub, extern "C"))]
fn extern_c_fn() -> u32 {
    42
}

// It even works with types, imports, and more!
mod foo {
    #[qualifiers(pub)]
    struct Foo {
        x: i32,
        y: i32,
    }
}

#[qualifiers(pub)]
use foo::Foo;

// Traits and implementations too!?
#[cfg_attr(feature = "unsafe_quux", qualifiers(unsafe))]
trait Quux {
    fn quux_the_thing();
}

#[cfg_attr(feature = "unsafe_quux", qualifiers(unsafe))]
impl Quux for Foo {
    fn quux_the_thing() {
        println!("The thing was quuxed.");
    }
}

// You can add qualifiers to the fields of a
// struct as well with this special attribute.
#[field_qualifiers(x(pub), y(pub))]
struct Point2 {
    x: i32,
    y: i32,
}

#[field_qualifiers(_0(pub), _1(pub), _2(pub))]
struct Point3(i32, i32, i32);

Learn more about cfg_attr here.

Note on legacy attributes

Before version 0.2.0, this crate provided a separate attribute for each kind of item. While this should generally be a small win for compile times, it is generally not justified by the additional complexity. The legacy attributes are still available behind the default legacy_attrs feature flag, but their use is currently discouraged. In order to disable the legacy attributes, add the following to your Cargo.toml:

[dependencies]
qualifier_attr = { version = "0.2", default-features = false }

Similar crates

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.