std: Stablize the macros module

This commit performs a pass over the `std::macros` module, applying stability
attributes where necessary. In particular, this audits macros for patterns such
as:

* Standard use of forward-to-format-args via `$($arg:tt)*` (or `+`)
* Prevent macro-defined identifiers from leaking into expression arguments as
  hygiene is not perfectly implemented.
* Wherever possible, `$crate` is used now.

Specifically, the following actions were taken:

* The `std::macros` module itself is no longer public.
* The `panic!` macro is stable
* The `assert!` macro is stable
* The `assert_eq!` macro is stable
* The `debug_assert!` macro is stable
* The `debug_assert_eq!` macro is stable
* The `unreachable!` macro is stable after removing the extra forms to bring the
  definition in line with the `unimplemented!` macro.
* The `try!` macro is stable
* The `vec!` macro is stable

[breaking-change]

Author: alexcrichton

src/libcollections/macros.rs

@@ -10,6 +10,7 @@
 
 /// Creates a `Vec` containing the arguments.
 #[macro_export]
+#[stable]
 macro_rules! vec {
     ($($x:expr),*) => ({
         let xs: $crate::boxed::Box<[_]> = box [$($x),*];

src/libstd/lib.rs

@@ -120,8 +120,7 @@
 extern crate log;
 
 #[macro_use]
-#[macro_reexport(assert, assert_eq, debug_assert, debug_assert_eq,
-                 unreachable, unimplemented, write, writeln)]
+#[macro_reexport(write, writeln)]
 extern crate core;
 
 #[macro_use]
@@ -176,7 +175,7 @@ pub use unicode::char;
 /* Exported macros */
 
 #[macro_use]
-pub mod macros;
+mod macros;
 
 #[macro_use]
 pub mod bitflags;

src/libstd/macros.rs

@@ -36,23 +36,27 @@
 /// panic!("this is a {} {message}", "fancy", message = "message");
 /// ```
 #[macro_export]
+#[stable]
 macro_rules! panic {
     () => ({
         panic!("explicit panic")
     });
     ($msg:expr) => ({
-        // static requires less code at runtime, more constant data
-        static _FILE_LINE: (&'static str, uint) = (file!(), line!());
-        ::std::rt::begin_unwind($msg, &_FILE_LINE)
+        $crate::rt::begin_unwind($msg, {
+            // static requires less code at runtime, more constant data
+            static _FILE_LINE: (&'static str, uint) = (file!(), line!());
+            &_FILE_LINE
+        })
     });
-    ($fmt:expr, $($arg:tt)*) => ({
-        // The leading _'s are to avoid dead code warnings if this is
-        // used inside a dead function. Just `#[allow(dead_code)]` is
-        // insufficient, since the user may have
-        // `#[forbid(dead_code)]` and which cannot be overridden.
-        static _FILE_LINE: (&'static str, uint) = (file!(), line!());
-        ::std::rt::begin_unwind_fmt(format_args!($fmt, $($arg)*), &_FILE_LINE)
-
+    ($fmt:expr, $($arg:tt)+) => ({
+        $crate::rt::begin_unwind_fmt(format_args!($fmt, $($arg)+), {
+            // The leading _'s are to avoid dead code warnings if this is
+            // used inside a dead function. Just `#[allow(dead_code)]` is
+            // insufficient, since the user may have
+            // `#[forbid(dead_code)]` and which cannot be overridden.
+            static _FILE_LINE: (&'static str, uint) = (file!(), line!());
+            &_FILE_LINE
+        })
     });
 }
 
@@ -77,15 +81,16 @@ macro_rules! panic {
 /// assert!(a + b == 30, "a = {}, b = {}", a, b);
 /// ```
 #[macro_export]
+#[stable]
 macro_rules! assert {
     ($cond:expr) => (
         if !$cond {
             panic!(concat!("assertion failed: ", stringify!($cond)))
         }
     );
-    ($cond:expr, $($arg:expr),+) => (
+    ($cond:expr, $($arg:tt)+) => (
         if !$cond {
-            panic!($($arg),+)
+            panic!($($arg)+)
         }
     );
 }
@@ -103,6 +108,7 @@ macro_rules! assert {
 /// assert_eq!(a, b);
 /// ```
 #[macro_export]
+#[stable]
 macro_rules! assert_eq {
     ($left:expr , $right:expr) => ({
         match (&($left), &($right)) {
@@ -144,6 +150,7 @@ macro_rules! assert_eq {
 /// debug_assert!(a + b == 30, "a = {}, b = {}", a, b);
 /// ```
 #[macro_export]
+#[stable]
 macro_rules! debug_assert {
     ($($arg:tt)*) => (if cfg!(not(ndebug)) { assert!($($arg)*); })
 }
@@ -210,6 +217,7 @@ macro_rules! debug_assert_eq {
 /// }
 /// ```
 #[macro_export]
+#[unstable = "relationship with panic is unclear"]
 macro_rules! unreachable {
     () => ({
         panic!("internal error: entered unreachable code")
@@ -225,6 +233,7 @@ macro_rules! unreachable {
 /// A standardised placeholder for marking unfinished code. It panics with the
 /// message `"not yet implemented"` when executed.
 #[macro_export]
+#[unstable = "relationship with panic is unclear"]
 macro_rules! unimplemented {
     () => (panic!("not yet implemented"))
 }
@@ -242,15 +251,15 @@ macro_rules! unimplemented {
 #[macro_export]
 #[stable]
 macro_rules! format {
-    ($($arg:tt)*) => (::std::fmt::format(format_args!($($arg)*)))
+    ($($arg:tt)*) => ($crate::fmt::format(format_args!($($arg)*)))
 }
 
 /// Equivalent to the `println!` macro except that a newline is not printed at
 /// the end of the message.
 #[macro_export]
 #[stable]
 macro_rules! print {
-    ($($arg:tt)*) => (::std::io::stdio::print_args(format_args!($($arg)*)))
+    ($($arg:tt)*) => ($crate::io::stdio::print_args(format_args!($($arg)*)))
 }
 
 /// Macro for printing to a task's stdout handle.
@@ -268,20 +277,19 @@ macro_rules! print {
 #[macro_export]
 #[stable]
 macro_rules! println {
-    ($($arg:tt)*) => (::std::io::stdio::println_args(format_args!($($arg)*)))
+    ($($arg:tt)*) => ($crate::io::stdio::println_args(format_args!($($arg)*)))
 }
 
 /// Helper macro for unwrapping `Result` values while returning early with an
 /// error if the value of the expression is `Err`. For more information, see
 /// `std::io`.
 #[macro_export]
+#[stable]
 macro_rules! try {
-    ($expr:expr) => ({
-        use $crate::result::Result::{Ok, Err};
-
-        match $expr {
-            Ok(val) => val,
-            Err(err) => return Err($crate::error::FromError::from_error(err)),
+    ($expr:expr) => (match $expr {
+        $crate::result::Result::Ok(val) => val,
+        $crate::result::Result::Err(err) => {
+            return $crate::result::Result::Err($crate::error::FromError::from_error(err))
         }
     })
 }
@@ -412,26 +420,6 @@ pub mod builtin {
     #[macro_export]
     macro_rules! option_env { ($name:expr) => ({ /* compiler built-in */ }) }
 
-    /// Concatenate literals into a static byte slice.
-    ///
-    /// This macro takes any number of comma-separated literal expressions,
-    /// yielding an expression of type `&'static [u8]` which is the
-    /// concatenation (left to right) of all the literals in their byte format.
-    ///
-    /// This extension currently only supports string literals, character
-    /// literals, and integers less than 256. The byte slice returned is the
-    /// utf8-encoding of strings and characters.
-    ///
-    /// # Example
-    ///
-    /// ```
-    /// let rust = bytes!("r", 'u', "st", 255);
-    /// assert_eq!(rust[1], b'u');
-    /// assert_eq!(rust[4], 255);
-    /// ```
-    #[macro_export]
-    macro_rules! bytes { ($($e:expr),*) => ({ /* compiler built-in */ }) }
-
     /// Concatenate identifiers into one identifier.
     ///
     /// This macro takes any number of comma-separated identifiers, and
@@ -565,10 +553,6 @@ pub mod builtin {
     #[macro_export]
     macro_rules! include_bytes { ($file:expr) => ({ /* compiler built-in */ }) }
 
-    /// Deprecated alias for `include_bytes!()`.
-    #[macro_export]
-    macro_rules! include_bin { ($file:expr) => ({ /* compiler built-in */}) }
-
     /// Expands to a string that represents the current module path.
     ///
     /// The current module path can be thought of as the hierarchy of modules

src/libsyntax/ext/base.rs

@@ -341,9 +341,6 @@ fn initial_syntax_expander_table(ecfg: &expand::ExpansionConfig) -> SyntaxEnv {
 
     let mut syntax_expanders = SyntaxEnv::new();
     syntax_expanders.insert(intern("macro_rules"), MacroRulesTT);
-    syntax_expanders.insert(intern("fmt"),
-                            builtin_normal_expander(
-                                ext::fmt::expand_syntax_ext));
     syntax_expanders.insert(intern("format_args"),
                             builtin_normal_expander(
                                 ext::format::expand_format_args));
@@ -353,9 +350,6 @@ fn initial_syntax_expander_table(ecfg: &expand::ExpansionConfig) -> SyntaxEnv {
     syntax_expanders.insert(intern("option_env"),
                             builtin_normal_expander(
                                     ext::env::expand_option_env));
-    syntax_expanders.insert(intern("bytes"),
-                            builtin_normal_expander(
-                                    ext::bytes::expand_syntax_ext));
     syntax_expanders.insert(intern("concat_idents"),
                             builtin_normal_expander(
                                     ext::concat_idents::expand_syntax_ext));
@@ -367,8 +361,6 @@ fn initial_syntax_expander_table(ecfg: &expand::ExpansionConfig) -> SyntaxEnv {
                                     ext::log_syntax::expand_syntax_ext));
     syntax_expanders.insert(intern("derive"),
                             Decorator(box ext::deriving::expand_meta_derive));
-    syntax_expanders.insert(intern("deriving"),
-                            Decorator(box ext::deriving::expand_meta_deriving));
 
     if ecfg.enable_quotes {
         // Quasi-quoting expanders
@@ -416,9 +408,6 @@ fn initial_syntax_expander_table(ecfg: &expand::ExpansionConfig) -> SyntaxEnv {
     syntax_expanders.insert(intern("include_str"),
                             builtin_normal_expander(
                                     ext::source_util::expand_include_str));
-    syntax_expanders.insert(intern("include_bin"),
-                            builtin_normal_expander(
-                                    ext::source_util::expand_include_bin));
     syntax_expanders.insert(intern("include_bytes"),
                             builtin_normal_expander(
                                     ext::source_util::expand_include_bytes));

src/libsyntax/ext/bytes.rs

@@ -40,16 +40,6 @@ pub mod totalord;
 
 pub mod generic;
 
-pub fn expand_meta_deriving(cx: &mut ExtCtxt,
-                            _span: Span,
-                            mitem: &MetaItem,
-                            item: &Item,
-                            push: Box<FnMut(P<Item>)>) {
-    cx.span_warn(mitem.span, "`deriving` is deprecated; use `derive`");
-
-    expand_meta_derive(cx, _span, mitem, item, push)
-}
-
 pub fn expand_meta_derive(cx: &mut ExtCtxt,
                           _span: Span,
                           mitem: &MetaItem,