]> git.lizzy.rs Git - rust.git/blob - src/librustc/lint/mod.rs
doc: remove incomplete sentence
[rust.git] / src / librustc / lint / mod.rs
1 // Copyright 2012-2014 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
4 //
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
10
11 //! Lints, aka compiler warnings.
12 //!
13 //! A 'lint' check is a kind of miscellaneous constraint that a user _might_
14 //! want to enforce, but might reasonably want to permit as well, on a
15 //! module-by-module basis. They contrast with static constraints enforced by
16 //! other phases of the compiler, which are generally required to hold in order
17 //! to compile the program at all.
18 //!
19 //! Most lints can be written as `LintPass` instances. These run just before
20 //! translation to LLVM bytecode. The `LintPass`es built into rustc are defined
21 //! within `builtin.rs`, which has further comments on how to add such a lint.
22 //! rustc can also load user-defined lint plugins via the plugin mechanism.
23 //!
24 //! Some of rustc's lints are defined elsewhere in the compiler and work by
25 //! calling `add_lint()` on the overall `Session` object. This works when
26 //! it happens before the main lint pass, which emits the lints stored by
27 //! `add_lint()`. To emit lints after the main lint pass (from trans, for
28 //! example) requires more effort. See `emit_lint` and `GatherNodeLevels`
29 //! in `context.rs`.
30
31 #![macro_escape]
32
33 pub use self::Level::*;
34 pub use self::LintSource::*;
35
36 use std::hash;
37 use std::ascii::AsciiExt;
38 use syntax::codemap::Span;
39 use syntax::visit::FnKind;
40 use syntax::ast;
41
42 pub use lint::context::{Context, LintStore, raw_emit_lint, check_crate, gather_attrs};
43
44 /// Specification of a single lint.
45 #[deriving(Copy)]
46 pub struct Lint {
47     /// A string identifier for the lint.
48     ///
49     /// This identifies the lint in attributes and in command-line arguments.
50     /// In those contexts it is always lowercase, but this field is compared
51     /// in a way which is case-insensitive for ASCII characters. This allows
52     /// `declare_lint!()` invocations to follow the convention of upper-case
53     /// statics without repeating the name.
54     ///
55     /// The name is written with underscores, e.g. "unused_imports".
56     /// On the command line, underscores become dashes.
57     pub name: &'static str,
58
59     /// Default level for the lint.
60     pub default_level: Level,
61
62     /// Description of the lint or the issue it detects.
63     ///
64     /// e.g. "imports that are never used"
65     pub desc: &'static str,
66 }
67
68 impl Lint {
69     /// Get the lint's name, with ASCII letters converted to lowercase.
70     pub fn name_lower(&self) -> String {
71         self.name.to_ascii_lowercase()
72     }
73 }
74
75 /// Build a `Lint` initializer.
76 #[macro_export]
77 macro_rules! lint_initializer {
78     ($name:ident, $level:ident, $desc:expr) => (
79         ::rustc::lint::Lint {
80             name: stringify!($name),
81             default_level: ::rustc::lint::$level,
82             desc: $desc,
83         }
84     )
85 }
86
87 /// Declare a static item of type `&'static Lint`.
88 #[macro_export]
89 macro_rules! declare_lint {
90     // FIXME(#14660): deduplicate
91     (pub $name:ident, $level:ident, $desc:expr) => (
92         pub static $name: &'static ::rustc::lint::Lint
93             = &lint_initializer!($name, $level, $desc);
94     );
95     ($name:ident, $level:ident, $desc:expr) => (
96         static $name: &'static ::rustc::lint::Lint
97             = &lint_initializer!($name, $level, $desc);
98     );
99 }
100
101 /// Declare a static `LintArray` and return it as an expression.
102 #[macro_export]
103 macro_rules! lint_array { ($( $lint:expr ),*) => (
104     {
105         #[allow(non_upper_case_globals)]
106         static array: LintArray = &[ $( &$lint ),* ];
107         array
108     }
109 ) }
110
111 pub type LintArray = &'static [&'static &'static Lint];
112
113 /// Trait for types providing lint checks.
114 ///
115 /// Each `check` method checks a single syntax node, and should not
116 /// invoke methods recursively (unlike `Visitor`). By default they
117 /// do nothing.
118 //
119 // FIXME: eliminate the duplication with `Visitor`. But this also
120 // contains a few lint-specific methods with no equivalent in `Visitor`.
121 pub trait LintPass {
122     /// Get descriptions of the lints this `LintPass` object can emit.
123     ///
124     /// NB: there is no enforcement that the object only emits lints it registered.
125     /// And some `rustc` internal `LintPass`es register lints to be emitted by other
126     /// parts of the compiler. If you want enforced access restrictions for your
127     /// `Lint`, make it a private `static` item in its own module.
128     fn get_lints(&self) -> LintArray;
129
130     fn check_crate(&mut self, _: &Context, _: &ast::Crate) { }
131     fn check_ident(&mut self, _: &Context, _: Span, _: ast::Ident) { }
132     fn check_mod(&mut self, _: &Context, _: &ast::Mod, _: Span, _: ast::NodeId) { }
133     fn check_view_item(&mut self, _: &Context, _: &ast::ViewItem) { }
134     fn check_foreign_item(&mut self, _: &Context, _: &ast::ForeignItem) { }
135     fn check_item(&mut self, _: &Context, _: &ast::Item) { }
136     fn check_local(&mut self, _: &Context, _: &ast::Local) { }
137     fn check_block(&mut self, _: &Context, _: &ast::Block) { }
138     fn check_stmt(&mut self, _: &Context, _: &ast::Stmt) { }
139     fn check_arm(&mut self, _: &Context, _: &ast::Arm) { }
140     fn check_pat(&mut self, _: &Context, _: &ast::Pat) { }
141     fn check_decl(&mut self, _: &Context, _: &ast::Decl) { }
142     fn check_expr(&mut self, _: &Context, _: &ast::Expr) { }
143     fn check_expr_post(&mut self, _: &Context, _: &ast::Expr) { }
144     fn check_ty(&mut self, _: &Context, _: &ast::Ty) { }
145     fn check_generics(&mut self, _: &Context, _: &ast::Generics) { }
146     fn check_fn(&mut self, _: &Context,
147         _: FnKind, _: &ast::FnDecl, _: &ast::Block, _: Span, _: ast::NodeId) { }
148     fn check_ty_method(&mut self, _: &Context, _: &ast::TypeMethod) { }
149     fn check_trait_method(&mut self, _: &Context, _: &ast::TraitItem) { }
150     fn check_struct_def(&mut self, _: &Context,
151         _: &ast::StructDef, _: ast::Ident, _: &ast::Generics, _: ast::NodeId) { }
152     fn check_struct_def_post(&mut self, _: &Context,
153         _: &ast::StructDef, _: ast::Ident, _: &ast::Generics, _: ast::NodeId) { }
154     fn check_struct_field(&mut self, _: &Context, _: &ast::StructField) { }
155     fn check_variant(&mut self, _: &Context, _: &ast::Variant, _: &ast::Generics) { }
156     fn check_variant_post(&mut self, _: &Context, _: &ast::Variant, _: &ast::Generics) { }
157     fn check_opt_lifetime_ref(&mut self, _: &Context, _: Span, _: &Option<ast::Lifetime>) { }
158     fn check_lifetime_ref(&mut self, _: &Context, _: &ast::Lifetime) { }
159     fn check_lifetime_def(&mut self, _: &Context, _: &ast::LifetimeDef) { }
160     fn check_explicit_self(&mut self, _: &Context, _: &ast::ExplicitSelf) { }
161     fn check_mac(&mut self, _: &Context, _: &ast::Mac) { }
162     fn check_path(&mut self, _: &Context, _: &ast::Path, _: ast::NodeId) { }
163     fn check_attribute(&mut self, _: &Context, _: &ast::Attribute) { }
164
165     /// Called when entering a syntax node that can have lint attributes such
166     /// as `#[allow(...)]`. Called with *all* the attributes of that node.
167     fn enter_lint_attrs(&mut self, _: &Context, _: &[ast::Attribute]) { }
168
169     /// Counterpart to `enter_lint_attrs`.
170     fn exit_lint_attrs(&mut self, _: &Context, _: &[ast::Attribute]) { }
171 }
172
173 /// A lint pass boxed up as a trait object.
174 pub type LintPassObject = Box<LintPass + 'static>;
175
176 /// Identifies a lint known to the compiler.
177 #[deriving(Clone, Copy)]
178 pub struct LintId {
179     // Identity is based on pointer equality of this field.
180     lint: &'static Lint,
181 }
182
183 impl PartialEq for LintId {
184     fn eq(&self, other: &LintId) -> bool {
185         (self.lint as *const Lint) == (other.lint as *const Lint)
186     }
187 }
188
189 impl Eq for LintId { }
190
191 impl<S: hash::Writer> hash::Hash<S> for LintId {
192     fn hash(&self, state: &mut S) {
193         let ptr = self.lint as *const Lint;
194         ptr.hash(state);
195     }
196 }
197
198 impl LintId {
199     /// Get the `LintId` for a `Lint`.
200     pub fn of(lint: &'static Lint) -> LintId {
201         LintId {
202             lint: lint,
203         }
204     }
205
206     /// Get the name of the lint.
207     pub fn as_str(&self) -> String {
208         self.lint.name_lower()
209     }
210 }
211
212 /// Setting for how to handle a lint.
213 #[deriving(Clone, Copy, PartialEq, PartialOrd, Eq, Ord)]
214 pub enum Level {
215     Allow, Warn, Deny, Forbid
216 }
217
218 impl Level {
219     /// Convert a level to a lower-case string.
220     pub fn as_str(self) -> &'static str {
221         match self {
222             Allow => "allow",
223             Warn => "warn",
224             Deny => "deny",
225             Forbid => "forbid",
226         }
227     }
228
229     /// Convert a lower-case string to a level.
230     pub fn from_str(x: &str) -> Option<Level> {
231         match x {
232             "allow" => Some(Allow),
233             "warn" => Some(Warn),
234             "deny" => Some(Deny),
235             "forbid" => Some(Forbid),
236             _ => None,
237         }
238     }
239 }
240
241 /// How a lint level was set.
242 #[deriving(Clone, Copy, PartialEq, Eq)]
243 pub enum LintSource {
244     /// Lint is at the default level as declared
245     /// in rustc or a plugin.
246     Default,
247
248     /// Lint level was set by an attribute.
249     Node(Span),
250
251     /// Lint level was set by a command-line flag.
252     CommandLine,
253 }
254
255 pub type LevelSource = (Level, LintSource);
256
257 pub mod builtin;
258
259 mod context;