Skip to content

Commit 15fa3ec

Browse files
lambdalisuelambdalisue
authored
Update README.md
1 parent 4dfb102 commit 15fa3ec

File tree

1 file changed

+144
-71
lines changed

1 file changed

+144
-71
lines changed

‎README.md

Lines changed: 144 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
# 🍂 fall
1+
# 🍂 Fall
22

33
[![Test](https://github.com/vim-fall/fall.vim/actions/workflows/test.yml/badge.svg)](https://github.com/vim-fall/fall.vim/actions/workflows/test.yml)
44
[![Deno](https://img.shields.io/badge/Deno%202.x-333?logo=deno&logoColor=fff)](#)
55
[![codecov](https://codecov.io/gh/vim-fall/fall.vim/graph/badge.svg?token=k2ZTes7Kln)](https://codecov.io/gh/vim-fall/fall.vim)
66
[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
7-
[![vim help](https://img.shields.io/badge/vim-%3Ah%20fall-orange.svg)](doc/fall.txt)
7+
[![Vim Help](https://img.shields.io/badge/vim-%3Ah%20fall-orange.svg)](doc/fall.txt)
88

99
<div align="center">
1010

@@ -13,26 +13,26 @@
1313
</div>
1414

1515
Fall is a fuzzy finder for Vim and Neovim, implemented in [Denops], and stands
16-
for "Filter All."
16+
for **"Filter All."**
1717

18-
> [!NOTE]
18+
> [!WARNING]
1919
>
20-
> Beta version. Please be aware that there might be backward incompatible
21-
> changes.
20+
> This is a beta version. Please be aware that there might be
21+
> backward-incompatible changes.
2222
2323
[Denops]: https://github.com/vim-denops/denops.vim
2424

2525
## Requirements
2626

2727
Users must install [Deno] version 2.x. Additionally, the `nerdfont` renderer is
28-
enabled by default so configure your terminal to use a [NerdFont] or disable it
29-
by removing `builtin.renderer.nerdfont` renderer from the configuration
28+
enabled by default, so configure your terminal to use a [NerdFont], or disable
29+
it by removing the `builtin.renderer.nerdfont` renderer from the configuration
3030
(`:FallConfig`).
3131

3232
[Deno]: https://deno.land
3333
[NerdFont]: https://www.nerdfonts.com
3434

35-
Note that Deno version 1.x. is not tested and not supported.
35+
Note that Deno version 1.x is not tested and not supported.
3636

3737
## Installation
3838

@@ -48,97 +48,170 @@ Plug 'vim-fall/fall.vim'
4848

4949
## Usage
5050

51-
Use `:Fall` command to open the fuzzy finder. The command accepts the following
52-
arguments:
51+
Use the `:Fall` command to open the fuzzy finder. The command accepts the
52+
following arguments:
5353

5454
```
5555
Fall {source} {source_args}...
5656
```
5757

58-
For example, if you'd like to use `file` source, you can use the following
58+
For example, if you'd like to use the `file` source, you can use the following:
5959

6060
```
6161
Fall file
6262
```
6363

64-
Or `line` source with `README.md` as an argument
64+
Or use the `line` source with `README.md` as an argument:
6565

6666
```
6767
Fall line README.md
6868
```
6969

70+
## Key Mappings
71+
72+
> [!NOTE]
73+
>
74+
> You can confirm your actual key mappings by opening the help window (`<F1>`).
75+
>
76+
77+
| Key Mapping | Description | Plug Mapping |
78+
| :------------- | :------------------------------------------------------------------ | :------------------------------------------ |
79+
| `<C-t>` | Move the cursor of the list component to the first item | `<Plug>(fall-list-first)` |
80+
| `<C-g>` | Move the cursor of the list component to the last item | `<Plug>(fall-list-last)` |
81+
| `<C-p>` | Move the cursor of the list component to the previous item | `<Plug>(fall-list-prev)` |
82+
| `<C-n>` | Move the cursor of the list component to the next item | `<Plug>(fall-list-next)` |
83+
| `<C-u>` | Move the cursor of the list component up by `&scroll` | `<Plug>(fall-list-prev:scroll)` |
84+
| `<C-d>` | Move the cursor of the list component down by `&scroll` | `<Plug>(fall-list-next:scroll)` |
85+
| `<PageUp>` | Move the content of the list component to the left | `<Plug>(fall-list-left)` |
86+
| `<PageDown>` | Move the content of the list component to the right | `<Plug>(fall-list-right)` |
87+
| `<S-PageUp>` | Move the content of the list component to the left by `&scroll` | `<Plug>(fall-list-left:scroll)` |
88+
| `<S-PageDown>` | Move the content of the list component to the right by `&scroll` | `<Plug>(fall-list-right:scroll)` |
89+
| `<C-,>` | Select the current item in the list component | `<Plug>(fall-select)` |
90+
| `<C-.>` | Select all items in the list component | `<Plug>(fall-select-all)` |
91+
| `<C-j>` | Select and move the cursor to the next item | `<Plug>(fall-select)<Plug>(fall-list-next)` |
92+
| `<C-k>` | Move the cursor to the previous item and select it | `<Plug>(fall-list-prev)<Plug>(fall-select)` |
93+
| `<M-Home>` | Move the cursor of the preview component to the first line | `<Plug>(fall-preview-first)` |
94+
| `<M-End>` | Move the cursor of the preview component to the last line | `<Plug>(fall-preview-last)` |
95+
| `<M-Up>` | Move the cursor of the preview component to the previous line | `<Plug>(fall-preview-prev)` |
96+
| `<M-Down>` | Move the cursor of the preview component to the next line | `<Plug>(fall-preview-next)` |
97+
| `<S-Up>` | Move the cursor of the preview component up by `&scroll` | `<Plug>(fall-preview-prev:scroll)` |
98+
| `<S-Down>` | Move the cursor of the preview component down by `&scroll` | `<Plug>(fall-preview-next:scroll)` |
99+
| `<M-Left>` | Move the content of the preview component to the left | `<Plug>(fall-preview-left)` |
100+
| `<M-Right>` | Move the content of the preview component to the right | `<Plug>(fall-preview-right)` |
101+
| `<S-Left>` | Move the content of the preview component to the left by `&scroll` | `<Plug>(fall-preview-left:scroll)` |
102+
| `<S-Right>` | Move the content of the preview component to the right by `&scroll` | `<Plug>(fall-preview-right:scroll)` |
103+
| `<Tab>` | Open an action selector to execute an action | `<Plug>(fall-action-select)` |
104+
| `<F1>` | Open or close the help window | `<Plug>(fall-help)` |
105+
| `<S-Home>` | Go to the previous page in the help window | `<Plug>(fall-help-prev)` |
106+
| `<S-End>` | Go to the next page in the help window | `<Plug>(fall-help-next)` |
107+
| `<F2>` | Switch to the next matcher in the current picker | `<Plug>(fall-switch-matcher-next)` |
108+
| `<F3>` | Switch to the next sorter in the current picker | `<Plug>(fall-switch-sorter-next)` |
109+
| `<F4>` | Switch to the next renderer in the current picker | `<Plug>(fall-switch-renderer-next)` |
110+
| `<F5>` | Switch to the next previewer in the current picker | `<Plug>(fall-switch-previewer-next)` |
111+
112+
113+
### Customization
114+
115+
Use `FallPickerEnter:*` autocmd to customize mappings in the picker window.
116+
117+
```vim
118+
function! s:fall_mappings() abort
119+
" Use <Up> and <Down> to move the cursor in the list component instead of <C-p> and <C-n>
120+
cnoremap <silent> <Up> <Plug>(fall-list-prev)
121+
cnoremap <silent> <Down> <Plug>(fall-list-next)
122+
" Disable horizontal scrolling
123+
cnoremap <silent> <Nop> <Plug>(fall-list-left)
124+
cnoremap <silent> <Nop> <Plug>(fall-list-right)
125+
endfunction
126+
127+
augroup my_fall_mapping
128+
autocmd!
129+
autocmd User FallPickerEnter:* call s:fall_mappings()
130+
augroup END
131+
```
132+
133+
If you want to invoke an action with a key mapping, you can use the
134+
`fall#action()` function.
135+
136+
```vim
137+
function! s:fall_mappings() abort
138+
cnoremap <silent> <C-e> <Cmd>call fall#action('open')<CR>
139+
cnoremap <silent> <C-x> <Cmd>call fall#action('open:split')<CR>
140+
cnoremap <silent> <C-v> <Cmd>call fall#action('open:vsplit')<CR>
141+
cnoremap <silent> <C-t> <Cmd>call fall#action('open:tabedit')<CR>
142+
endfunction
143+
144+
augroup my_fall_mapping
145+
autocmd!
146+
autocmd User FallPickerEnter:* call s:fall_mappings()
147+
augroup END
148+
```
149+
150+
If you want to apply mappings to a particular picker, you can specify the picker
151+
name in the `FallPickerEnter:{name}` autocmd.
152+
153+
```vim
154+
" These mappings are only available on the "file" picker.
155+
function! s:fall_mappings_file() abort
156+
cnoremap <silent> <C-e> <Cmd>call fall#action('open')<CR>
157+
cnoremap <silent> <C-x> <Cmd>call fall#action('open:split')<CR>
158+
cnoremap <silent> <C-v> <Cmd>call fall#action('open:vsplit')<CR>
159+
cnoremap <silent> <C-t> <Cmd>call fall#action('open:tabedit')<CR>
160+
endfunction
161+
162+
augroup my_fall_mapping
163+
autocmd!
164+
autocmd User FallPickerEnter:file call s:fall_mappings_file()
165+
augroup END
166+
```
167+
168+
If you want to completely disable the default key mappings, use the
169+
`g:fall_disable_default_mappings` variable.
170+
171+
```vim
172+
let g:fall_disable_default_mappings = v:true
173+
```
174+
70175
## Configuration
71176

72-
Use `:FallConfig` command to open the configuration file. The configuration file
73-
is written in TypeScript. The configuration is reloaded automatically when the
74-
file is saved.
177+
Use the `:FallConfig` command to open the configuration file. The configuration
178+
file is written in TypeScript and is reloaded automatically when the file is
179+
saved.
75180

76181
```
77182
FallConfig
78183
```
79184

80-
The following is a minimum configuration example. It only defines several
81-
fundamental pickers as default configurations.
185+
The following is a minimal configuration example. It defines two pickers.
82186

83187
```typescript
84188
import { type Entrypoint } from "jsr:@vim-fall/config@^0.17.3";
85189
import * as builtin from "jsr:@vim-fall/std@^0.6.0/builtin";
86190

87191
export const main: Entrypoint = ({
88-
defineItemPickerFromSource,
89-
defineItemPickerFromCurator,
192+
defineItemPickerFromSource,
193+
defineItemPickerFromCurator,
90194
}) => {
91-
defineItemPickerFromCurator("git-grep", builtin.curator.gitGrep, {
92-
previewers: [builtin.previewer.file],
93-
actions: {
94-
...builtin.action.defaultOpenActions,
95-
...builtin.action.defaultSystemopenActions,
96-
...builtin.action.defaultQuickfixActions,
97-
},
98-
defaultAction: "open",
99-
});
100-
101-
defineItemPickerFromSource("file", builtin.source.file, {
102-
matchers: [builtin.matcher.fzf],
103-
previewers: [builtin.previewer.file],
104-
actions: {
105-
...builtin.action.defaultOpenActions,
106-
...builtin.action.defaultSystemopenActions,
107-
...builtin.action.defaultQuickfixActions,
108-
},
109-
defaultAction: "open",
110-
});
111-
112-
defineItemPickerFromSource("line", builtin.source.line, {
113-
matchers: [builtin.matcher.fzf],
114-
previewers: [builtin.previewer.buffer],
115-
actions: {
116-
...builtin.action.defaultOpenActions,
117-
...builtin.action.defaultBufferActions,
118-
...builtin.action.defaultQuickfixActions,
119-
},
120-
defaultAction: "open",
121-
});
122-
123-
defineItemPickerFromSource("buffer", builtin.source.buffer, {
124-
matchers: [builtin.matcher.fzf],
125-
previewers: [builtin.previewer.buffer],
126-
actions: {
127-
...builtin.action.defaultOpenActions,
128-
...builtin.action.defaultBufferActions,
129-
...builtin.action.defaultQuickfixActions,
130-
},
131-
defaultAction: "open",
132-
});
133-
134-
defineItemPickerFromSource("help", builtin.source.helptag, {
135-
matchers: [builtin.matcher.fzf],
136-
previewers: [builtin.previewer.helptag],
137-
actions: {
138-
...builtin.action.defaultHelpActions,
139-
},
140-
defaultAction: "help",
141-
});
195+
defineItemPickerFromCurator("git-grep", builtin.curator.gitGrep, {
196+
previewers: [builtin.previewer.file],
197+
actions: {
198+
...builtin.action.defaultOpenActions,
199+
...builtin.action.defaultSystemopenActions,
200+
...builtin.action.defaultQuickfixActions,
201+
},
202+
defaultAction: "open",
203+
});
204+
205+
defineItemPickerFromSource("file", builtin.source.file, {
206+
matchers: [builtin.matcher.fzf],
207+
previewers: [builtin.previewer.file],
208+
actions: {
209+
...builtin.action.defaultOpenActions,
210+
...builtin.action.defaultSystemopenActions,
211+
...builtin.action.defaultQuickfixActions,
212+
},
213+
defaultAction: "open",
214+
});
142215
};
143216
```
144217

0 commit comments

Comments
 (0)