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_match_to_let_else;
 124     mod convert_tuple_struct_to_named_struct;
 125     mod convert_named_struct_to_tuple_struct;
 126     mod convert_to_guarded_return;
 127     mod convert_two_arm_bool_match_to_matches_macro;
 128     mod convert_while_to_loop;
 129     mod destructure_tuple_binding;
 130     mod expand_glob_import;
 131     mod extract_function;
 132     mod extract_module;
 133     mod extract_struct_from_enum_variant;
 134     mod extract_type_alias;
 135     mod extract_variable;
 136     mod add_missing_match_arms;
 137     mod fix_visibility;
 138     mod flip_binexpr;
 139     mod flip_comma;
 140     mod flip_trait_bound;
 141     mod move_format_string_arg;
 142     mod generate_constant;
 143     mod generate_default_from_enum_variant;
 144     mod generate_default_from_new;
 145     mod generate_deref;
 146     mod generate_derive;
 147     mod generate_documentation_template;
 148     mod generate_enum_is_method;
 149     mod generate_enum_projection_method;
 150     mod generate_enum_variant;
 151     mod generate_from_impl_for_enum;
 152     mod generate_function;
 153     mod generate_getter;
 154     mod generate_impl;
 155     mod generate_is_empty_from_len;
 156     mod generate_new;
 157     mod generate_setter;
 158     mod generate_delegate_methods;
 159     mod add_return_type;
 160     mod inline_call;
 161     mod inline_local_variable;
 162     mod inline_type_alias;
 163     mod introduce_named_lifetime;
 164     mod invert_if;
 165     mod merge_imports;
 166     mod merge_match_arms;
 167     mod move_bounds;
 168     mod move_guard;
 169     mod move_module_to_file;
 170     mod move_to_mod_rs;
 171     mod move_from_mod_rs;
 172     mod number_representation;
 173     mod promote_local_to_const;
 174     mod pull_assignment_up;
 175     mod qualify_path;
 176     mod qualify_method_call;
 177     mod raw_string;
 178     mod remove_dbg;
 179     mod remove_mut;
 180     mod remove_unused_param;
 181     mod reorder_fields;
 182     mod reorder_impl_items;
 183     mod replace_try_expr_with_match;
 184     mod replace_derive_with_manual_impl;
 185     mod replace_if_let_with_match;
 186     mod replace_or_with_or_else;
 187     mod introduce_named_generic;
 188     mod replace_let_with_if_let;
 189     mod replace_qualified_name_with_use;
 190     mod replace_string_with_char;
 191     mod replace_turbofish_with_explicit_type;
 192     mod split_import;
 193     mod unmerge_match_arm;
 194     mod unwrap_tuple;
 195     mod sort_items;
 196     mod toggle_ignore;
 197     mod unmerge_use;
 198     mod unnecessary_async;
 199     mod unwrap_block;
 200     mod unwrap_result_return_type;
 201     mod wrap_return_type_in_result;
 202
 203     pub(crate) fn all() -> &'static [Handler] {
 204         &[
 205             // These are alphabetic for the foolish consistency
 206             add_explicit_type::add_explicit_type,
 207             add_label_to_loop::add_label_to_loop,
 208             add_missing_match_arms::add_missing_match_arms,
 209             add_lifetime_to_type::add_lifetime_to_type,
 210             add_return_type::add_return_type,
 211             add_turbo_fish::add_turbo_fish,
 212             apply_demorgan::apply_demorgan,
 213             auto_import::auto_import,
 214             change_visibility::change_visibility,
 215             convert_bool_then::convert_bool_then_to_if,
 216             convert_bool_then::convert_if_to_bool_then,
 217             convert_comment_block::convert_comment_block,
 218             convert_integer_literal::convert_integer_literal,
 219             convert_into_to_from::convert_into_to_from,
 220             convert_iter_for_each_to_for::convert_iter_for_each_to_for,
 221             convert_iter_for_each_to_for::convert_for_loop_with_for_each,
 222             convert_let_else_to_match::convert_let_else_to_match,
 223             convert_named_struct_to_tuple_struct::convert_named_struct_to_tuple_struct,
 224             convert_match_to_let_else::convert_match_to_let_else,
 225             convert_to_guarded_return::convert_to_guarded_return,
 226             convert_tuple_struct_to_named_struct::convert_tuple_struct_to_named_struct,
 227             convert_two_arm_bool_match_to_matches_macro::convert_two_arm_bool_match_to_matches_macro,
 228             convert_while_to_loop::convert_while_to_loop,
 229             destructure_tuple_binding::destructure_tuple_binding,
 230             expand_glob_import::expand_glob_import,
 231             extract_struct_from_enum_variant::extract_struct_from_enum_variant,
 232             extract_type_alias::extract_type_alias,
 233             fix_visibility::fix_visibility,
 234             flip_binexpr::flip_binexpr,
 235             flip_comma::flip_comma,
 236             flip_trait_bound::flip_trait_bound,
 237             generate_constant::generate_constant,
 238             generate_default_from_enum_variant::generate_default_from_enum_variant,
 239             generate_default_from_new::generate_default_from_new,
 240             generate_derive::generate_derive,
 241             generate_documentation_template::generate_documentation_template,
 242             generate_documentation_template::generate_doc_example,
 243             generate_enum_is_method::generate_enum_is_method,
 244             generate_enum_projection_method::generate_enum_as_method,
 245             generate_enum_projection_method::generate_enum_try_into_method,
 246             generate_enum_variant::generate_enum_variant,
 247             generate_from_impl_for_enum::generate_from_impl_for_enum,
 248             generate_function::generate_function,
 249             generate_impl::generate_impl,
 250             generate_is_empty_from_len::generate_is_empty_from_len,
 251             generate_new::generate_new,
 252             inline_call::inline_call,
 253             inline_call::inline_into_callers,
 254             inline_local_variable::inline_local_variable,
 255             inline_type_alias::inline_type_alias,
 256             inline_type_alias::inline_type_alias_uses,
 257             introduce_named_generic::introduce_named_generic,
 258             introduce_named_lifetime::introduce_named_lifetime,
 259             invert_if::invert_if,
 260             merge_imports::merge_imports,
 261             merge_match_arms::merge_match_arms,
 262             move_bounds::move_bounds_to_where_clause,
 263             move_format_string_arg::move_format_string_arg,
 264             move_guard::move_arm_cond_to_match_guard,
 265             move_guard::move_guard_to_arm_body,
 266             move_module_to_file::move_module_to_file,
 267             move_to_mod_rs::move_to_mod_rs,
 268             move_from_mod_rs::move_from_mod_rs,
 269             number_representation::reformat_number_literal,
 270             pull_assignment_up::pull_assignment_up,
 271             promote_local_to_const::promote_local_to_const,
 272             qualify_path::qualify_path,
 273             qualify_method_call::qualify_method_call,
 274             raw_string::add_hash,
 275             raw_string::make_usual_string,
 276             raw_string::remove_hash,
 277             remove_dbg::remove_dbg,
 278             remove_mut::remove_mut,
 279             remove_unused_param::remove_unused_param,
 280             reorder_fields::reorder_fields,
 281             reorder_impl_items::reorder_impl_items,
 282             replace_try_expr_with_match::replace_try_expr_with_match,
 283             replace_derive_with_manual_impl::replace_derive_with_manual_impl,
 284             replace_if_let_with_match::replace_if_let_with_match,
 285             replace_if_let_with_match::replace_match_with_if_let,
 286             replace_let_with_if_let::replace_let_with_if_let,
 287             replace_or_with_or_else::replace_or_else_with_or,
 288             replace_or_with_or_else::replace_or_with_or_else,
 289             replace_turbofish_with_explicit_type::replace_turbofish_with_explicit_type,
 290             replace_qualified_name_with_use::replace_qualified_name_with_use,
 291             sort_items::sort_items,
 292             split_import::split_import,
 293             toggle_ignore::toggle_ignore,
 294             unmerge_match_arm::unmerge_match_arm,
 295             unmerge_use::unmerge_use,
 296             unnecessary_async::unnecessary_async,
 297             unwrap_block::unwrap_block,
 298             unwrap_result_return_type::unwrap_result_return_type,
 299             unwrap_tuple::unwrap_tuple,
 300             wrap_return_type_in_result::wrap_return_type_in_result,
 301             // These are manually sorted for better priorities. By default,
 302             // priority is determined by the size of the target range (smaller
 303             // target wins). If the ranges are equal, position in this list is
 304             // used as a tie-breaker.
 305             add_missing_impl_members::add_missing_impl_members,
 306             add_missing_impl_members::add_missing_default_members,
 307             //
 308             replace_string_with_char::replace_string_with_char,
 309             replace_string_with_char::replace_char_with_string,
 310             raw_string::make_raw_string,
 311             //
 312             extract_variable::extract_variable,
 313             extract_function::extract_function,
 314             extract_module::extract_module,
 315             //
 316             generate_getter::generate_getter,
 317             generate_getter::generate_getter_mut,
 318             generate_setter::generate_setter,
 319             generate_delegate_methods::generate_delegate_methods,
 320             generate_deref::generate_deref,
 321             // Are you sure you want to add new assist here, and not to the
 322             // sorted list above?
 323         ]
 324     }
 325 }