Skip to content

Commit 01581f9

Browse files
gokcehangokcehan
committed
update documentation
1 parent 54315ff commit 01581f9

File tree

3 files changed

+162
-86
lines changed

3 files changed

+162
-86
lines changed

‎doc.go

Lines changed: 75 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -53,23 +53,23 @@ The following commands are provided by lf without default keybindings:
5353
The following command line commands are provided by lf with default
5454
keybindings:
5555
56-
cmd-escape (default '<esc>')
57-
cmd-comp (default '<tab>')
58-
cmd-enter (default '<c-j>' and '<enter>')
59-
cmd-hist-next (default '<c-n>')
60-
cmd-hist-prev (default '<c-p>')
61-
cmd-delete (default '<c-d>' and '<delete>')
62-
cmd-delete-back (default '<bs>' and '<bs2>')
63-
cmd-left (default '<c-b>' and '<left>')
64-
cmd-right (default '<c-f>' and '<right>')
65-
cmd-beg (default '<c-a>' and '<home>')
66-
cmd-end (default '<c-e>' and '<end>')
67-
cmd-delete-beg (default '<c-u>')
68-
cmd-delete-end (default '<c-k>')
69-
cmd-delete-word (default '<c-w>')
70-
cmd-put (default '<c-y>')
71-
cmd-transpose (default '<c-t>')
72-
cmd-interrupt (default '<c-c>')
56+
cmd-escape (default '<esc>')
57+
cmd-comp (default '<tab>')
58+
cmd-enter (default '<c-j>' and '<enter>')
59+
cmd-hist-next (default '<c-n>')
60+
cmd-hist-prev (default '<c-p>')
61+
cmd-delete (default '<c-d>' and '<delete>')
62+
cmd-delete-back (default '<bs>' and '<bs2>')
63+
cmd-left (default '<c-b>' and '<left>')
64+
cmd-right (default '<c-f>' and '<right>')
65+
cmd-beg (default '<c-a>' and '<home>')
66+
cmd-end (default '<c-e>' and '<end>')
67+
cmd-delete-beg (default '<c-u>')
68+
cmd-delete-end (default '<c-k>')
69+
cmd-delete-word (default '<c-w>')
70+
cmd-put (default '<c-y>')
71+
cmd-transpose (default '<c-t>')
72+
cmd-interrupt (default '<c-c>')
7373
7474
The following options can be used to customize the behavior of lf:
7575
@@ -146,9 +146,9 @@ The following command prefixes are used by lf:
146146
147147
: read (default) builtin/custom command
148148
$ shell shell command
149-
% shell-pipe shell command displaying the output
149+
% shell-pipe shell command running with the ui
150150
! shell-wait shell command waiting for key press
151-
& shell-async asynchronous shell command
151+
& shell-async shell command running asynchronously
152152
/ search search file in current directory
153153
? search-back search file in the reverse order
154154
@@ -219,7 +219,7 @@ prefix.
219219
set info time
220220
}}
221221
222-
Mappings
222+
Push Mappings
223223
224224
The usual way to map a key sequence is to assign it to a named or unnamed
225225
command. While this provides a clean way to remap builtin keys as well as other
@@ -244,12 +244,11 @@ commands it is possible to accidentally create recursive bindings:
244244
245245
These types of bindings create a deadlock when executed.
246246
247-
Commands
247+
Shell Commands ($)
248248
249-
For demonstration let us write a shell command to move selected file(s) to
250-
trash.
251-
252-
A first attempt to write such a command may look like this:
249+
Regular shell commands are the most basic command type that is useful for many
250+
purposes. For example, we can write a shell command to move selected file(s) to
251+
trash. A first attempt to write such a command may look like this:
253252
254253
cmd trash ${{
255254
mkdir -p ~/.trash
@@ -289,6 +288,47 @@ could use the 'ifs' option to set it for all shell commands (i.e. 'set ifs
289288
behave unexpectedly for new users. However, use of this option is highly
290289
recommended and it is assumed in the rest of the documentation.
291290
291+
Piping Shell Commands (%)
292+
293+
Regular shell commands have some limitations in some cases. When an output or
294+
error message is given and the command exits afterwards, the ui is immediately
295+
resumed and there is no way to see the message without dropping to shell again.
296+
Also, even when there is no output or error, the ui still needs to be paused
297+
while the command is running. This can cause flickering on the screen for short
298+
commands and similar distractions for longer commands.
299+
300+
Instead of pausing the ui, piping shell commands connects stdin, stdout, and
301+
stderr of the command to the statline in the bottom of the ui. This can be
302+
useful for programs following the unix philosophy to give no output in the
303+
success case, and brief error messages or prompts in other cases.
304+
305+
For example, following rename command prompts for overwrite in the statline if
306+
there is an existing file with the given name:
307+
308+
cmd rename %mv -i $f $1
309+
310+
You can also output error messages in the command and it will show up in the
311+
statline. For example, an alternative rename command may look like this:
312+
313+
cmd rename %[ -e $1 ] && printf "file exists" || mv $f $1
314+
315+
One thing to be careful is that although input is still line buffered, output
316+
and error are byte buffered and verbose commands will be very slow to display.
317+
318+
Waiting Shell Commands (!)
319+
320+
Waiting shell commands are similar to regular shell commands except that they
321+
wait for a key press when the command is finished. These can be useful to see
322+
the output of a program before the ui is resumed. Waiting shell commands are
323+
more appropriate than piping shell commands when the command is verbose and the
324+
output is best displayed as multiline.
325+
326+
Asynchronous Shell Commands (&)
327+
328+
Asynchronous shell commands are used to start a command in the background and
329+
then resume operation without waiting for the command to finish. Stdin, stdout,
330+
and stderr of the command is neither connected to the terminal nor to the ui.
331+
292332
Remote Commands
293333
294334
One of the more advanced features in lf is remote commands. All clients connect
@@ -325,15 +365,17 @@ a shell command:
325365
lf -remote "send $id echo hello world"
326366
327367
Since lf does not have control flow syntax, remote commands are used for such
328-
needs. A common use is to display an error message back in the client. You can
329-
implement a safe rename command which does not overwrite an existing file or
330-
directory as such:
331-
332-
cmd rename ${{
333-
if [ -e $1 ]; then
334-
lf -remote "send $id echo file exists"
368+
needs. For example, you can configure the number of columns in the ui with
369+
respect to the terminal width as follows:
370+
371+
cmd recol ${{
372+
w=$(tput cols)
373+
if [ $w -le 80 ]; then
374+
lf -remote "send $id set ratios 1:2"
375+
elif [ $w -le 160 ]; then
376+
lf -remote "send $id set ratios 1:2:3"
335377
else
336-
mv $f $1
378+
lf -remote "send $id set ratios 1:2:3:5"
337379
fi
338380
}}
339381

‎docstring.go

Lines changed: 79 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -57,23 +57,23 @@ The following commands are provided by lf without default keybindings:
5757
The following command line commands are provided by lf with default
5858
keybindings:
5959
60-
cmd-escape (default '<esc>')
61-
cmd-comp (default '<tab>')
62-
cmd-enter (default '<c-j>' and '<enter>')
63-
cmd-hist-next (default '<c-n>')
64-
cmd-hist-prev (default '<c-p>')
65-
cmd-delete (default '<c-d>' and '<delete>')
66-
cmd-delete-back (default '<bs>' and '<bs2>')
67-
cmd-left (default '<c-b>' and '<left>')
68-
cmd-right (default '<c-f>' and '<right>')
69-
cmd-beg (default '<c-a>' and '<home>')
70-
cmd-end (default '<c-e>' and '<end>')
71-
cmd-delete-beg (default '<c-u>')
72-
cmd-delete-end (default '<c-k>')
73-
cmd-delete-word (default '<c-w>')
74-
cmd-put (default '<c-y>')
75-
cmd-transpose (default '<c-t>')
76-
cmd-interrupt (default '<c-c>')
60+
cmd-escape (default '<esc>')
61+
cmd-comp (default '<tab>')
62+
cmd-enter (default '<c-j>' and '<enter>')
63+
cmd-hist-next (default '<c-n>')
64+
cmd-hist-prev (default '<c-p>')
65+
cmd-delete (default '<c-d>' and '<delete>')
66+
cmd-delete-back (default '<bs>' and '<bs2>')
67+
cmd-left (default '<c-b>' and '<left>')
68+
cmd-right (default '<c-f>' and '<right>')
69+
cmd-beg (default '<c-a>' and '<home>')
70+
cmd-end (default '<c-e>' and '<end>')
71+
cmd-delete-beg (default '<c-u>')
72+
cmd-delete-end (default '<c-k>')
73+
cmd-delete-word (default '<c-w>')
74+
cmd-put (default '<c-y>')
75+
cmd-transpose (default '<c-t>')
76+
cmd-interrupt (default '<c-c>')
7777
7878
The following options can be used to customize the behavior of lf:
7979
@@ -153,9 +153,9 @@ The following command prefixes are used by lf:
153153
154154
: read (default) builtin/custom command
155155
$ shell shell command
156-
% shell-pipe shell command displaying the output
156+
% shell-pipe shell command running with the ui
157157
! shell-wait shell command waiting for key press
158-
& shell-async asynchronous shell command
158+
& shell-async shell command running asynchronously
159159
/ search search file in current directory
160160
? search-back search file in the reverse order
161161
@@ -228,7 +228,7 @@ proper prefix.
228228
}}
229229
230230
231-
Mappings
231+
Push Mappings
232232
233233
The usual way to map a key sequence is to assign it to a named or unnamed
234234
command. While this provides a clean way to remap builtin keys as well as
@@ -254,13 +254,12 @@ of commands it is possible to accidentally create recursive bindings:
254254
255255
These types of bindings create a deadlock when executed.
256256
257+
Shell Commands ($)
257258
258-
Commands
259-
260-
For demonstration let us write a shell command to move selected file(s) to
261-
trash.
262-
263-
A first attempt to write such a command may look like this:
259+
Regular shell commands are the most basic command type that is useful for
260+
many purposes. For example, we can write a shell command to move selected
261+
file(s) to trash. A first attempt to write such a command may look like
262+
this:
264263
265264
cmd trash ${{
266265
mkdir -p ~/.trash
@@ -301,6 +300,50 @@ or '$rm $fs' would simply work). This option is not set by default as it can
301300
behave unexpectedly for new users. However, use of this option is highly
302301
recommended and it is assumed in the rest of the documentation.
303302
303+
Piping Shell Commands (%)
304+
305+
Regular shell commands have some limitations in some cases. When an output
306+
or error message is given and the command exits afterwards, the ui is
307+
immediately resumed and there is no way to see the message without dropping
308+
to shell again. Also, even when there is no output or error, the ui still
309+
needs to be paused while the command is running. This can cause flickering
310+
on the screen for short commands and similar distractions for longer
311+
commands.
312+
313+
Instead of pausing the ui, piping shell commands connects stdin, stdout, and
314+
stderr of the command to the statline in the bottom of the ui. This can be
315+
useful for programs following the unix philosophy to give no output in the
316+
success case, and brief error messages or prompts in other cases.
317+
318+
For example, following rename command prompts for overwrite in the statline
319+
if there is an existing file with the given name:
320+
321+
cmd rename %mv -i $f $1
322+
323+
You can also output error messages in the command and it will show up in the
324+
statline. For example, an alternative rename command may look like this:
325+
326+
cmd rename %[ -e $1 ] && printf "file exists" || mv $f $1
327+
328+
One thing to be careful is that although input is still line buffered,
329+
output and error are byte buffered and verbose commands will be very slow to
330+
display.
331+
332+
Waiting Shell Commands (!)
333+
334+
Waiting shell commands are similar to regular shell commands except that
335+
they wait for a key press when the command is finished. These can be useful
336+
to see the output of a program before the ui is resumed. Waiting shell
337+
commands are more appropriate than piping shell commands when the command is
338+
verbose and the output is best displayed as multiline.
339+
340+
Asynchronous Shell Commands (&)
341+
342+
Asynchronous shell commands are used to start a command in the background
343+
and then resume operation without waiting for the command to finish. Stdin,
344+
stdout, and stderr of the command is neither connected to the terminal nor
345+
to the ui.
346+
304347
305348
Remote Commands
306349
@@ -339,15 +382,17 @@ calling the following in a shell command:
339382
lf -remote "send $id echo hello world"
340383
341384
Since lf does not have control flow syntax, remote commands are used for
342-
such needs. A common use is to display an error message back in the client.
343-
You can implement a safe rename command which does not overwrite an existing
344-
file or directory as such:
345-
346-
cmd rename ${{
347-
if [ -e $1 ]; then
348-
lf -remote "send $id echo file exists"
385+
such needs. For example, you can configure the number of columns in the ui
386+
with respect to the terminal width as follows:
387+
388+
cmd recol ${{
389+
w=$(tput cols)
390+
if [ $w -le 80 ]; then
391+
lf -remote "send $id set ratios 1:2"
392+
elif [ $w -le 160 ]; then
393+
lf -remote "send $id set ratios 1:2:3"
349394
else
350-
mv $f $1
395+
lf -remote "send $id set ratios 1:2:3:5"
351396
fi
352397
}}
353398

‎etc/lfrc.example

Lines changed: 8 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -37,24 +37,15 @@ cmd open-file ${{
3737
}}
3838

3939
# rename current file without overwrite
40-
cmd rename ${{
41-
if [ -e $1 ]; then
42-
lf -remote "send $id echo file exists"
43-
else
44-
mv $f $1
45-
fi
46-
}}
40+
cmd rename %[ -e $1 ] && printf "file exists" || mv $f $1
4741
map r push :rename<space>
4842

49-
# show disk usage
50-
cmd usage $du -h . | less
51-
5243
# make sure trash folder exists
53-
$mkdir -p ~/.trash
44+
%mkdir -p ~/.trash
5445

5546
# move current file or selected files to trash folder
5647
# (also see 'man mv' for backup/overwrite options)
57-
cmd trash $mv $fx ~/.trash
48+
cmd trash %mv $fx ~/.trash
5849

5950
# remove current file or selected files (prompting)
6051
cmd remove ${{
@@ -66,7 +57,7 @@ cmd remove ${{
6657

6758
# extract the current file with the right command
6859
# (xkcd link: https://xkcd.com/1168/)
69-
cmd extract ${{
60+
cmd extract %{{
7061
case $f in
7162
*.tar.bz|*.tar.bz2|*.tbz|*.tbz2) tar xjvf $f;;
7263
*.tar.gz|*.tgz) tar xzvf $f;;
@@ -77,12 +68,10 @@ cmd extract ${{
7768
esac
7869
}}
7970

80-
# compress marked files with tar and gunzip
81-
# This command takes the output name without '.tar.gz' suffix as an argument
82-
# (e.g. 'compress foo' creates 'foo.tar.gz').
83-
cmd compress ${{
71+
# compress current file or selected files with tar and gunzip
72+
cmd compress %{{
8473
mkdir $1
85-
cp $fs $1
86-
tar czvf $1.tar.gz $1
74+
cp -r $fx $1
75+
tar czf $1.tar.gz $1
8776
rm -rf $1
8877
}}

0 commit comments

Comments
 (0)