diff --git a/.travis.yml b/.travis.yml index 35cca71e..363fea9a 100644 --- a/.travis.yml +++ b/.travis.yml @@ -5,6 +5,7 @@ before_script: - (test -x $HOME/.cargo/bin/cargo-install-update || cargo install cargo-update) - (test -x $HOME/.cargo/bin/mdbook || cargo install mdbook) - cargo install-update -a + - mdbook --version script: - mdbook build - mdbook test diff --git a/src/rust-2018/macros/macro-changes.md b/src/rust-2018/macros/macro-changes.md index 1d43db67..c0688062 100644 --- a/src/rust-2018/macros/macro-changes.md +++ b/src/rust-2018/macros/macro-changes.md @@ -2,6 +2,8 @@ ![Minimum Rust version: beta](https://img.shields.io/badge/Minimum%20Rust%20Version-beta-orange.svg) +## `macro_rules!` style macros + In Rust 2018, you can import specific macros from external crates via `use` statements, rather than the old `#[macro_use]` attribute. @@ -78,3 +80,192 @@ struct Bar; This only works for macros defined in external crates. For macros defined locally, `#[macro_use] mod foo;` is still required, as it was in Rust 2015. + +### Local helper macros + +Sometimes it is helpful or necessary to have helper macros inside your module. This can make +supporting both versions of rust more complicated. + +For example, let's make a simplified (and slightly contrived) version of the `log` crate in 2015 +edition style: + +```rust +use std::fmt; + +/// How important/severe the log message is. +#[derive(Copy, Clone)] +pub enum LogLevel { + Warn, + Error +} + +impl fmt::Display for LogLevel { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + match self { + LogLevel::Warn => write!(f, "warning"), + LogLevel::Error => write!(f, "error"), + } + } +} + +// A helper macro to log the message. +#[doc(hidden)] +#[macro_export] +macro_rules! __impl_log { + ($level:expr, $msg:expr) => {{ + println!("{}: {}", $level, $msg) + }} +} + +/// Warn level log message +#[macro_export] +macro_rules! warn { + ($($args:tt)*) => { + __impl_log!($crate::LogLevel::Warn, format_args!($($args)*)) + } +} + +/// Error level log message +#[macro_export] +macro_rules! error { + ($($args:tt)*) => { + __impl_log!($crate::LogLevel::Error, format_args!($($args)*)) + } +} +``` + +Our `__impl_log!` macro is private to our module, but needs to be exported as it is called by other +macros, and in 2015 edition all used macros must be exported. + +Now, in 2018 this example will not compile: + +```rust,ignore +use log::error; + +fn main() { + error!("error message"); +} +``` + +will give an error message about not finding the `__impl_log!` macro. This is because unlike in +the 2015 edition, macros are namespaced and we must import them. We could do + +```rust,ignore +use log::{__impl_log, error}; +``` + +which would make our code compile, but `__impl_log` is meant to be an implementation detail! + +#### Macros with `$crate::` prefix. + +The cleanest way to handle this situation is to use the `$crate::` prefix for macros, the same as +you would for any other path. Versions of the compiler >= 1.30 will handle this in both editions: + +```rust +macro_rules! warn { + ($($args:tt)*) => { + $crate::__impl_log!($crate::LogLevel::Warn, format_args!($($args)*)) + } +} + +// ... +``` + +However, this will not work for older versions of the compiler that don't understand the +`$crate::` prefix for macros. + +#### Macros using `local_inner_macros` + +We also have the `local_inner_macros` modifier that we can add to our `#[macro_export]` attribute. +This has the advantage of working with older rustc versions (older versions just ignore the extra +modifier). The downside is that it's a bit messier: + +```rust,ignore +#[macro_export(local_inner_macros)] +macro_rules! warn { + ($($args:tt)*) => { + __impl_log!($crate::LogLevel::Warn, format_args!($($args)*)) + } +} +``` + +So the code knows to look for any macros used locally. But wait - this won't compile, because we +use the `format_args!` macro that isn't in our local crate (hence the convoluted example). The +solution is to add a level of indirection: we create a macro that wraps `format_args`, but is local +to our crate. That way everything works in both editions (sadly we have to pollute the global +namespace a bit, but that's ok). + +```rust +// I've used the pattern `___` to name this macro, hopefully avoiding +// name clashes. +#[doc(hidden)] +#[macro_export] +macro_rules! _log__format_args { + ($($inner:tt)*) => { + format_args! { $($inner)* } + } +} +``` + +Here we're using the most general macro pattern possible, a list of token trees. We just pass +whatever tokens we get to the inner macro, and rely on it to report errors. + +So the full 2015/2018 working example would be: + +```rust +use std::fmt; + +/// How important/severe the log message is. +#[derive(Debug, Copy, Clone)] +pub enum LogLevel { + Warn, + Error +} + +impl fmt::Display for LogLevel { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + match self { + LogLevel::Warn => write!(f, "warning"), + LogLevel::Error => write!(f, "error"), + } + } +} + +// A helper macro to log the message. +#[doc(hidden)] +#[macro_export] +macro_rules! __impl_log { + ($level:expr, $msg:expr) => {{ + println!("{}: {}", $level, $msg) + }} +} + +/// Warn level log message +#[macro_export(local_inner_macros)] +macro_rules! warn { + ($($args:tt)*) => { + __impl_log!($crate::LogLevel::Warn, _log__format_args!($($args)*)) + } +} + +/// Error level log message +#[macro_export(local_inner_macros)] +macro_rules! error { + ($($args:tt)*) => { + __impl_log!($crate::LogLevel::Error, _log__format_args!($($args)*)) + } +} + +#[doc(hidden)] +#[macro_export] +macro_rules! _log__format_args { + ($($inner:tt)*) => { + format_args! { $($inner)* } + } +} +``` + +Once everyone is using a rustc version >= 1.30, we can all just use the `$crate::` method (2015 +crates are guaranteed to carry on compiling fine with later versions of the compiler). We need to +wait for package managers and larger organisations to update their compilers before this happens, +so in the mean time we can use the `local_inner_macros` method to support everybody. :)