src/doc/unstable-book/src/language-features/plugin.md

   1 # `plugin`
   2
   3 The tracking issue for this feature is: [#29597]
   4
   5 [#29597]: https://github.com/rust-lang/rust/issues/29597
   6
   7
   8 This feature is part of "compiler plugins." It will often be used with the
   9 [`plugin_registrar`] and `rustc_private` features.
  10
  11 [`plugin_registrar`]: plugin-registrar.md
  12
  13 ------------------------
  14
  15 `rustc` can load compiler plugins, which are user-provided libraries that
  16 extend the compiler's behavior with new syntax extensions, lint checks, etc.
  17
  18 A plugin is a dynamic library crate with a designated *registrar* function that
  19 registers extensions with `rustc`. Other crates can load these extensions using
  20 the crate attribute `#![plugin(...)]`.  See the
  21 `rustc_plugin` documentation for more about the
  22 mechanics of defining and loading a plugin.
  23
  24 If present, arguments passed as `#![plugin(foo(... args ...))]` are not
  25 interpreted by rustc itself.  They are provided to the plugin through the
  26 `Registry`'s `args` method.
  27
  28 In the vast majority of cases, a plugin should *only* be used through
  29 `#![plugin]` and not through an `extern crate` item.  Linking a plugin would
  30 pull in all of libsyntax and librustc as dependencies of your crate.  This is
  31 generally unwanted unless you are building another plugin.  The
  32 `plugin_as_library` lint checks these guidelines.
  33
  34 The usual practice is to put compiler plugins in their own crate, separate from
  35 any `macro_rules!` macros or ordinary Rust code meant to be used by consumers
  36 of a library.
  37
  38 # Syntax extensions
  39
  40 Plugins can extend Rust's syntax in various ways. One kind of syntax extension
  41 is the procedural macro. These are invoked the same way as [ordinary
  42 macros](../../book/macros.md), but the expansion is performed by arbitrary Rust
  43 code that manipulates syntax trees at
  44 compile time.
  45
  46 Let's write a plugin
  47 [`roman_numerals.rs`](https://github.com/rust-lang/rust/blob/master/src/test/run-pass-fulldeps/auxiliary/roman_numerals.rs)
  48 that implements Roman numeral integer literals.
  49
  50 ```rust,ignore
  51 #![crate_type="dylib"]
  52 #![feature(plugin_registrar, rustc_private)]
  53
  54 extern crate syntax;
  55 extern crate syntax_pos;
  56 extern crate rustc;
  57 extern crate rustc_plugin;
  58
  59 use syntax::parse::token;
  60 use syntax::tokenstream::TokenTree;
  61 use syntax::ext::base::{ExtCtxt, MacResult, DummyResult, MacEager};
  62 use syntax::ext::build::AstBuilder;  // A trait for expr_usize.
  63 use syntax_pos::Span;
  64 use rustc_plugin::Registry;
  65
  66 fn expand_rn(cx: &mut ExtCtxt, sp: Span, args: &[TokenTree])
  67         -> Box<MacResult + 'static> {
  68
  69     static NUMERALS: &'static [(&'static str, usize)] = &[
  70         ("M", 1000), ("CM", 900), ("D", 500), ("CD", 400),
  71         ("C",  100), ("XC",  90), ("L",  50), ("XL",  40),
  72         ("X",   10), ("IX",   9), ("V",   5), ("IV",   4),
  73         ("I",    1)];
  74
  75     if args.len() != 1 {
  76         cx.span_err(
  77             sp,
  78             &format!("argument should be a single identifier, but got {} arguments", args.len()));
  79         return DummyResult::any(sp);
  80     }
  81
  82     let text = match args[0] {
  83         TokenTree::Token(_, token::Ident(s)) => s.to_string(),
  84         _ => {
  85             cx.span_err(sp, "argument should be a single identifier");
  86             return DummyResult::any(sp);
  87         }
  88     };
  89
  90     let mut text = &*text;
  91     let mut total = 0;
  92     while !text.is_empty() {
  93         match NUMERALS.iter().find(|&&(rn, _)| text.starts_with(rn)) {
  94             Some(&(rn, val)) => {
  95                 total += val;
  96                 text = &text[rn.len()..];
  97             }
  98             None => {
  99                 cx.span_err(sp, "invalid Roman numeral");
 100                 return DummyResult::any(sp);
 101             }
 102         }
 103     }
 104
 105     MacEager::expr(cx.expr_usize(sp, total))
 106 }
 107
 108 #[plugin_registrar]
 109 pub fn plugin_registrar(reg: &mut Registry) {
 110     reg.register_macro("rn", expand_rn);
 111 }
 112 ```
 113
 114 Then we can use `rn!()` like any other macro:
 115
 116 ```rust,ignore
 117 #![feature(plugin)]
 118 #![plugin(roman_numerals)]
 119
 120 fn main() {
 121     assert_eq!(rn!(MMXV), 2015);
 122 }
 123 ```
 124
 125 The advantages over a simple `fn(&str) -> u32` are:
 126
 127 * The (arbitrarily complex) conversion is done at compile time.
 128 * Input validation is also performed at compile time.
 129 * It can be extended to allow use in patterns, which effectively gives
 130   a way to define new literal syntax for any data type.
 131
 132 In addition to procedural macros, you can define new
 133 [`derive`](../../reference/attributes/derive.md)-like attributes and other kinds
 134 of extensions.  See `Registry::register_syntax_extension` and the
 135 `SyntaxExtension` enum.  For a more involved macro example, see
 136 [`regex_macros`](https://github.com/rust-lang/regex/blob/master/regex_macros/src/lib.rs).
 137
 138
 139 ## Tips and tricks
 140
 141 You can use `syntax::parse` to turn token trees into
 142 higher-level syntax elements like expressions:
 143
 144 ```rust,ignore
 145 fn expand_foo(cx: &mut ExtCtxt, sp: Span, args: &[TokenTree])
 146         -> Box<MacResult+'static> {
 147
 148     let mut parser = cx.new_parser_from_tts(args);
 149
 150     let expr: P<Expr> = parser.parse_expr();
 151 ```
 152
 153 Looking through [`libsyntax` parser
 154 code](https://github.com/rust-lang/rust/blob/master/src/libsyntax/parse/parser.rs)
 155 will give you a feel for how the parsing infrastructure works.
 156
 157 Keep the `Span`s of everything you parse, for better error reporting. You can
 158 wrap `Spanned` around your custom data structures.
 159
 160 Calling `ExtCtxt::span_fatal` will immediately abort compilation. It's better to
 161 instead call `ExtCtxt::span_err` and return `DummyResult` so that the compiler
 162 can continue and find further errors.
 163
 164 To print syntax fragments for debugging, you can use `span_note` together with
 165 `syntax::print::pprust::*_to_string`.
 166
 167 The example above produced an integer literal using `AstBuilder::expr_usize`.
 168 As an alternative to the `AstBuilder` trait, `libsyntax` provides a set of
 169 quasiquote macros. They are undocumented and very rough around the edges.
 170 However, the implementation may be a good starting point for an improved
 171 quasiquote as an ordinary plugin library.
 172
 173
 174 # Lint plugins
 175
 176 Plugins can extend [Rust's lint
 177 infrastructure](../../reference/attributes/diagnostics.md#lint-check-attributes) with
 178 additional checks for code style, safety, etc. Now let's write a plugin
 179 [`lint_plugin_test.rs`](https://github.com/rust-lang/rust/blob/master/src/test/ui-fulldeps/auxiliary/lint_plugin_test.rs)
 180 that warns about any item named `lintme`.
 181
 182 ```rust,ignore
 183 #![feature(plugin_registrar)]
 184 #![feature(box_syntax, rustc_private)]
 185
 186 extern crate syntax;
 187
 188 // Load rustc as a plugin to get macros
 189 #[macro_use]
 190 extern crate rustc;
 191 extern crate rustc_plugin;
 192
 193 use rustc::lint::{EarlyContext, LintContext, LintPass, EarlyLintPass,
 194                   EarlyLintPassObject, LintArray};
 195 use rustc_plugin::Registry;
 196 use syntax::ast;
 197
 198 declare_lint!(TEST_LINT, Warn, "Warn about items named 'lintme'");
 199
 200 struct Pass;
 201
 202 impl LintPass for Pass {
 203     fn get_lints(&self) -> LintArray {
 204         lint_array!(TEST_LINT)
 205     }
 206 }
 207
 208 impl EarlyLintPass for Pass {
 209     fn check_item(&mut self, cx: &EarlyContext, it: &ast::Item) {
 210         if it.ident.as_str() == "lintme" {
 211             cx.span_lint(TEST_LINT, it.span, "item is named 'lintme'");
 212         }
 213     }
 214 }
 215
 216 #[plugin_registrar]
 217 pub fn plugin_registrar(reg: &mut Registry) {
 218     reg.register_early_lint_pass(box Pass as EarlyLintPassObject);
 219 }
 220 ```
 221
 222 Then code like
 223
 224 ```rust,ignore
 225 #![plugin(lint_plugin_test)]
 226
 227 fn lintme() { }
 228 ```
 229
 230 will produce a compiler warning:
 231
 232 ```txt
 233 foo.rs:4:1: 4:16 warning: item is named 'lintme', #[warn(test_lint)] on by default
 234 foo.rs:4 fn lintme() { }
 235          ^~~~~~~~~~~~~~~
 236 ```
 237
 238 The components of a lint plugin are:
 239
 240 * one or more `declare_lint!` invocations, which define static `Lint` structs;
 241
 242 * a struct holding any state needed by the lint pass (here, none);
 243
 244 * a `LintPass`
 245   implementation defining how to check each syntax element. A single
 246   `LintPass` may call `span_lint` for several different `Lint`s, but should
 247   register them all through the `get_lints` method.
 248
 249 Lint passes are syntax traversals, but they run at a late stage of compilation
 250 where type information is available. `rustc`'s [built-in
 251 lints](https://github.com/rust-lang/rust/blob/master/src/librustc/lint/builtin.rs)
 252 mostly use the same infrastructure as lint plugins, and provide examples of how
 253 to access type information.
 254
 255 Lints defined by plugins are controlled by the usual [attributes and compiler
 256 flags](../../reference/attributes/diagnostics.md#lint-check-attributes), e.g.
 257 `#[allow(test_lint)]` or `-A test-lint`. These identifiers are derived from the
 258 first argument to `declare_lint!`, with appropriate case and punctuation
 259 conversion.
 260
 261 You can run `rustc -W help foo.rs` to see a list of lints known to `rustc`,
 262 including those provided by plugins loaded by `foo.rs`.