Add a guide to compiler plugins

Fixes #16983.

src/test/auxiliary/roman_numerals.rs

@@ -0,0 +1,70 @@
+// Copyright 2014 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+// force-host
+
+#![crate_type="dylib"]
+#![feature(plugin_registrar)]
+
+extern crate syntax;
+extern crate rustc;
+
+use syntax::codemap::Span;
+use syntax::parse::token::{IDENT, get_ident};
+use syntax::ast::{TokenTree, TTTok};
+use syntax::ext::base::{ExtCtxt, MacResult, DummyResult, MacExpr};
+use syntax::ext::build::AstBuilder;  // trait for expr_uint
+use rustc::plugin::Registry;
+
+// WARNING WARNING WARNING WARNING WARNING
+// =======================================
+//
+// This code also appears in src/doc/guide-plugin.md. Please keep
+// the two copies in sync!  FIXME: have rustdoc read this file
+
+fn expand_rn(cx: &mut ExtCtxt, sp: Span, args: &[TokenTree])
+        -> Box<MacResult + 'static> {
+
+    static NUMERALS: &'static [(&'static str, uint)] = &[
+        ("M", 1000), ("CM", 900), ("D", 500), ("CD", 400),
+        ("C",  100), ("XC",  90), ("L",  50), ("XL",  40),
+        ("X",   10), ("IX",   9), ("V",   5), ("IV",   4),
+        ("I",    1)];
+
+    let text = match args {
+        [TTTok(_, IDENT(s, _))] => get_ident(s).to_string(),
+        _ => {
+            cx.span_err(sp, "argument should be a single identifier");
+            return DummyResult::any(sp);
+        }
+    };
+
+    let mut text = text.as_slice();
+    let mut total = 0u;
+    while !text.is_empty() {
+        match NUMERALS.iter().find(|&&(rn, _)| text.starts_with(rn)) {
+            Some(&(rn, val)) => {
+                total += val;
+                text = text.slice_from(rn.len());
+            }
+            None => {
+                cx.span_err(sp, "invalid Roman numeral");
+                return DummyResult::any(sp);
+            }
+        }
+    }
+
+    MacExpr::new(cx.expr_uint(sp, total))
+}
+
+#[plugin_registrar]
+pub fn plugin_registrar(reg: &mut Registry) {
+    reg.register_macro("rn", expand_rn);
+}

src/test/run-pass-fulldeps/roman-numerals-macro.rs

@@ -0,0 +1,26 @@
+// Copyright 2014 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+// aux-build:roman_numerals.rs
+// ignore-stage1
+
+#![feature(phase)]
+
+#[phase(plugin, link)]
+extern crate roman_numerals;
+
+pub fn main() {
+    assert_eq!(rn!(MMXV), 2015);
+    assert_eq!(rn!(MCMXCIX), 1999);
+    assert_eq!(rn!(XXV), 25);
+    assert_eq!(rn!(MDCLXVI), 1666);
+    assert_eq!(rn!(MMMDCCCLXXXVIII), 3888);
+    assert_eq!(rn!(MMXIV), 2014);
+}