Merge pull request #44 from alexcrichton/unstable-flags

Rename procmacro2_unstable and proc-macro2/unstable

Author: alexcrichton

.travis.yml

@@ -11,16 +11,16 @@ matrix:
         - pip install 'travis-cargo<0.2' --user && export PATH=$HOME/.local/bin:$PATH
       script:
         - cargo test
-        - cargo build --features unstable
-        - RUSTFLAGS='--cfg procmacro2_unstable' cargo test
-        - RUSTFLAGS='--cfg procmacro2_unstable' cargo build --features unstable
-        - RUSTFLAGS='--cfg procmacro2_unstable' cargo doc --no-deps
+        - cargo build --features nightly
+        - RUSTFLAGS='--cfg procmacro2_semver_exempt' cargo test
+        - RUSTFLAGS='--cfg procmacro2_semver_exempt' cargo build --features nightly
+        - RUSTFLAGS='--cfg procmacro2_semver_exempt' cargo doc --no-deps
       after_success:
         - travis-cargo --only nightly doc-upload
 
 script:
   - cargo test
-  - RUSTFLAGS='--cfg procmacro2_unstable' cargo test
+  - RUSTFLAGS='--cfg procmacro2_semver_exempt' cargo test
 env:
   global:
     - TRAVIS_CARGO_NIGHTLY_FEATURE=""

Cargo.toml

@@ -21,4 +21,13 @@ doctest = false
 unicode-xid = "0.1"
 
 [features]
-unstable = []
+
+# When enabled: act as a shim around the nightly compiler's proc_macro crate.
+# This requires a nightly compiler.
+#
+# When disabled: emulate the same API as the nightly compiler's proc_macro crate
+# but in a way that works on all stable compilers >=1.15.0.
+nightly = []
+
+# Deprecated; use "nightly" instead.
+unstable = ["nightly"]

README.md

@@ -48,7 +48,7 @@ pub fn my_derive(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
 }
 ```
 
-If you'd like you can enable the `unstable` feature in this crate. This will
+If you'd like you can enable the `nightly` feature in this crate. This will
 cause it to compile against the **unstable and nightly-only** features of the
 `proc_macro` crate. This in turn requires a nightly compiler. This should help
 preserve span information, however, coming in from the compiler itself.
@@ -57,19 +57,27 @@ You can enable this feature via:
 
 ```toml
 [dependencies]
-proc-macro2 = { version = "0.1", features = ["unstable"] }
+proc-macro2 = { version = "0.1", features = ["nightly"] }
 ```
 
 
 ## Unstable Features
 
 `proc-macro2` supports exporting some methods from `proc_macro` which are
 currently highly unstable, and may not be stabilized in the first pass of
-`proc_macro` stabilizations. These features are not exported by default.
+`proc_macro` stabilizations. These features are not exported by default. Minor
+versions of `proc-macro2` may make breaking changes to them at any time.
 
-To export these features, the `procmacro2_unstable` config flag must be passed
-to rustc. To pass this flag, run `cargo` with 
-`RUSTFLAGS='--cfg procmacro2_unstable' cargo build`.
+To enable these features, the `procmacro2_semver_exempt` config flag must be
+passed to rustc.
+
+```
+RUSTFLAGS='--cfg procmacro2_semver_exempt' cargo build
+```
+
+Note that this must not only be done for your crate, but for any crate that
+depends on your crate. This infectious nature is intentional, as it serves as a
+reminder that you are outside of the normal semver guarantees.
 
 
 # License

src/lib.rs

@@ -14,31 +14,31 @@
 //! to use this crate will be trivially able to switch to the upstream
 //! `proc_macro` crate once its API stabilizes.
 //!
-//! In the meantime this crate also has an `unstable` Cargo feature which
+//! In the meantime this crate also has a `nightly` Cargo feature which
 //! enables it to reimplement itself with the unstable API of `proc_macro`.
 //! This'll allow immediate usage of the beneficial upstream API, particularly
 //! around preserving span information.
 
-#![cfg_attr(feature = "unstable", feature(proc_macro))]
+#![cfg_attr(feature = "nightly", feature(proc_macro))]
 
 extern crate proc_macro;
 
-#[cfg(not(feature = "unstable"))]
+#[cfg(not(feature = "nightly"))]
 extern crate unicode_xid;
 
 use std::fmt;
 use std::str::FromStr;
 use std::iter::FromIterator;
 
 #[macro_use]
-#[cfg(not(feature = "unstable"))]
+#[cfg(not(feature = "nightly"))]
 mod strnom;
 
 #[path = "stable.rs"]
-#[cfg(not(feature = "unstable"))]
+#[cfg(not(feature = "nightly"))]
 mod imp;
 #[path = "unstable.rs"]
-#[cfg(feature = "unstable")]
+#[cfg(feature = "nightly")]
 mod imp;
 
 #[macro_use]
@@ -104,14 +104,14 @@ impl TokenStream {
 }
 
 // Returned by reference, so we can't easily wrap it.
-#[cfg(procmacro2_unstable)]
+#[cfg(procmacro2_semver_exempt)]
 pub use imp::FileName;
 
-#[cfg(procmacro2_unstable)]
+#[cfg(procmacro2_semver_exempt)]
 #[derive(Clone, PartialEq, Eq)]
 pub struct SourceFile(imp::SourceFile);
 
-#[cfg(procmacro2_unstable)]
+#[cfg(procmacro2_semver_exempt)]
 impl SourceFile {
     /// Get the path to this source file as a string.
     pub fn path(&self) -> &FileName {
@@ -123,21 +123,21 @@ impl SourceFile {
     }
 }
 
-#[cfg(procmacro2_unstable)]
+#[cfg(procmacro2_semver_exempt)]
 impl AsRef<FileName> for SourceFile {
     fn as_ref(&self) -> &FileName {
         self.0.path()
     }
 }
 
-#[cfg(procmacro2_unstable)]
+#[cfg(procmacro2_semver_exempt)]
 impl fmt::Debug for SourceFile {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         self.0.fmt(f)
     }
 }
 
-#[cfg(procmacro2_unstable)]
+#[cfg(procmacro2_semver_exempt)]
 pub struct LineColumn {
     pub line: usize,
     pub column: usize,
@@ -162,30 +162,30 @@ impl Span {
         Span(imp::Span::def_site())
     }
 
-    /// This method is only available when the `"unstable"` feature is enabled.
-    #[cfg(feature = "unstable")]
+    /// This method is only available when the `"nightly"` feature is enabled.
+    #[cfg(feature = "nightly")]
     pub fn unstable(self) -> proc_macro::Span {
         self.0.unstable()
     }
 
-    #[cfg(procmacro2_unstable)]
+    #[cfg(procmacro2_semver_exempt)]
     pub fn source_file(&self) -> SourceFile {
         SourceFile(self.0.source_file())
     }
 
-    #[cfg(procmacro2_unstable)]
+    #[cfg(procmacro2_semver_exempt)]
     pub fn start(&self) -> LineColumn {
         let imp::LineColumn{ line, column } = self.0.start();
         LineColumn { line: line, column: column }
     }
 
-    #[cfg(procmacro2_unstable)]
+    #[cfg(procmacro2_semver_exempt)]
     pub fn end(&self) -> LineColumn {
         let imp::LineColumn{ line, column } = self.0.end();
         LineColumn { line: line, column: column }
     }
 
-    #[cfg(procmacro2_unstable)]
+    #[cfg(procmacro2_semver_exempt)]
     pub fn join(&self, other: Span) -> Option<Span> {
         self.0.join(other.0).map(Span)
     }