src/tools/rust-analyzer/crates/ide-assists/src/lib.rs

   1 //! `assists` crate provides a bunch of code assists, also known as code actions
   2 //! (in LSP) or intentions (in IntelliJ).
   3 //!
   4 //! An assist is a micro-refactoring, which is automatically activated in
   5 //! certain context. For example, if the cursor is over `,`, a "swap `,`" assist
   6 //! becomes available.
   7 //!
   8 //! ## Assists Guidelines
   9 //!
  10 //! Assists are the main mechanism to deliver advanced IDE features to the user,
  11 //! so we should pay extra attention to the UX.
  12 //!
  13 //! The power of assists comes from their context-awareness. The main problem
  14 //! with IDE features is that there are a lot of them, and it's hard to teach
  15 //! the user what's available. Assists solve this problem nicely: 💡 signifies
  16 //! that *something* is possible, and clicking on it reveals a *short* list of
  17 //! actions. Contrast it with Emacs `M-x`, which just spits an infinite list of
  18 //! all the features.
  19 //!
  20 //! Here are some considerations when creating a new assist:
  21 //!
  22 //! * It's good to preserve semantics, and it's good to keep the code compiling,
  23 //!   but it isn't necessary. Example: "flip binary operation" might change
  24 //!   semantics.
  25 //! * Assist shouldn't necessary make the code "better". A lot of assist come in
  26 //!   pairs: "if let <-> match".
  27 //! * Assists should have as narrow scope as possible. Each new assists greatly
  28 //!   improves UX for cases where the user actually invokes it, but it makes UX
  29 //!   worse for every case where the user clicks 💡 to invoke some *other*
  30 //!   assist. So, a rarely useful assist which is always applicable can be a net
  31 //!   negative.
  32 //! * Rarely useful actions are tricky. Sometimes there are features which are
  33 //!   clearly useful to some users, but are just noise most of the time. We
  34 //!   don't have a good solution here, our current approach is to make this
  35 //!   functionality available only if assist is applicable to the whole
  36 //!   selection. Example: `sort_items` sorts items alphabetically. Naively, it
  37 //!   should be available more or less everywhere, which isn't useful. So
  38 //!   instead we only show it if the user *selects* the items they want to sort.
  39 //! * Consider grouping related assists together (see [`Assists::add_group`]).
  40 //! * Make assists robust. If the assist depends on results of type-inference too
  41 //!   much, it might only fire in fully-correct code. This makes assist less
  42 //!   useful and (worse) less predictable. The user should have a clear
  43 //!   intuition when each particular assist is available.
  44 //! * Make small assists, which compose. Example: rather than auto-importing
  45 //!   enums in `add_missing_match_arms`, we use fully-qualified names. There's a
  46 //!   separate assist to shorten a fully-qualified name.
  47 //! * Distinguish between assists and fixits for diagnostics. Internally, fixits
  48 //!   and assists are equivalent. They have the same "show a list + invoke a
  49 //!   single element" workflow, and both use [`Assist`] data structure. The main
  50 //!   difference is in the UX: while 💡 looks only at the cursor position,
  51 //!   diagnostics squigglies and fixits are calculated for the whole file and
  52 //!   are presented to the user eagerly. So, diagnostics should be fixable
  53 //!   errors, while assists can be just suggestions for an alternative way to do
  54 //!   something. If something *could* be a diagnostic, it should be a
  55 //!   diagnostic. Conversely, it might be valuable to turn a diagnostic with a
  56 //!   lot of false errors into an assist.
  57 //!
  58 //! See also this post:
  59 //! <https://rust-analyzer.github.io/blog/2020/09/28/how-to-make-a-light-bulb.html>
  60
  61 #![warn(rust_2018_idioms, unused_lifetimes, semicolon_in_expressions_from_macros)]
  62
  63 #[allow(unused)]
  64 macro_rules! eprintln {
  65     ($($tt:tt)*) => { stdx::eprintln!($($tt)*) };
  66 }
  67
  68 mod assist_config;
  69 mod assist_context;
  70 #[cfg(test)]
  71 mod tests;
  72 pub mod utils;
  73
  74 use hir::Semantics;
  75 use ide_db::{base_db::FileRange, RootDatabase};
  76 use syntax::TextRange;
  77
  78 pub(crate) use crate::assist_context::{AssistContext, Assists};
  79
  80 pub use assist_config::AssistConfig;
  81 pub use ide_db::assists::{
  82     Assist, AssistId, AssistKind, AssistResolveStrategy, GroupLabel, SingleResolve,
  83 };
  84
  85 /// Return all the assists applicable at the given position.
  86 ///
  87 // NOTE: We don't have a `Feature: ` section for assists, they are special-cased
  88 // in the manual.
  89 pub fn assists(
  90     db: &RootDatabase,
  91     config: &AssistConfig,
  92     resolve: AssistResolveStrategy,
  93     range: FileRange,
  94 ) -> Vec<Assist> {
  95     let sema = Semantics::new(db);
  96     let ctx = AssistContext::new(sema, config, range);
  97     let mut acc = Assists::new(&ctx, resolve);
  98     handlers::all().iter().for_each(|handler| {
  99         handler(&mut acc, &ctx);
 100     });
 101     acc.finish()
 102 }
 103
 104 mod handlers {
 105     use crate::{AssistContext, Assists};
 106
 107     pub(crate) type Handler = fn(&mut Assists, &AssistContext<'_>) -> Option<()>;
 108
 109     mod add_explicit_type;
 110     mod add_label_to_loop;
 111     mod add_lifetime_to_type;
 112     mod add_missing_impl_members;
 113     mod add_turbo_fish;
 114     mod apply_demorgan;
 115     mod auto_import;
 116     mod change_visibility;
 117     mod convert_bool_then;
 118     mod convert_comment_block;
 119     mod convert_integer_literal;
 120     mod convert_into_to_from;
 121     mod convert_iter_for_each_to_for;
 122     mod convert_let_else_to_match;
 123     mod convert_tuple_struct_to_named_struct;
 124     mod convert_to_guarded_return;
 125     mod convert_while_to_loop;
 126     mod destructure_tuple_binding;
 127     mod expand_glob_import;
 128     mod extract_function;
 129     mod extract_module;
 130     mod extract_struct_from_enum_variant;
 131     mod extract_type_alias;
 132     mod extract_variable;
 133     mod add_missing_match_arms;
 134     mod fix_visibility;
 135     mod flip_binexpr;
 136     mod flip_comma;
 137     mod flip_trait_bound;
 138     mod generate_constant;
 139     mod generate_default_from_enum_variant;
 140     mod generate_default_from_new;
 141     mod generate_deref;
 142     mod generate_derive;
 143     mod generate_documentation_template;
 144     mod generate_enum_is_method;
 145     mod generate_enum_projection_method;
 146     mod generate_enum_variant;
 147     mod generate_from_impl_for_enum;
 148     mod generate_function;
 149     mod generate_getter;
 150     mod generate_impl;
 151     mod generate_is_empty_from_len;
 152     mod generate_new;
 153     mod generate_setter;
 154     mod generate_delegate_methods;
 155     mod add_return_type;
 156     mod inline_call;
 157     mod inline_local_variable;
 158     mod inline_type_alias;
 159     mod introduce_named_lifetime;
 160     mod invert_if;
 161     mod merge_imports;
 162     mod merge_match_arms;
 163     mod move_bounds;
 164     mod move_guard;
 165     mod move_module_to_file;
 166     mod move_to_mod_rs;
 167     mod move_from_mod_rs;
 168     mod number_representation;
 169     mod promote_local_to_const;
 170     mod pull_assignment_up;
 171     mod qualify_path;
 172     mod qualify_method_call;
 173     mod raw_string;
 174     mod remove_dbg;
 175     mod remove_mut;
 176     mod remove_unused_param;
 177     mod reorder_fields;
 178     mod reorder_impl_items;
 179     mod replace_try_expr_with_match;
 180     mod replace_derive_with_manual_impl;
 181     mod replace_if_let_with_match;
 182     mod introduce_named_generic;
 183     mod replace_let_with_if_let;
 184     mod replace_qualified_name_with_use;
 185     mod replace_string_with_char;
 186     mod replace_turbofish_with_explicit_type;
 187     mod split_import;
 188     mod sort_items;
 189     mod toggle_ignore;
 190     mod unmerge_use;
 191     mod unnecessary_async;
 192     mod unwrap_block;
 193     mod unwrap_result_return_type;
 194     mod wrap_return_type_in_result;
 195
 196     pub(crate) fn all() -> &'static [Handler] {
 197         &[
 198             // These are alphabetic for the foolish consistency
 199             add_explicit_type::add_explicit_type,
 200             add_label_to_loop::add_label_to_loop,
 201             add_missing_match_arms::add_missing_match_arms,
 202             add_lifetime_to_type::add_lifetime_to_type,
 203             add_return_type::add_return_type,
 204             add_turbo_fish::add_turbo_fish,
 205             apply_demorgan::apply_demorgan,
 206             auto_import::auto_import,
 207             change_visibility::change_visibility,
 208             convert_bool_then::convert_bool_then_to_if,
 209             convert_bool_then::convert_if_to_bool_then,
 210             convert_comment_block::convert_comment_block,
 211             convert_integer_literal::convert_integer_literal,
 212             convert_into_to_from::convert_into_to_from,
 213             convert_iter_for_each_to_for::convert_iter_for_each_to_for,
 214             convert_iter_for_each_to_for::convert_for_loop_with_for_each,
 215             convert_let_else_to_match::convert_let_else_to_match,
 216             convert_to_guarded_return::convert_to_guarded_return,
 217             convert_tuple_struct_to_named_struct::convert_tuple_struct_to_named_struct,
 218             convert_while_to_loop::convert_while_to_loop,
 219             destructure_tuple_binding::destructure_tuple_binding,
 220             expand_glob_import::expand_glob_import,
 221             extract_struct_from_enum_variant::extract_struct_from_enum_variant,
 222             extract_type_alias::extract_type_alias,
 223             fix_visibility::fix_visibility,
 224             flip_binexpr::flip_binexpr,
 225             flip_comma::flip_comma,
 226             flip_trait_bound::flip_trait_bound,
 227             generate_constant::generate_constant,
 228             generate_default_from_enum_variant::generate_default_from_enum_variant,
 229             generate_default_from_new::generate_default_from_new,
 230             generate_derive::generate_derive,
 231             generate_documentation_template::generate_documentation_template,
 232             generate_documentation_template::generate_doc_example,
 233             generate_enum_is_method::generate_enum_is_method,
 234             generate_enum_projection_method::generate_enum_as_method,
 235             generate_enum_projection_method::generate_enum_try_into_method,
 236             generate_enum_variant::generate_enum_variant,
 237             generate_from_impl_for_enum::generate_from_impl_for_enum,
 238             generate_function::generate_function,
 239             generate_impl::generate_impl,
 240             generate_is_empty_from_len::generate_is_empty_from_len,
 241             generate_new::generate_new,
 242             inline_call::inline_call,
 243             inline_call::inline_into_callers,
 244             inline_local_variable::inline_local_variable,
 245             inline_type_alias::inline_type_alias,
 246             introduce_named_generic::introduce_named_generic,
 247             introduce_named_lifetime::introduce_named_lifetime,
 248             invert_if::invert_if,
 249             merge_imports::merge_imports,
 250             merge_match_arms::merge_match_arms,
 251             move_bounds::move_bounds_to_where_clause,
 252             move_guard::move_arm_cond_to_match_guard,
 253             move_guard::move_guard_to_arm_body,
 254             move_module_to_file::move_module_to_file,
 255             move_to_mod_rs::move_to_mod_rs,
 256             move_from_mod_rs::move_from_mod_rs,
 257             number_representation::reformat_number_literal,
 258             pull_assignment_up::pull_assignment_up,
 259             promote_local_to_const::promote_local_to_const,
 260             qualify_path::qualify_path,
 261             qualify_method_call::qualify_method_call,
 262             raw_string::add_hash,
 263             raw_string::make_usual_string,
 264             raw_string::remove_hash,
 265             remove_dbg::remove_dbg,
 266             remove_mut::remove_mut,
 267             remove_unused_param::remove_unused_param,
 268             reorder_fields::reorder_fields,
 269             reorder_impl_items::reorder_impl_items,
 270             replace_try_expr_with_match::replace_try_expr_with_match,
 271             replace_derive_with_manual_impl::replace_derive_with_manual_impl,
 272             replace_if_let_with_match::replace_if_let_with_match,
 273             replace_if_let_with_match::replace_match_with_if_let,
 274             replace_let_with_if_let::replace_let_with_if_let,
 275             replace_turbofish_with_explicit_type::replace_turbofish_with_explicit_type,
 276             replace_qualified_name_with_use::replace_qualified_name_with_use,
 277             sort_items::sort_items,
 278             split_import::split_import,
 279             toggle_ignore::toggle_ignore,
 280             unmerge_use::unmerge_use,
 281             unnecessary_async::unnecessary_async,
 282             unwrap_block::unwrap_block,
 283             unwrap_result_return_type::unwrap_result_return_type,
 284             wrap_return_type_in_result::wrap_return_type_in_result,
 285             // These are manually sorted for better priorities. By default,
 286             // priority is determined by the size of the target range (smaller
 287             // target wins). If the ranges are equal, position in this list is
 288             // used as a tie-breaker.
 289             add_missing_impl_members::add_missing_impl_members,
 290             add_missing_impl_members::add_missing_default_members,
 291             //
 292             replace_string_with_char::replace_string_with_char,
 293             replace_string_with_char::replace_char_with_string,
 294             raw_string::make_raw_string,
 295             //
 296             extract_variable::extract_variable,
 297             extract_function::extract_function,
 298             extract_module::extract_module,
 299             //
 300             generate_getter::generate_getter,
 301             generate_getter::generate_getter_mut,
 302             generate_setter::generate_setter,
 303             generate_delegate_methods::generate_delegate_methods,
 304             generate_deref::generate_deref,
 305             // Are you sure you want to add new assist here, and not to the
 306             // sorted list above?
 307         ]
 308     }
 309 }