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 to
  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 `fill_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 //!
  59 //! See also this post:
  60 //! <https://rust-analyzer.github.io/blog/2020/09/28/how-to-make-a-light-bulb.html>
  61 #[allow(unused)]
  62 macro_rules! eprintln {
  63     ($($tt:tt)*) => { stdx::eprintln!($($tt)*) };
  64 }
  65
  66 mod assist_config;
  67 mod assist_context;
  68 #[cfg(test)]
  69 mod tests;
  70 pub mod utils;
  71
  72 use hir::Semantics;
  73 use ide_db::{base_db::FileRange, RootDatabase};
  74 use syntax::TextRange;
  75
  76 pub(crate) use crate::assist_context::{AssistContext, Assists};
  77
  78 pub use assist_config::AssistConfig;
  79 pub use ide_db::assists::{
  80     Assist, AssistId, AssistKind, AssistResolveStrategy, GroupLabel, SingleResolve,
  81 };
  82
  83 /// Return all the assists applicable at the given position.
  84 ///
  85 // NOTE: We don't have a `Feature: ` section for assists, they are special-cased
  86 // in the manual.
  87 pub fn assists(
  88     db: &RootDatabase,
  89     config: &AssistConfig,
  90     resolve: AssistResolveStrategy,
  91     range: FileRange,
  92 ) -> Vec<Assist> {
  93     let sema = Semantics::new(db);
  94     let ctx = AssistContext::new(sema, config, range);
  95     let mut acc = Assists::new(&ctx, resolve);
  96     handlers::all().iter().for_each(|handler| {
  97         handler(&mut acc, &ctx);
  98     });
  99     acc.finish()
 100 }
 101
 102 mod handlers {
 103     use crate::{AssistContext, Assists};
 104
 105     pub(crate) type Handler = fn(&mut Assists, &AssistContext) -> Option<()>;
 106
 107     mod add_explicit_type;
 108     mod add_lifetime_to_type;
 109     mod add_missing_impl_members;
 110     mod add_turbo_fish;
 111     mod apply_demorgan;
 112     mod auto_import;
 113     mod change_visibility;
 114     mod convert_bool_then;
 115     mod convert_comment_block;
 116     mod convert_integer_literal;
 117     mod convert_into_to_from;
 118     mod convert_iter_for_each_to_for;
 119     mod convert_tuple_struct_to_named_struct;
 120     mod convert_to_guarded_return;
 121     mod convert_while_to_loop;
 122     mod destructure_tuple_binding;
 123     mod expand_glob_import;
 124     mod extract_function;
 125     mod extract_module;
 126     mod extract_struct_from_enum_variant;
 127     mod extract_type_alias;
 128     mod extract_variable;
 129     mod add_missing_match_arms;
 130     mod fix_visibility;
 131     mod flip_binexpr;
 132     mod flip_comma;
 133     mod flip_trait_bound;
 134     mod generate_constant;
 135     mod generate_default_from_enum_variant;
 136     mod generate_default_from_new;
 137     mod generate_deref;
 138     mod generate_derive;
 139     mod generate_documentation_template;
 140     mod generate_enum_is_method;
 141     mod generate_enum_projection_method;
 142     mod generate_from_impl_for_enum;
 143     mod generate_function;
 144     mod generate_getter;
 145     mod generate_impl;
 146     mod generate_is_empty_from_len;
 147     mod generate_new;
 148     mod generate_setter;
 149     mod generate_delegate_methods;
 150     mod add_return_type;
 151     mod inline_call;
 152     mod inline_local_variable;
 153     mod introduce_named_lifetime;
 154     mod invert_if;
 155     mod merge_imports;
 156     mod merge_match_arms;
 157     mod move_bounds;
 158     mod move_guard;
 159     mod move_module_to_file;
 160     mod move_to_mod_rs;
 161     mod move_from_mod_rs;
 162     mod number_representation;
 163     mod promote_local_to_const;
 164     mod pull_assignment_up;
 165     mod qualify_path;
 166     mod qualify_method_call;
 167     mod raw_string;
 168     mod remove_dbg;
 169     mod remove_mut;
 170     mod remove_unused_param;
 171     mod reorder_fields;
 172     mod reorder_impl;
 173     mod replace_try_expr_with_match;
 174     mod replace_derive_with_manual_impl;
 175     mod replace_if_let_with_match;
 176     mod introduce_named_generic;
 177     mod replace_let_with_if_let;
 178     mod replace_qualified_name_with_use;
 179     mod replace_string_with_char;
 180     mod replace_turbofish_with_explicit_type;
 181     mod split_import;
 182     mod sort_items;
 183     mod toggle_ignore;
 184     mod unmerge_use;
 185     mod unwrap_block;
 186     mod unwrap_result_return_type;
 187     mod wrap_return_type_in_result;
 188
 189     pub(crate) fn all() -> &'static [Handler] {
 190         &[
 191             // These are alphabetic for the foolish consistency
 192             add_explicit_type::add_explicit_type,
 193             add_missing_match_arms::add_missing_match_arms,
 194             add_lifetime_to_type::add_lifetime_to_type,
 195             add_return_type::add_return_type,
 196             add_turbo_fish::add_turbo_fish,
 197             apply_demorgan::apply_demorgan,
 198             auto_import::auto_import,
 199             change_visibility::change_visibility,
 200             convert_bool_then::convert_bool_then_to_if,
 201             convert_bool_then::convert_if_to_bool_then,
 202             convert_comment_block::convert_comment_block,
 203             convert_integer_literal::convert_integer_literal,
 204             convert_into_to_from::convert_into_to_from,
 205             convert_iter_for_each_to_for::convert_iter_for_each_to_for,
 206             convert_iter_for_each_to_for::convert_for_loop_with_for_each,
 207             convert_to_guarded_return::convert_to_guarded_return,
 208             convert_tuple_struct_to_named_struct::convert_tuple_struct_to_named_struct,
 209             convert_while_to_loop::convert_while_to_loop,
 210             destructure_tuple_binding::destructure_tuple_binding,
 211             expand_glob_import::expand_glob_import,
 212             extract_struct_from_enum_variant::extract_struct_from_enum_variant,
 213             extract_type_alias::extract_type_alias,
 214             fix_visibility::fix_visibility,
 215             flip_binexpr::flip_binexpr,
 216             flip_comma::flip_comma,
 217             flip_trait_bound::flip_trait_bound,
 218             generate_constant::generate_constant,
 219             generate_default_from_enum_variant::generate_default_from_enum_variant,
 220             generate_default_from_new::generate_default_from_new,
 221             generate_derive::generate_derive,
 222             generate_documentation_template::generate_documentation_template,
 223             generate_enum_is_method::generate_enum_is_method,
 224             generate_enum_projection_method::generate_enum_as_method,
 225             generate_enum_projection_method::generate_enum_try_into_method,
 226             generate_from_impl_for_enum::generate_from_impl_for_enum,
 227             generate_function::generate_function,
 228             generate_impl::generate_impl,
 229             generate_is_empty_from_len::generate_is_empty_from_len,
 230             generate_new::generate_new,
 231             inline_call::inline_call,
 232             inline_call::inline_into_callers,
 233             inline_local_variable::inline_local_variable,
 234             introduce_named_generic::introduce_named_generic,
 235             introduce_named_lifetime::introduce_named_lifetime,
 236             invert_if::invert_if,
 237             merge_imports::merge_imports,
 238             merge_match_arms::merge_match_arms,
 239             move_bounds::move_bounds_to_where_clause,
 240             move_guard::move_arm_cond_to_match_guard,
 241             move_guard::move_guard_to_arm_body,
 242             move_module_to_file::move_module_to_file,
 243             move_to_mod_rs::move_to_mod_rs,
 244             move_from_mod_rs::move_from_mod_rs,
 245             number_representation::reformat_number_literal,
 246             pull_assignment_up::pull_assignment_up,
 247             promote_local_to_const::promote_local_to_const,
 248             qualify_path::qualify_path,
 249             qualify_method_call::qualify_method_call,
 250             raw_string::add_hash,
 251             raw_string::make_usual_string,
 252             raw_string::remove_hash,
 253             remove_dbg::remove_dbg,
 254             remove_mut::remove_mut,
 255             remove_unused_param::remove_unused_param,
 256             reorder_fields::reorder_fields,
 257             reorder_impl::reorder_impl,
 258             replace_try_expr_with_match::replace_try_expr_with_match,
 259             replace_derive_with_manual_impl::replace_derive_with_manual_impl,
 260             replace_if_let_with_match::replace_if_let_with_match,
 261             replace_if_let_with_match::replace_match_with_if_let,
 262             replace_let_with_if_let::replace_let_with_if_let,
 263             replace_turbofish_with_explicit_type::replace_turbofish_with_explicit_type,
 264             replace_qualified_name_with_use::replace_qualified_name_with_use,
 265             sort_items::sort_items,
 266             split_import::split_import,
 267             toggle_ignore::toggle_ignore,
 268             unmerge_use::unmerge_use,
 269             unwrap_block::unwrap_block,
 270             unwrap_result_return_type::unwrap_result_return_type,
 271             wrap_return_type_in_result::wrap_return_type_in_result,
 272             // These are manually sorted for better priorities. By default,
 273             // priority is determined by the size of the target range (smaller
 274             // target wins). If the ranges are equal, position in this list is
 275             // used as a tie-breaker.
 276             add_missing_impl_members::add_missing_impl_members,
 277             add_missing_impl_members::add_missing_default_members,
 278             //
 279             replace_string_with_char::replace_string_with_char,
 280             replace_string_with_char::replace_char_with_string,
 281             raw_string::make_raw_string,
 282             //
 283             extract_variable::extract_variable,
 284             extract_function::extract_function,
 285             extract_module::extract_module,
 286             //
 287             generate_getter::generate_getter,
 288             generate_getter::generate_getter_mut,
 289             generate_setter::generate_setter,
 290             generate_delegate_methods::generate_delegate_methods,
 291             generate_deref::generate_deref,
 292             // Are you sure you want to add new assist here, and not to the
 293             // sorted list above?
 294         ]
 295     }
 296 }