From 01581f902fe1fab8ddd21bb7c2cf6ec78d8d1ace Mon Sep 17 00:00:00 2001 From: Gokcehan Date: Fri, 6 Apr 2018 22:49:50 +0300 Subject: [PATCH] update documentation --- doc.go | 106 ++++++++++++++++++++++++++++++-------------- docstring.go | 111 +++++++++++++++++++++++++++++++++-------------- etc/lfrc.example | 27 ++++-------- 3 files changed, 160 insertions(+), 84 deletions(-) diff --git a/doc.go b/doc.go index 23cd14c..20785fe 100644 --- a/doc.go +++ b/doc.go @@ -53,23 +53,23 @@ The following commands are provided by lf without default keybindings: The following command line commands are provided by lf with default keybindings: - cmd-escape (default '') - cmd-comp (default '') - cmd-enter (default '' and '') - cmd-hist-next (default '') - cmd-hist-prev (default '') - cmd-delete (default '' and '') - cmd-delete-back (default '' and '') - cmd-left (default '' and '') - cmd-right (default '' and '') - cmd-beg (default '' and '') - cmd-end (default '' and '') - cmd-delete-beg (default '') - cmd-delete-end (default '') - cmd-delete-word (default '') - cmd-put (default '') - cmd-transpose (default '') - cmd-interrupt (default '') + cmd-escape (default '') + cmd-comp (default '') + cmd-enter (default '' and '') + cmd-hist-next (default '') + cmd-hist-prev (default '') + cmd-delete (default '' and '') + cmd-delete-back (default '' and '') + cmd-left (default '' and '') + cmd-right (default '' and '') + cmd-beg (default '' and '') + cmd-end (default '' and '') + cmd-delete-beg (default '') + cmd-delete-end (default '') + cmd-delete-word (default '') + cmd-put (default '') + cmd-transpose (default '') + cmd-interrupt (default '') The following options can be used to customize the behavior of lf: @@ -146,9 +146,9 @@ The following command prefixes are used by lf: : read (default) builtin/custom command $ shell shell command - % shell-pipe shell command displaying the output + % shell-pipe shell command running with the ui ! shell-wait shell command waiting for key press - & shell-async asynchronous shell command + & shell-async shell command running asynchronously / search search file in current directory ? search-back search file in the reverse order @@ -219,7 +219,7 @@ prefix. set info time }} -Mappings +Push Mappings The usual way to map a key sequence is to assign it to a named or unnamed 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: These types of bindings create a deadlock when executed. -Commands +Shell Commands ($) -For demonstration let us write a shell command to move selected file(s) to -trash. - -A first attempt to write such a command may look like this: +Regular shell commands are the most basic command type that is useful for many +purposes. For example, we can write a shell command to move selected file(s) to +trash. A first attempt to write such a command may look like this: cmd trash ${{ mkdir -p ~/.trash @@ -289,6 +288,47 @@ could use the 'ifs' option to set it for all shell commands (i.e. 'set ifs behave unexpectedly for new users. However, use of this option is highly recommended and it is assumed in the rest of the documentation. +Piping Shell Commands (%) + +Regular shell commands have some limitations in some cases. When an output or +error message is given and the command exits afterwards, the ui is immediately +resumed and there is no way to see the message without dropping to shell again. +Also, even when there is no output or error, the ui still needs to be paused +while the command is running. This can cause flickering on the screen for short +commands and similar distractions for longer commands. + +Instead of pausing the ui, piping shell commands connects stdin, stdout, and +stderr of the command to the statline in the bottom of the ui. This can be +useful for programs following the unix philosophy to give no output in the +success case, and brief error messages or prompts in other cases. + +For example, following rename command prompts for overwrite in the statline if +there is an existing file with the given name: + + cmd rename %mv -i $f $1 + +You can also output error messages in the command and it will show up in the +statline. For example, an alternative rename command may look like this: + + cmd rename %[ -e $1 ] && printf "file exists" || mv $f $1 + +One thing to be careful is that although input is still line buffered, output +and error are byte buffered and verbose commands will be very slow to display. + +Waiting Shell Commands (!) + +Waiting shell commands are similar to regular shell commands except that they +wait for a key press when the command is finished. These can be useful to see +the output of a program before the ui is resumed. Waiting shell commands are +more appropriate than piping shell commands when the command is verbose and the +output is best displayed as multiline. + +Asynchronous Shell Commands (&) + +Asynchronous shell commands are used to start a command in the background and +then resume operation without waiting for the command to finish. Stdin, stdout, +and stderr of the command is neither connected to the terminal nor to the ui. + Remote Commands One of the more advanced features in lf is remote commands. All clients connect @@ -325,15 +365,17 @@ a shell command: lf -remote "send $id echo hello world" Since lf does not have control flow syntax, remote commands are used for such -needs. A common use is to display an error message back in the client. You can -implement a safe rename command which does not overwrite an existing file or -directory as such: +needs. For example, you can configure the number of columns in the ui with +respect to the terminal width as follows: - cmd rename ${{ - if [ -e $1 ]; then - lf -remote "send $id echo file exists" + cmd recol ${{ + w=$(tput cols) + if [ $w -le 80 ]; then + lf -remote "send $id set ratios 1:2" + elif [ $w -le 160 ]; then + lf -remote "send $id set ratios 1:2:3" else - mv $f $1 + lf -remote "send $id set ratios 1:2:3:5" fi }} diff --git a/docstring.go b/docstring.go index dd767a9..fe849ab 100644 --- a/docstring.go +++ b/docstring.go @@ -57,23 +57,23 @@ The following commands are provided by lf without default keybindings: The following command line commands are provided by lf with default keybindings: - cmd-escape (default '') - cmd-comp (default '') - cmd-enter (default '' and '') - cmd-hist-next (default '') - cmd-hist-prev (default '') - cmd-delete (default '' and '') - cmd-delete-back (default '' and '') - cmd-left (default '' and '') - cmd-right (default '' and '') - cmd-beg (default '' and '') - cmd-end (default '' and '') - cmd-delete-beg (default '') - cmd-delete-end (default '') - cmd-delete-word (default '') - cmd-put (default '') - cmd-transpose (default '') - cmd-interrupt (default '') + cmd-escape (default '') + cmd-comp (default '') + cmd-enter (default '' and '') + cmd-hist-next (default '') + cmd-hist-prev (default '') + cmd-delete (default '' and '') + cmd-delete-back (default '' and '') + cmd-left (default '' and '') + cmd-right (default '' and '') + cmd-beg (default '' and '') + cmd-end (default '' and '') + cmd-delete-beg (default '') + cmd-delete-end (default '') + cmd-delete-word (default '') + cmd-put (default '') + cmd-transpose (default '') + cmd-interrupt (default '') The following options can be used to customize the behavior of lf: @@ -153,9 +153,9 @@ The following command prefixes are used by lf: : read (default) builtin/custom command $ shell shell command - % shell-pipe shell command displaying the output + % shell-pipe shell command running with the ui ! shell-wait shell command waiting for key press - & shell-async asynchronous shell command + & shell-async shell command running asynchronously / search search file in current directory ? search-back search file in the reverse order @@ -228,7 +228,7 @@ proper prefix. }} -Mappings +Push Mappings The usual way to map a key sequence is to assign it to a named or unnamed 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: These types of bindings create a deadlock when executed. +Shell Commands ($) -Commands - -For demonstration let us write a shell command to move selected file(s) to -trash. - -A first attempt to write such a command may look like this: +Regular shell commands are the most basic command type that is useful for +many purposes. For example, we can write a shell command to move selected +file(s) to trash. A first attempt to write such a command may look like +this: cmd trash ${{ mkdir -p ~/.trash @@ -301,6 +300,50 @@ or '$rm $fs' would simply work). This option is not set by default as it can behave unexpectedly for new users. However, use of this option is highly recommended and it is assumed in the rest of the documentation. +Piping Shell Commands (%) + +Regular shell commands have some limitations in some cases. When an output +or error message is given and the command exits afterwards, the ui is +immediately resumed and there is no way to see the message without dropping +to shell again. Also, even when there is no output or error, the ui still +needs to be paused while the command is running. This can cause flickering +on the screen for short commands and similar distractions for longer +commands. + +Instead of pausing the ui, piping shell commands connects stdin, stdout, and +stderr of the command to the statline in the bottom of the ui. This can be +useful for programs following the unix philosophy to give no output in the +success case, and brief error messages or prompts in other cases. + +For example, following rename command prompts for overwrite in the statline +if there is an existing file with the given name: + + cmd rename %mv -i $f $1 + +You can also output error messages in the command and it will show up in the +statline. For example, an alternative rename command may look like this: + + cmd rename %[ -e $1 ] && printf "file exists" || mv $f $1 + +One thing to be careful is that although input is still line buffered, +output and error are byte buffered and verbose commands will be very slow to +display. + +Waiting Shell Commands (!) + +Waiting shell commands are similar to regular shell commands except that +they wait for a key press when the command is finished. These can be useful +to see the output of a program before the ui is resumed. Waiting shell +commands are more appropriate than piping shell commands when the command is +verbose and the output is best displayed as multiline. + +Asynchronous Shell Commands (&) + +Asynchronous shell commands are used to start a command in the background +and then resume operation without waiting for the command to finish. Stdin, +stdout, and stderr of the command is neither connected to the terminal nor +to the ui. + Remote Commands @@ -339,15 +382,17 @@ calling the following in a shell command: lf -remote "send $id echo hello world" Since lf does not have control flow syntax, remote commands are used for -such needs. A common use is to display an error message back in the client. -You can implement a safe rename command which does not overwrite an existing -file or directory as such: +such needs. For example, you can configure the number of columns in the ui +with respect to the terminal width as follows: - cmd rename ${{ - if [ -e $1 ]; then - lf -remote "send $id echo file exists" + cmd recol ${{ + w=$(tput cols) + if [ $w -le 80 ]; then + lf -remote "send $id set ratios 1:2" + elif [ $w -le 160 ]; then + lf -remote "send $id set ratios 1:2:3" else - mv $f $1 + lf -remote "send $id set ratios 1:2:3:5" fi }} diff --git a/etc/lfrc.example b/etc/lfrc.example index b1b5eee..943c4ce 100644 --- a/etc/lfrc.example +++ b/etc/lfrc.example @@ -37,24 +37,15 @@ cmd open-file ${{ }} # rename current file without overwrite -cmd rename ${{ - if [ -e $1 ]; then - lf -remote "send $id echo file exists" - else - mv $f $1 - fi -}} +cmd rename %[ -e $1 ] && printf "file exists" || mv $f $1 map r push :rename -# show disk usage -cmd usage $du -h . | less - # make sure trash folder exists -$mkdir -p ~/.trash +%mkdir -p ~/.trash # move current file or selected files to trash folder # (also see 'man mv' for backup/overwrite options) -cmd trash $mv $fx ~/.trash +cmd trash %mv $fx ~/.trash # remove current file or selected files (prompting) cmd remove ${{ @@ -66,7 +57,7 @@ cmd remove ${{ # extract the current file with the right command # (xkcd link: https://xkcd.com/1168/) -cmd extract ${{ +cmd extract %{{ case $f in *.tar.bz|*.tar.bz2|*.tbz|*.tbz2) tar xjvf $f;; *.tar.gz|*.tgz) tar xzvf $f;; @@ -77,12 +68,10 @@ cmd extract ${{ esac }} -# compress marked files with tar and gunzip -# This command takes the output name without '.tar.gz' suffix as an argument -# (e.g. 'compress foo' creates 'foo.tar.gz'). -cmd compress ${{ +# compress current file or selected files with tar and gunzip +cmd compress %{{ mkdir $1 - cp $fs $1 - tar czvf $1.tar.gz $1 + cp -r $fx $1 + tar czf $1.tar.gz $1 rm -rf $1 }}