| 1 |
.TH LESSPIPE.SH "1" "August 2024" "lesspipe.sh" "User Commands" |
| 2 |
.SH NAME |
| 3 |
lesspipe.sh \- a filter for less |
| 4 |
.SH SYNOPSIS |
| 5 |
.B lesspipe.sh |
| 6 |
[\fIFILE[s]\fR]... |
| 7 |
.SH DESCRIPTION |
| 8 |
.PP |
| 9 |
The aim of \fBlesspipe.sh\fP is to enhance the output of \fBless\fP. The choice |
| 10 |
of the rules to be applied to modify the output are based on the file contents. |
| 11 |
The file extension is respected only as a last resort. |
| 12 |
Usually \fBlesspipe.sh\fP is called as an input filter to \fBless\fP. |
| 13 |
.PP |
| 14 |
With the help of that filter \fBless\fP |
| 15 |
will display the uncompressed contents of compressed (\fIgzip, bzip2, |
| 16 |
compress, zstd, lz4, lzip, xz, lzma or brotli\fP) files. For files |
| 17 |
containing archives and directories, a table of contents will be displayed |
| 18 |
(\fItar, ar, zip, 7-zip, rar, jar, cpio, rpm, deb ms-cabinet, iso, appimage |
| 19 |
and snap formats\fP). |
| 20 |
Many other files will be reformatted for display. It includes |
| 21 |
\fIpdf, dvi, markdown, Office (MS and Openoffice)\fP suites formats, |
| 22 |
\fINetCDF, matlab, device tree blob, html, xml\fP and \fImedia (image, audio and |
| 23 |
video)\fP formats. This does require helper programs being installed. |
| 24 |
.PP |
| 25 |
The filter can also be applied recursively to extract and display |
| 26 |
files in archives on the fly. This works to a depth of 6 where applying a |
| 27 |
decompression algorithm counts as a separate level. |
| 28 |
.PP |
| 29 |
If the file utility reports text with an encoding different from the one |
| 30 |
used in the terminal then the text will be transformed using \fIiconv\fP into |
| 31 |
the default encoding. This does assume the \fIfile\fP command gets the file |
| 32 |
encoding right, which can be wrong in some situations. An appended colon |
| 33 |
to the file name does suppress the conversion. |
| 34 |
.PP |
| 35 |
When using the programs \fBgit\fP, \fBvim\fP or \fBmutt\fP they can be |
| 36 |
enabled to read non-text files by using lesspipe.sh. That is described in |
| 37 |
the Wiki at \fIhttps://github.com/wofr06/lesspipe/wiki\fP. |
| 38 |
.SH FILTER ACTIVATION |
| 39 |
The filter is called from \fBless\fP provided the environment variable |
| 40 |
\fBLESSOPEN\fP is set properly. For ksh like shells (\fIbash, zsh\fP) |
| 41 |
the command |
| 42 |
.RS |
| 43 |
.I LESSOPEN="|lesspipe.sh %s"; export LESSOPEN |
| 44 |
.RE |
| 45 |
does activate the filter for less. Use the fully qualified path, if |
| 46 |
\fBlesspipe.sh\fP is not in the search path. The command to set \fBLESSOPEN\fP |
| 47 |
can also be displayed by calling \fBlesspipe.sh\fP without arguments. |
| 48 |
This can even be used to set \fBLESSOPEN\fP directly: |
| 49 |
.RS |
| 50 |
.I eval `lesspipe.sh` |
| 51 |
(bash) or |
| 52 |
.RE |
| 53 |
.RS |
| 54 |
.I lesspipe.sh|source /dev/stdin |
| 55 |
(zsh) |
| 56 |
.RE |
| 57 |
The above commands work only in the described manner if the file name is |
| 58 |
\fBlesspipe.sh\fP. |
| 59 |
If it is installed under a different name then calling it without an argument |
| 60 |
will work as a filter with \fBLESSQUIET\fP set and expecting input from STDIN. |
| 61 |
.PP |
| 62 |
Having set the environment variable as described above, \fBless\fP |
| 63 |
:will then display textual information for a wide range of file formats. |
| 64 |
.PP |
| 65 |
The filter is normally not called if input is piped to less as in |
| 66 |
.RS |
| 67 |
.I cat somefile | less |
| 68 |
.RE |
| 69 |
As described in the man page of less, the filtering in a pipe can however |
| 70 |
be forced by starting \fBLESSOPEN\fP with the characters \fI|-\fP. |
| 71 |
.PP |
| 72 |
\fBLESSOPEN\fP starting with the two characters \fI||\fP to handle empty files |
| 73 |
and command errors is implemented only partly, usually on failures of |
| 74 |
commands within \fBlesspipe.sh\fP the error messages get displayed. |
| 75 |
.PP |
| 76 |
To suppress informal messages in the first line of the filter output the |
| 77 |
ENV variable \fBLESSQUIET\fP can be set to a nonempty value. |
| 78 |
.PP |
| 79 |
To disengage the filter temporarily a colon can be appended to the file name. |
| 80 |
If the file name contains a colon, then an equal sign should be used instead. |
| 81 |
.SH HTML, XML and Perl POD Files |
| 82 |
Files in the \fIhtml\fP, \fIxml\fP and \fIperl pod\fP format are always |
| 83 |
rendered. Sometimes however the original contents of the file should be viewed |
| 84 |
instead. As mentioned before that can be achieved by appending a colon to the |
| 85 |
file name. If the correct file type (\fIhtml\fP, \fIxml\fP, \fIpod\fP) follows, |
| 86 |
the output can get colorized (see also the section below). |
| 87 |
.PP |
| 88 |
.RS |
| 89 |
Example: \fIless index.html:html\fP |
| 90 |
.RE |
| 91 |
.PP |
| 92 |
If the binary \fIxmq\fP is installed, then \fIxml\fP is rendered differently, |
| 93 |
so that the xml structure is better recognized. A similar display for |
| 94 |
\fIhtml\fP contents using \fIxmq\fP is achieved by appending a colon to the |
| 95 |
file name. To get the original html file contents, two colons are |
| 96 |
required in this case. |
| 97 |
.SH OUTPUT COLORIZATION |
| 98 |
The filter is able to do syntax highlighting for a wide variety of |
| 99 |
file types. If installed, \fInvimpager\fP is used for |
| 100 |
colorizing the output. If not, \fIbat\fP/\fIbatcat\fP, \fIpygmentize\fP, |
| 101 |
\fIsource-highlight\fP, \fIvimcolor\fP and \fIcode2color\fP are tried in turn. |
| 102 |
For bat/batcat the theme is set to \fIansi\fP and the style is set to |
| 103 |
\fIplain\fP which comes closer to the unfiltered output of \fBless\fP. |
| 104 |
These settings can be changed in \fI~/.config/bat/config\fP or by the |
| 105 |
environment variables \fBBAT_STYLE\fP and \fBBAT_THEME\fP. |
| 106 |
.PP |
| 107 |
Among the colorizers |
| 108 |
a preferred one can be forced for colorizing by setting the ENV variable |
| 109 |
\fBLESSCOLORIZER\fP to the name of the colorizer. For \fIpygmentize\fP and |
| 110 |
\fIbat\fP/\fIbatcat\fP restricted option settings are allowed as follows: |
| 111 |
.RS |
| 112 |
.I LESSCOLORIZER='pygmentize -O style=foo' (-P allowed as well) |
| 113 |
.RE |
| 114 |
.RS |
| 115 |
.I LESSCOLORIZER='bat --style=foo --theme=bar' (default is theme ansi, style plain) |
| 116 |
.RE |
| 117 |
Syntax highlighting is activated, if the environment variable \fBLESS\fP |
| 118 |
exists and contains the option \fI-R\fP |
| 119 |
or less is called with this option. This guarantees that escape sequences |
| 120 |
get converted into colors and do not garble the display. Using the option |
| 121 |
\fI-r\fP is not recommended, as the screen layout may be wrong, if long |
| 122 |
lines are in the output. |
| 123 |
.PP |
| 124 |
Syntax highlighting can be switched off by |
| 125 |
appending a colon after the file name, if the output was colorful. If the |
| 126 |
wrong language was chosen for syntax highlighting, then another one can be |
| 127 |
forced by appending a colon and a suffix to the file name. |
| 128 |
.PP |
| 129 |
In a pipe that method cannot be used. As a way out a last argument can be added |
| 130 |
that gets inspected by \fBlesspipe.sh\fP. |
| 131 |
A single colon (disengage filter) or :extension (force language) is possible as e.g with |
| 132 |
.RS |
| 133 |
.I command that generates c code | less - :c |
| 134 |
.RE |
| 135 |
.PP |
| 136 |
When the conditions for syntax highlighting are met directory listings and |
| 137 |
listings of tar file contents get colorized as well. |
| 138 |
.PP |
| 139 |
As \fBless\fP is used as a default browser in other programs (e.g. \fIman\fP, |
| 140 |
\fIgit\fP, and \fIperldoc\fP)) \fBlesspipe.sh\fP may be engaged and alter |
| 141 |
the output of those programs. |
| 142 |
.SH WATCHING GROWING FILES |
| 143 |
As soon as \fBlesspipe.sh\fP |
| 144 |
calls a program to convert the input the ability to watch growing files |
| 145 |
(using the F command within less) is lost. This is usually wanted for log |
| 146 |
files like syslog. To temporarily disengage \fBlesspipe.sh\fP |
| 147 |
a colon as the last argument for \fBless\fP needs to be added as e.g in |
| 148 |
.RS |
| 149 |
.I less /var/log/syslog : |
| 150 |
.RE |
| 151 |
or \fBless\fP |
| 152 |
can be called with the +F argument, which is equivalent to F within the pager: |
| 153 |
.RS |
| 154 |
.I less +F /var/log/syslog |
| 155 |
.RE |
| 156 |
Appending a colon to the file name does not work, as then the filter has to be engaged to at least remove that colon and use cat for the original file. |
| 157 |
On the other hand non growing log files can be colorized using \fBccze\fP. |
| 158 |
Its recognition as a log file is difficult if not ending in \fI.log\fP |
| 159 |
but can be forced appending \fB:.log\fP to the file name as e.g in |
| 160 |
.RS |
| 161 |
.I less /var/log/syslog:.log |
| 162 |
.RE |
| 163 |
.SH ADVANCED USAGE |
| 164 |
This version of \fBlesspipe.sh\fP |
| 165 |
allows you to view individual files contained in a file archive, which itself |
| 166 |
may even be contained in another archive. |
| 167 |
.PP |
| 168 |
The notation for viewing files in multifile archives is |
| 169 |
.RS |
| 170 |
.B less |
| 171 |
\fIarchive_file\fP:\fIcontained_file\fP |
| 172 |
.RE |
| 173 |
or even |
| 174 |
.RS |
| 175 |
.B less |
| 176 |
\fIsuper_archive\fP:\fIarchive_file\fP:\fIcontained_file\fP |
| 177 |
.RE |
| 178 |
To display the last file in the chain raw format, a colon (\fI:\fP) has to be |
| 179 |
appended to the file name. If it does contain a colon, then the alternate |
| 180 |
separator character equal sign (\fI=\fP) has to be used. |
| 181 |
.PP |
| 182 |
Again, this method of extracting and displaying files does not work if |
| 183 |
\fBless\fP is called in an output pipe and \fBLESSOPEN\fP starts with the |
| 184 |
\fB|-\fP characters. As already for syntax highlighting the solution is to use |
| 185 |
a second argument that starts with a colon. Then the above command would |
| 186 |
be written as |
| 187 |
.RS |
| 188 |
\fBcat \fIsuper_archive\fP | \fBless\fP - :\fIarchive\fP:\fIcontained_file\fP |
| 189 |
.RE |
| 190 |
.PP |
| 191 |
.SH COMPLETING MECHANISM FOR ARCHIVE CONTENTS |
| 192 |
With the provided \fIlesscomplete\fP (for \fBzsh\fP and \fBbash\fP), |
| 193 |
\fI_less\fP (for \fBzsh\fP) and \fIless_completion\fP (for \fBbash\fP) files |
| 194 |
a tab completion for files in archives can be accomplished. |
| 195 |
Entering a colon (:) or an equal sign (=) after an archive |
| 196 |
file name and then pressing the tab key triggers the completion mechanism. |
| 197 |
This also works in chained archives. The files \fIlesscomplete\fP and |
| 198 |
\fIless_completion\fP have to be in one of the directories listed in |
| 199 |
\fB$PATH\fP and the function \fI_less\fP for \fBzsh\fP in a directory |
| 200 |
listed by \fI$fpath\fP. The less_completion script has to |
| 201 |
be sourced within a bash initialization script, e.g. in \fI~/.bashrc\fP. New |
| 202 |
directories such as \fI~/scripts\fP and \fI~/.fpath\fP can be added using the |
| 203 |
commands |
| 204 |
.RS |
| 205 |
\fBPATH\fP=\fI~/scripts:$PATH\fP and |
| 206 |
\fBfpath\fP=\fI(~/.fpath $fpath)\fP |
| 207 |
.RE |
| 208 |
.SH USER DEFINED FILTERING |
| 209 |
The lesspipe.sh filtering can be replaced or enhanced by a user defined |
| 210 |
program. Such a program has to be called either \fB.lessfilter\fP (and be |
| 211 |
placed in the users home directory), or \fBlessfilter\fP (and be accessible |
| 212 |
from a directory mentioned in \fB$PATH\fP). |
| 213 |
It has to be executable and has to end with an exit code 0, if the filtering |
| 214 |
was done within that script. Otherwise, a nonzero exit code means the filtering |
| 215 |
is left to lesspipe.sh. |
| 216 |
.PP |
| 217 |
This mechanism can be used to add filtering for new formats or e.g. inhibit |
| 218 |
filtering for certain file types. |
| 219 |
.SH AUTHOR |
| 220 |
Wolfgang Friebel |
| 221 |
.SH "REPORTING BUGS" |
| 222 |
Report bugs to <wp.friebel AT gmail DOT com>. |
| 223 |
.SH COPYRIGHT |
| 224 |
Copyright \(co 2005-2024 Wolfgang Friebel |
| 225 |
.br |
| 226 |
This is free software; see the source for copying conditions. There is NO |
| 227 |
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
| 228 |
.SH "SEE ALSO" |
| 229 |
less(1) |
| 230 |
.PP |
| 231 |
A description of \fBlesspipe.sh\fP |
| 232 |
is also contained in the file README contained in the source code package |