aboutsummaryrefslogtreecommitdiff
path: root/editors/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'editors/README.md')
-rw-r--r--editors/README.md221
1 files changed, 166 insertions, 55 deletions
diff --git a/editors/README.md b/editors/README.md
index 5b09750e6..9ed65e631 100644
--- a/editors/README.md
+++ b/editors/README.md
@@ -4,72 +4,96 @@ To install experimental VS Code plugin:
4$ git clone https://github.com/rust-analyzer/rust-analyzer.git --depth 1 4$ git clone https://github.com/rust-analyzer/rust-analyzer.git --depth 1
5$ cd rust-analyzer 5$ cd rust-analyzer
6$ cargo install-code 6$ cargo install-code
7
8# for stdlib support
9$ rustup component add rust-src
7``` 10```
8 11
9This will run `cargo install --packge ra_lsp_server` to install the 12This will run `cargo install --packge ra_lsp_server` to install the server
10server binary into `~/.cargo/bin`, and then will build and install 13binary into `~/.cargo/bin`, and then will build and install plugin from
11plugin from `editors/code`. See 14`editors/code`. See
12[this](https://github.com/matklad/rust-analyzer/blob/cc76b0d31d8ba013c499dd3a4ca69b37004795e6/crates/tools/src/main.rs#L192) 15[this](https://github.com/rust-analyzer/rust-analyzer/blob/0199572a3d06ff66eeae85a2d2c9762996f0d2d8/crates/tools/src/main.rs#L150)
13for details 16for details. The installation is expected to *just work*, if it doesn't, report
17bugs!
14 18
15It's better to remove existing Rust plugins to avoid interference. 19It's better to remove existing Rust plugins to avoid interference.
16 20
17### Features: 21## Rust Analyzer Specifc Features
18
19* syntax highlighting (LSP does not have API for it, so impl is hacky
20 and sometimes fall-backs to the horrible built-in highlighting)
21
22* **Go to symbol in workspace** (`ctrl+t`)
23 - `#Foo` searches for `Foo` type in the current workspace
24 - `#foo#` searches for `foo` function in the current workspace
25 - `#Foo*` searches for `Foo` type among dependencies, excluding `stdlib`
26 - Sorry for a weired UI, neither LSP, not VSCode have any sane API for filtering! :)
27
28* **Go to symbol in file** (`alt+shift+o`)
29
30* **Go to definition** ("correct" for `mod foo;` decls, approximate for other things).
31
32* commands (`ctrl+shift+p` or keybindings)
33 - **Show Rust Syntax Tree** (use it to verify that plugin works)
34 - **Rust Extend Selection**. Extends the current selection to the
35 encompassing syntactic construct (expression, statement, item,
36 module, etc). It works with multiple cursors. Do bind this command
37 to a key, its super-useful!
38 - **Rust Matching Brace**. If the cursor is on any brace
39 (`<>(){}[]`) which is a part of a brace-pair, moves cursor to the
40 matching brace.
41 - **Rust Parent Module**. Navigate to the parent module of the current module
42 - **Rust Join Lines**. Join selected lines into one, smartly fixing
43 up whitespace and trailing commas.
44 - **Run test at caret**. When cursor is inside a function marked
45 `#[test]`, this action runs this specific test. If the cursor is
46 outside of the test function, this re-runs the last test. Do bind
47 this to a shortcut!
48 - **Format document**. Formats the current file with rustfmt.
49 Rustfmt must be installed separately with `rustup component add rustfmt`.
50
51* Typing assists
52 - typing `let =` tries to smartly add `;` if `=` is followed by an existing expression.
53 - Enter inside comments continues comment (`<|>` signifies cursor position):
54 22
55``` 23These features are implemented as extensions to the langauge server protocol.
56/// Docs<|> 24They are more experimental in nature and work only with VS Code.
57fn foo() {}
58```
59 25
60``` 26### Syntax highlighting
61/// Docs 27
62/// <|> 28It overrides built-in highlighting, and works only with a specific theme
63fn foo() {} 29(zenburn). `ra-lsp.highlightingOn` setting can be used to disable it.
64``` 30
31### Go to symbol in workspace <kbd>ctrl+t</kbd>
32
33It mostly works on top of the built-in LSP functionality, however `#` and `*`
34symbols can be used to narrow down the search. Specifically,
35
36- `#Foo` searches for `Foo` type in the current workspace
37- `#foo#` searches for `foo` function in the current workspace
38- `#Foo*` searches for `Foo` type among dependencies, excluding `stdlib`
39- `#foo#*` seaches for `foo` function among dependencies.
40
41That is, `#` switches from "types" to all symbols, `*` switches from the current
42workspace to dependencies.
43
44### Commands <kbd>ctrl+shift+p</kbd>
45
46#### Show Rust Syntax Tree
47
48Shows the parse tree of the current file. It exists mostly for debugging
49rust-analyzer itself.
50
51#### Extend Selection
52
53Extends the current selection to the encompassing syntactic construct
54(expression, statement, item, module, etc). It works with multiple cursors. Do
55bind this command to a key, its super-useful! Expected to be upstreamed to LSP soonish:
56https://github.com/Microsoft/language-server-protocol/issues/613
57
58#### Matching Brace
59
60If the cursor is on any brace (`<>(){}[]`) which is a part of a brace-pair,
61moves cursor to the matching brace. It uses the actual parser to determine
62braces, so it won't confuse generics with comparisons.
65 63
66* code actions (use `ctrl+.` to activate). 64#### Parent Module
67 65
66Navigates to the parent module of the current module.
67
68#### Join Lines
69
70Join selected lines into one, smartly fixing up whitespace and trailing commas.
71
72#### Run
73
74Shows popup suggesting to run a test/benchmark/binary **at the current cursor
75location**. Super useful for repeatedly running just a single test. Do bind this
76to a shortcut!
77
78
79### On Typing Assists
80
81Some features trigger on typing certain characters:
82
83- typing `let =` tries to smartly add `;` if `=` is followed by an existing expression.
84- Enter inside comments automatically inserts `///`
85- typing `.` in a chain method call auto-indents
86
87
88### Code Actions (Assists)
89
90These are triggered in a particular context via lightbulb. We use custom code on
91the VS Code side to be able to position cursor.
68 92
69 93
70- Flip `,` 94- Flip `,`
71 95
72``` 96```rust
73// before: 97// before:
74fn foo(x: usize,<|> dim: (usize, usize)) 98fn foo(x: usize,<|> dim: (usize, usize))
75// after: 99// after:
@@ -78,7 +102,7 @@ fn foo(dim: (usize, usize), x: usize)
78 102
79- Add `#[derive]` 103- Add `#[derive]`
80 104
81``` 105```rust
82// before: 106// before:
83struct Foo { 107struct Foo {
84 <|>x: i32 108 <|>x: i32
@@ -92,7 +116,7 @@ struct Foo {
92 116
93- Add `impl` 117- Add `impl`
94 118
95``` 119```rust
96// before: 120// before:
97struct Foo<'a, T: Debug> { 121struct Foo<'a, T: Debug> {
98 <|>t: T 122 <|>t: T
@@ -106,3 +130,90 @@ impl<'a, T: Debug> Foo<'a, T> {
106 <|> 130 <|>
107} 131}
108``` 132```
133
134- Change visibility
135
136```rust
137// before:
138fn<|> foo() {}
139
140// after
141pub(crate) fn foo() {}
142```
143
144- Introduce variable:
145
146```rust
147// before:
148fn foo() {
149 foo(<|>1 + 1<|>);
150}
151
152// after:
153fn foo() {
154 let var_name = 1 + 1;
155 foo(var_name);
156}
157```
158
159- Replace if-let with match:
160
161```rust
162// before:
163impl VariantData {
164 pub fn is_struct(&self) -> bool {
165 if <|>let VariantData::Struct(..) = *self {
166 true
167 } else {
168 false
169 }
170 }
171}
172
173// after:
174impl VariantData {
175 pub fn is_struct(&self) -> bool {
176 <|>match *self {
177 VariantData::Struct(..) => true,
178 _ => false,
179 }
180 }
181}
182```
183
184- Split import
185
186```rust
187// before:
188use algo:<|>:visitor::{Visitor, visit};
189//after:
190use algo::{<|>visitor::{Visitor, visit}};
191```
192
193## LSP features
194
195* **Go to definition**: works correctly for local variables and some paths,
196 falls back to heuristic name matching for other things for the time being.
197
198* **Completion**: completes paths, including dependencies and standard library.
199 Does not handle glob imports and macros. Completes fields and inherent methods
200
201* **Outline** <kbd>alt+shift+o</kbd>
202
203* **Signature Info**
204
205* **Format document**. Formats the current file with rustfmt. Rustfmt must be
206 installed separately with `rustup component add rustfmt`.
207
208* **Hover** shows types of expressions and docstings
209
210* **Rename** works for local variables
211
212* **Code Lens** for running tests
213
214* **Folding**
215
216* **Diagnostics**
217 - missing module for `mod foo;` with a fix to create `foo.rs`.
218 - struct field shorthand
219 - unnessary braces in use item