Skip to content

Commit 898a1d1

Browse files
lambdalisuelambdalisue
committed
WIP: Add documentation
1 parent 4ad5cd4 commit 898a1d1

File tree

1 file changed

+246
-3
lines changed

1 file changed

+246
-3
lines changed

‎doc/fall.txt‎

Lines changed: 246 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,16 +8,259 @@ License: MIT License (See LICENSE)
88
CONTENTS *fall-contents*
99

1010
INTRODUCTION |fall-introduction|
11+
REQUIREMENTS |fall-requirements|
1112

1213

1314
=============================================================================
1415
INTRODUCTION *fall-introduction*
1516

16-
Fall (*fall.vim*) is a yet another fuzzy finder for Vim/Neovim written
17-
in Denops.
17+
Fall (*fall.vim*) is a yet another Fuzzy Finder for Vim/Neovim.
1818

19-
Denops: https://github.com/vim-denops/denops.vim
19+
It has the following distinct features
2020

21+
- Quick help with <F1> key
22+
- Support multiple matchers, sorters, renderers, and previewers
23+
- Submatch for fine-grained filtering
24+
- Action selector to select an action to invoke
25+
- Customizable with TypeScript
26+
27+
=============================================================================
28+
REQUIREMENTS *fall-requirements*
29+
30+
Fall is written in denops so users need to install denops.vim
31+
32+
denops.vim~
33+
An ecosystem for writing Vim/Neovim plugin in Deno.
34+
https://github.com/vim-denops/denops.vim
35+
36+
Additionally, the "nerdfont" renderer is enabled by default so configure your
37+
terminal to use a Nerd Font to display the icons correctly.
38+
39+
NerdFont~
40+
A collection of over 10,000 icons that are compatible with popular
41+
programming fonts.
42+
https://www.nerdfonts.com/
43+
44+
Disable the "nerdfont" renderer by removing it from the "renderers" option in
45+
the "custom.ts" file if you don't want to use the Nerd Font. See
46+
|fall-customization| for more information about the customization.
47+
48+
=============================================================================
49+
USAGE *fall-usage*
50+
51+
Fall provides a command |:Fall| which opens a floating window to filter the
52+
specified source. For example, to filter the files in the current directory,
53+
"file" source like this:
54+
>
55+
:Fall file
56+
<
57+
Then you can filter the files in the current directory with a picker window.
58+
If you want to filter the files in the specified directory, you can pass the
59+
directory path as an argument like this:
60+
>
61+
:Fall file /path/to/directory
62+
<
63+
Or if you want to filter the lines in the current buffer, you can use the
64+
"line" source like this:
65+
>
66+
:Fall line
67+
68+
In the picker window, you can use the following key mappings. Note that the
69+
actual key mappings may vary depending on the configuration and you can
70+
confirm the key mappings by invoking the help with the <F1> key.
71+
72+
<CR> Invoke the default action on the current or selected item(s)
73+
<Tab> Open an action selector and invoke the selected action
74+
<C-,> Select or unselect the current item
75+
<C-n> Move the cursor to the next item
76+
<C-p> Move the cursor to the previous item
77+
<Down> Move the cursor in preview window to the next line
78+
<Up> Move the cursor in preview window to the previous line
79+
<F1> Show help
80+
<F2> Switch to the next matcher
81+
<F3> Switch to the next sorter
82+
<F4> Switch to the next renderer
83+
<F5> Switch to the next previewer
84+
<
85+
See |fall-configuration-mappings| for more information about the mappings.
86+
87+
88+
=============================================================================
89+
CONFIGURATION *fall-configuration*
90+
91+
=============================================================================
92+
CUSTOMIZATION *fall-customization*
93+
94+
>ts
95+
import type { Entrypoint } from "jsr:@vim-fall/custom";
96+
import * as builtin from "jsr:@vim-fall/std/builtin";
97+
98+
export const main: Entrypoint = ({
99+
definePickerFromSource,
100+
definePickerFromCurator,
101+
}) => {
102+
// Define "file" picker
103+
definePickerFromSource("file", builtin.source.file, {
104+
matchers: [builtin.matcher.fzf],
105+
renderers: [
106+
builtin.renderer.nerdfont,
107+
builtin.renderer.noop,
108+
],
109+
actions: {
110+
...builtin.action.defaultOpenActions,
111+
...builtin.action.defaultSystemopenActions,
112+
...builtin.action.defaultCdActions,
113+
...builtin.action.defaultEchoActions,
114+
...builtin.action.defaultYankActions,
115+
},
116+
defaultAction: "open",
117+
});
118+
// Define "git-grep" picker
119+
definePickerFromCurator("git-grep", builtin.curator.gitGrep, {
120+
renderers: [
121+
builtin.renderer.nerdfont,
122+
builtin.renderer.noop,
123+
],
124+
actions: {
125+
...builtin.action.defaultOpenActions,
126+
...builtin.action.defaultSystemopenActions,
127+
...builtin.action.defaultCdActions,
128+
...builtin.action.defaultEchoActions,
129+
...builtin.action.defaultYankActions,
130+
},
131+
defaultAction: "open",
132+
});
133+
};
134+
<
135+
See "default.custom.ts" file in "denops/fall/_assets" directory for
136+
the default configuration.
137+
138+
139+
=============================================================================
140+
INTERFACE *fall-interface*
141+
142+
-----------------------------------------------------------------------------
143+
COMMAND *fall-command*
144+
145+
*:Fall*
146+
:Fall {source} [{cmdarg}]
147+
Open a picker window to filter the specified {source}. The {source} is
148+
a picker name defined in "custom.ts" file opened by the |:FallCustom|
149+
command. The {cmdarg} is a command argument passed to the source.
150+
151+
*:FallCustom*
152+
:FallCustom
153+
Open a "custom.ts" file to customize the picker. The "custom.ts" file
154+
is a TypeScript file which exports a function named "main" that
155+
defines pickers. When user update the file, the picker is reloaded
156+
automatically by the |:FallCustomReload| command.
157+
158+
See |g:fall_custom_path| for the path of the "custom.ts" file.
159+
160+
*:FallCustomReload*
161+
:FallCustomReload
162+
Reload the "custom.ts" file to apply the changes. Note that Deno
163+
caches the module in memory so the changes may not be applied until
164+
the Denops process is restarted.
165+
166+
See |:FallCustomRecache| for the command to recache the module cache.
167+
168+
*:FallCustomRecache*
169+
:FallCustomRecache
170+
Recache the Deno's local module cache. This command is useful when
171+
you want to update the dependencies in the "custom.ts" file.
172+
173+
-----------------------------------------------------------------------------
174+
AUTOCMD *fall-autocmd*
175+
176+
*FallPickerEnter*
177+
FallPickerEnter:{name}
178+
An |User| |autocmd| triggered when the picker window of the {name}
179+
picker is entered.
180+
181+
Use this event to define custom key mappings like:
182+
>vim
183+
function! s:my_fall() abort
184+
" Use <Up> and <Down> to navigate instead of <C-n> and <C-p>
185+
cnoremap <nowait> <Up> <Plug>(fall-list-prev)
186+
cnoremap <nowait> <Down> <Plug>(fall-list-next)
187+
" Disable horizontal scroll
188+
cnoremap <nowait> <Nop> <Plug>(fall-list-left)
189+
cnoremap <nowait> <Nop> <Plug>(fall-list-right)
190+
" Use <C-x> and <C-v> to open in split window
191+
cnoremap <nowait> <C-x> <Cmd>call fall#action('open:split')<CR>
192+
cnoremap <nowait> <C-v> <Cmd>call fall#action('open:vsplit')<CR>
193+
endfunction
194+
195+
augroup my_fall
196+
autocmd!
197+
autocmd User FallPickerEnter:* call s:my_fall()
198+
augroup END
199+
<
200+
Note that command mappings defined after this autocmd will be
201+
discarded prior to |FallPickerLeave| event so you won't need to
202+
invoke |:cunmap| command to remove the mappings.
203+
204+
See |FallPickerLeave| for the event triggered when the picker window
205+
is leaved.
206+
207+
*FallPickerLeave*
208+
FallPickerLeave:{name}
209+
An |User| |autocmd| triggered when the picker window of the {name}
210+
picker is leaved.
211+
212+
See |FallPickerEnter| for the event triggered when the picker window
213+
is entered.
214+
215+
*FallCustomLoaded*
216+
FallCustomLoaded
217+
An |User| |autocmd| triggered when the "custom.ts" file is loaded.
218+
See |:FallCustomReload| for the command to reload the "custom.ts"
219+
file.
220+
221+
*FallCustomRecached*
222+
FallCustomRecached
223+
An |User| |autocmd| triggered when the Deno's local module cache of
224+
dependencies in the "custom.ts" file is recached.
225+
See |:FallCustomRecache| for the command to recache the module cache.
226+
227+
*FallPreviewRendered*
228+
FallPreviewRendered:{filename}
229+
An |User| |autocmd| triggered when the preview window of the picker
230+
window is rendered. The {filename} is the name of the file rendered.
231+
232+
Use this event to configure the preview window like:
233+
>vim
234+
function! s:my_fall_preview() abort
235+
" Enable line number on the preview window (Not available on Vim)
236+
setlocal number
237+
endfunction
238+
239+
augroup my_fall_preview
240+
autocmd!
241+
autocmd User FallPreviewRendered:* call s:my_fall_preview()
242+
augroup END
243+
<
244+
-----------------------------------------------------------------------------
245+
FILETYPE *fall-filetype*
246+
247+
Fall provides the following filetypes for the components of the picker window.
248+
249+
fall-input The filetype of the input component.
250+
fall-list The filetype of the list component.
251+
fall-help The filetype of the help component.
252+
253+
For example, to enable |list| option for the list component, you can use the
254+
|FileType| |autocmd| like:
255+
>vim
256+
augroup my_fall_list
257+
autocmd!
258+
autocmd FileType fall-list setlocal list
259+
augroup END
260+
<
261+
Note that the filetype of the preview component is determined by the previewer
262+
used in the picker so you need to use |FallPreviewRendered| instead to
263+
configure the preview window.
21264

22265
=============================================================================
23266
vim:tw=78:fo=tcq2mM:ts=8:ft=help:norl

0 commit comments

Comments
 (0)