diff options
Diffstat (limited to 'book/src')
| -rw-r--r-- | book/src/SUMMARY.md | 2 | ||||
| -rw-r--r-- | book/src/configuration.md | 2 | ||||
| -rw-r--r-- | book/src/guides/README.md | 4 | ||||
| -rw-r--r-- | book/src/guides/textobject.md | 30 | ||||
| -rw-r--r-- | book/src/keymap.md | 145 | ||||
| -rw-r--r-- | book/src/remapping.md | 2 | ||||
| -rw-r--r-- | book/src/themes.md | 11 | ||||
| -rw-r--r-- | book/src/usage.md | 15 |
8 files changed, 146 insertions, 65 deletions
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 3fa8e067..56f50e21 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -8,3 +8,5 @@ - [Keymap](./keymap.md) - [Key Remapping](./remapping.md) - [Hooks](./hooks.md) +- [Guides](./guides/README.md) + - [Adding Textobject Queries](./guides/textobject.md) diff --git a/book/src/configuration.md b/book/src/configuration.md index d47f95d9..be25441f 100644 --- a/book/src/configuration.md +++ b/book/src/configuration.md @@ -21,6 +21,8 @@ To override global configuration parameters, create a `config.toml` file located | `auto-pairs` | Enable automatic insertion of pairs to parenthese, brackets, etc. | `true` | | `auto-completion` | Enable automatic pop up of auto-completion. | `true` | | `idle-timeout` | Time in milliseconds since last keypress before idle timers trigger. Used for autocompletion, set to 0 for instant. | `400` | +| `completion-trigger-len` | The min-length of word under cursor to trigger autocompletion | `2` | +| `auto-info` | Whether to display infoboxes | `true` | ## LSP diff --git a/book/src/guides/README.md b/book/src/guides/README.md new file mode 100644 index 00000000..96e62978 --- /dev/null +++ b/book/src/guides/README.md @@ -0,0 +1,4 @@ +# Guides + +This section contains guides for adding new language server configurations, +tree-sitter grammers, textobject queries, etc. diff --git a/book/src/guides/textobject.md b/book/src/guides/textobject.md new file mode 100644 index 00000000..50b3b574 --- /dev/null +++ b/book/src/guides/textobject.md @@ -0,0 +1,30 @@ +# Adding Textobject Queries + +Textobjects that are language specific ([like functions, classes, etc][textobjects]) +require an accompanying tree-sitter grammar and a `textobjects.scm` query file +to work properly. Tree-sitter allows us to query the source code syntax tree +and capture specific parts of it. The queries are written in a lisp dialect. +More information on how to write queries can be found in the [official tree-sitter +documentation](tree-sitter-queries). + +Query files should be placed in `runtime/queries/{language}/textobjects.scm` +when contributing. Note that to test the query files locally you should put +them under your local runtime directory (`~/.config/helix/runtime` on Linux +for example). + +The following [captures][tree-sitter-captures] are recognized: + +| Capture Name | +| --- | +| `function.inside` | +| `function.around` | +| `class.inside` | +| `class.around` | +| `parameter.inside` | + +[Example query files][textobject-examples] can be found in the helix GitHub repository. + +[textobjects]: ../usage.md#textobjects +[tree-sitter-queries]: https://tree-sitter.github.io/tree-sitter/using-parsers#query-syntax +[tree-sitter-captures]: https://tree-sitter.github.io/tree-sitter/using-parsers#capturing-nodes +[textobject-examples]: https://github.com/search?q=repo%3Ahelix-editor%2Fhelix+filename%3Atextobjects.scm&type=Code&ref=advsearch&l=&l= diff --git a/book/src/keymap.md b/book/src/keymap.md index 156b1d99..5a6aee41 100644 --- a/book/src/keymap.md +++ b/book/src/keymap.md @@ -6,38 +6,39 @@ > NOTE: Unlike vim, `f`, `F`, `t` and `T` are not confined to the current line. -| Key | Description | Command | -| ----- | ----------- | ------- | -| `h`, `Left` | Move left | `move_char_left` | -| `j`, `Down` | Move down | `move_char_right` | -| `k`, `Up` | Move up | `move_line_up` | -| `l`, `Right` | Move right | `move_line_down` | -| `w` | Move next word start | `move_next_word_start` | -| `b` | Move previous word start | `move_prev_word_start` | -| `e` | Move next word end | `move_next_word_end` | -| `W` | Move next WORD start | `move_next_long_word_start` | -| `B` | Move previous WORD start | `move_prev_long_word_start` | -| `E` | Move next WORD end | `move_next_long_word_end` | -| `t` | Find 'till next char | `find_till_char` | -| `f` | Find next char | `find_next_char` | -| `T` | Find 'till previous char | `till_prev_char` | -| `F` | Find previous char | `find_prev_char` | -| `Home` | Move to the start of the line | `goto_line_start` | -| `End` | Move to the end of the line | `goto_line_end` | -| `PageUp` | Move page up | `page_up` | -| `PageDown` | Move page down | `page_down` | -| `Ctrl-u` | Move half page up | `half_page_up` | -| `Ctrl-d` | Move half page down | `half_page_down` | -| `Ctrl-i` | Jump forward on the jumplist | `jump_forward` | -| `Ctrl-o` | Jump backward on the jumplist | `jump_backward` | -| `v` | Enter [select (extend) mode](#select--extend-mode) | `select_mode` | -| `g` | Enter [goto mode](#goto-mode) | N/A | -| `m` | Enter [match mode](#match-mode) | N/A | -| `:` | Enter command mode | `command_mode` | -| `z` | Enter [view mode](#view-mode) | N/A | -| `Z` | Enter sticky [view mode](#view-mode) | N/A | -| `Ctrl-w` | Enter [window mode](#window-mode) | N/A | -| `Space` | Enter [space mode](#space-mode) | N/A | +| Key | Description | Command | +| ----- | ----------- | ------- | +| `h`/`Left` | Move left | `move_char_left` | +| `j`/`Down` | Move down | `move_line_down` | +| `k`/`Up` | Move up | `move_line_up` | +| `l`/`Right` | Move right | `move_char_right` | +| `w` | Move next word start | `move_next_word_start` | +| `b` | Move previous word start | `move_prev_word_start` | +| `e` | Move next word end | `move_next_word_end` | +| `W` | Move next WORD start | `move_next_long_word_start` | +| `B` | Move previous WORD start | `move_prev_long_word_start` | +| `E` | Move next WORD end | `move_next_long_word_end` | +| `t` | Find 'till next char | `find_till_char` | +| `f` | Find next char | `find_next_char` | +| `T` | Find 'till previous char | `till_prev_char` | +| `F` | Find previous char | `find_prev_char` | +| `Alt-.` | Repeat last motion (`f`, `t` or `m`) | `repeat_last_motion` | +| `Home` | Move to the start of the line | `goto_line_start` | +| `End` | Move to the end of the line | `goto_line_end` | +| `PageUp` | Move page up | `page_up` | +| `PageDown` | Move page down | `page_down` | +| `Ctrl-u` | Move half page up | `half_page_up` | +| `Ctrl-d` | Move half page down | `half_page_down` | +| `Ctrl-i` | Jump forward on the jumplist | `jump_forward` | +| `Ctrl-o` | Jump backward on the jumplist | `jump_backward` | +| `v` | Enter [select (extend) mode](#select--extend-mode) | `select_mode` | +| `g` | Enter [goto mode](#goto-mode) | N/A | +| `m` | Enter [match mode](#match-mode) | N/A | +| `:` | Enter command mode | `command_mode` | +| `z` | Enter [view mode](#view-mode) | N/A | +| `Z` | Enter sticky [view mode](#view-mode) | N/A | +| `Ctrl-w` | Enter [window mode](#window-mode) | N/A | +| `Space` | Enter [space mode](#space-mode) | N/A | ### Changes @@ -54,6 +55,7 @@ | `A` | Insert at the end of the line | `append_to_line` | | `o` | Open new line below selection | `open_below` | | `O` | Open new line above selection | `open_above` | +| `.` | Repeat last change | N/A | | `u` | Undo change | `undo` | | `U` | Redo change | `redo` | | `y` | Yank selection | `yank` | @@ -86,8 +88,9 @@ | `;` | Collapse selection onto a single cursor | `collapse_selection` | | `Alt-;` | Flip selection cursor and anchor | `flip_selections` | | `,` | Keep only the primary selection | `keep_primary_selection` | -| `C` | Copy selection onto the next line | `copy_selection_on_next_line` | -| `Alt-C` | Copy selection onto the previous line | `copy_selection_on_prev_line` | +| `Alt-,` | Remove the primary selection | `remove_primary_selection` | +| `C` | Copy selection onto the next line (Add cursor below) | `copy_selection_on_next_line` | +| `Alt-C` | Copy selection onto the previous line (Add cursor above) | `copy_selection_on_prev_line` | | `(` | Rotate main selection backward | `rotate_selections_backward` | | `)` | Rotate main selection forward | `rotate_selections_forward` | | `Alt-(` | Rotate selection contents backward | `rotate_selection_contents_backward` | @@ -103,13 +106,13 @@ ### Search -> TODO: The search implementation isn't ideal yet -- we don't support searching in reverse. | Key | Description | Command | | ----- | ----------- | ------- | | `/` | Search for regex pattern | `search` | +| `?` | Search for previous pattern | `rsearch` | | `n` | Select next search match | `search_next` | -| `N` | Add next search match to selection | `extend_search_next` | +| `N` | Select previous search match | `search_prev` | | `*` | Use current selection as the search pattern | `search_selection` | ### Minor modes @@ -158,6 +161,8 @@ Jumps to various locations. | `r` | Go to references | `goto_reference` | | `i` | Go to implementation | `goto_implementation` | | `a` | Go to the last accessed/alternate file | `goto_last_accessed_file` | +| `n` | Go to next buffer | `goto_next_buffer` | +| `p` | Go to previous buffer | `goto_previous_buffer` | #### Match mode @@ -180,12 +185,16 @@ TODO: Mappings for selecting syntax nodes (a superset of `[`). This layer is similar to vim keybindings as kakoune does not support window. -| Key | Description | Command | -| ----- | ------------- | ------- | -| `w`, `Ctrl-w` | Switch to next window | `rotate_view` | -| `v`, `Ctrl-v` | Vertical right split | `vsplit` | -| `h`, `Ctrl-h` | Horizontal bottom split | `hsplit` | -| `q`, `Ctrl-q` | Close current window | `wclose` | +| Key | Description | Command | +| ----- | ------------- | ------- | +| `w`, `Ctrl-w` | Switch to next window | `rotate_view` | +| `v`, `Ctrl-v` | Vertical right split | `vsplit` | +| `s`, `Ctrl-s` | Horizontal bottom split | `hsplit` | +| `h`, `Ctrl-h`, `left` | Move to left split | `jump_view_left` | +| `j`, `Ctrl-j`, `down` | Move to split below | `jump_view_down` | +| `k`, `Ctrl-k`, `up` | Move to split above | `jump_view_up` | +| `l`, `Ctrl-l`, `right` | Move to right split | `jump_view_right` | +| `q`, `Ctrl-q` | Close current window | `wclose` | #### Space mode @@ -213,12 +222,12 @@ This layer is a kludge of mappings, mostly pickers. Mappings in the style of [vim-unimpaired](https://github.com/tpope/vim-unimpaired). -| Key | Description | Command | -| ----- | ----------- | ------- | -| `[d` | Go to previous diagnostic | `goto_prev_diag` | -| `]d` | Go to next diagnostic | `goto_next_diag` | -| `[D` | Go to first diagnostic in document | `goto_first_diag` | -| `]D` | Go to last diagnostic in document | `goto_last_diag` | +| Key | Description | Command | +| ----- | ----------- | ------- | +| `[d` | Go to previous diagnostic | `goto_prev_diag` | +| `]d` | Go to next diagnostic | `goto_next_diag` | +| `[D` | Go to first diagnostic in document | `goto_first_diag` | +| `]D` | Go to last diagnostic in document | `goto_last_diag` | | `[space` | Add newline above | `add_newline_above` | | `]space` | Add newline below | `add_newline_below` | @@ -242,12 +251,34 @@ commands (including goto) to extend the existing selection instead of replacing Keys to use within picker. Remapping currently not supported. -| Key | Description | -| ----- | ------------- | -| `Up`, `Ctrl-p` | Previous entry | -| `Down`, `Ctrl-n` | Next entry | -| `Ctrl-space` | Filter options | -| `Enter` | Open selected | -| `Ctrl-h` | Open horizontally | -| `Ctrl-v` | Open vertically | -| `Escape`, `Ctrl-c` | Close picker | +| Key | Description | +| ----- | ------------- | +| `Up`, `Ctrl-k`, `Ctrl-p` | Previous entry | +| `Down`, `Ctrl-j`, `Ctrl-n` | Next entry | +| `Ctrl-space` | Filter options | +| `Enter` | Open selected | +| `Ctrl-s` | Open horizontally | +| `Ctrl-v` | Open vertically | +| `Escape`, `Ctrl-c` | Close picker | + +# Prompt +Keys to use within prompt, Remapping currently not supported. +| Key | Description | +| ----- | ------------- | +| `Escape`, `Ctrl-c` | Close prompt | +| `Alt-b`, `Alt-Left` | Backward a word | +| `Ctrl-b`, `Left` | Backward a char | +| `Alt-f`, `Alt-Right` | Forward a word | +| `Ctrl-f`, `Right` | Forward a char | +| `Ctrl-e`, `End` | move prompt end | +| `Ctrl-a`, `Home` | move prompt start | +| `Ctrl-w` | delete previous word | +| `Ctrl-k` | delete to end of line | +| `backspace` | delete previous char | +| `Ctrl-s` | insert a word under doc cursor, may be changed to Ctrl-r Ctrl-w later | +| `Ctrl-p`, `Up` | select previous history | +| `Ctrl-n`, `Down` | select next history | +| `Tab` | slect next completion item | +| `BackTab` | slect previous completion item | +| `Enter` | Open selected | + diff --git a/book/src/remapping.md b/book/src/remapping.md index 81f45da3..3369f031 100644 --- a/book/src/remapping.md +++ b/book/src/remapping.md @@ -2,7 +2,7 @@ One-way key remapping is temporarily supported via a simple TOML configuration file. (More powerful solutions such as rebinding via commands will be -available in the feature). +available in the future). To remap keys, write a `config.toml` file in your `helix` configuration directory (default `~/.config/helix` in Linux systems) with a structure like diff --git a/book/src/themes.md b/book/src/themes.md index a99e3a59..ecbbb6e9 100644 --- a/book/src/themes.md +++ b/book/src/themes.md @@ -103,8 +103,6 @@ We use a similar set of scopes as [SublimeText](https://www.sublimetext.com/docs/scope_naming.html). See also [TextMate](https://macromates.com/manual/en/language_grammars) scopes. -- `escape` (TODO: rename to (constant).character.escape) - - `type` - Types - `builtin` - Primitive types provided by the language (`int`, `usize`) @@ -112,13 +110,17 @@ We use a similar set of scopes as - `builtin` Special constants provided by the language (`true`, `false`, `nil` etc) - `boolean` - `character` + - `escape` + - `numeric` (numbers) + - `integer` + - `float` -- `number` (TODO: rename to constant.number/.numeric.{integer, float, complex}) - `string` (TODO: string.quoted.{single, double}, string.raw/.unquoted)? - `regexp` - Regular expressions - `special` - `path` - `url` + - `symbol` - Erlang/Elixir atoms, Ruby symbols, Clojure keywords - `comment` - Code comments - `line` - Single line comments (`//`) @@ -128,7 +130,8 @@ We use a similar set of scopes as - `variable` - Variables - `builtin` - Reserved language variables (`self`, `this`, `super`, etc) - `parameter` - Function parameters - - `property` + - `other` + - `member` - Fields of composite data types (e.g. structs, unions) - `function` (TODO: ?) - `label` diff --git a/book/src/usage.md b/book/src/usage.md index 9ee8634c..71730fa8 100644 --- a/book/src/usage.md +++ b/book/src/usage.md @@ -2,6 +2,8 @@ (Currently not fully documented, see the [keymappings](./keymap.md) list for more.) +See [tutor.txt](https://github.com/helix-editor/helix/blob/master/runtime/tutor.txt) (accessible via `hx --tutor` or `:tutor`) for a vimtutor-like introduction. + ## Registers Vim-like registers can be used to yank and store text to be pasted later. Usage is similar, with `"` being used to select a register: @@ -49,9 +51,10 @@ Multiple characters are currently not supported, but planned. ## Textobjects -Currently supported: `word`, `surround`. +Currently supported: `word`, `surround`, `function`, `class`, `parameter`.  + - `ma` - Select around the object (`va` in vim, `<alt-a>` in kakoune) - `mi` - Select inside the object (`vi` in vim, `<alt-i>` in kakoune) @@ -60,5 +63,11 @@ Currently supported: `word`, `surround`. | --- | --- | | `w` | Word | | `(`, `[`, `'`, etc | Specified surround pairs | - -Textobjects based on treesitter, like `function`, `class`, etc are planned. +| `f` | Function | +| `c` | Class | +| `p` | Parameter | + +Note: `f`, `c`, etc need a tree-sitter grammar active for the current +document and a special tree-sitter query file to work properly. [Only +some grammars](https://github.com/search?q=repo%3Ahelix-editor%2Fhelix+filename%3Atextobjects.scm&type=Code&ref=advsearch&l=&l=) +currently have the query file implemented. Contributions are welcome ! |