FreeBSD Manual Pages
LESSPIPE.SH(1) User Commands LESSPIPE.SH(1) NAME lesspipe.sh - a filter for less SYNOPSIS lesspipe.sh [FILE[s]]... DESCRIPTION Usually lesspipe.sh is called as an input filter to less. With the help of that filter less will display the uncompressed contents of compressed (gzip, bzip2, compress, zstd, lz4, lzip, xz, lzma or brotli) files. For files containing archives and directories, a table of contents will be dis- played (tar, ar, zip, i7-zip, rar, jar, rpm, deb ms-cabinet and iso for- mats). Many other files will be reformatted for display. It includes pdf, dvi, markdown, Office (MS and Openoffice) suites formats, NetCDF, matlab, html and media (image, audio and video) formats. This does require helper programs being installed. The filter does not only display the above mentioned file formats, but can also be applied recursively and be used to extract and display files in archives on the fly. This works to a depth of 6 where applying a decompres- sion algorithm counts as a separate level. If the file utility reports text with an encoding different from the one used in the terminal then the text will be transformed using iconv into the default encoding. This does assume the file command gets the file encoding right, which can be wrong in some situations. An appended colon to the file name does suppress the conversion. When using the programs git, vim or mutt they can be enabled to read non- text files by using lesspipe.sh. That is described in the Wiki at https://github.com/wofr06/lesspipe/wiki. FILTER ACTIVATION The filter is called from less provided the environment variable LESSOPEN is set properly. For ksh like shells (bash, zsh) the command LESSOPEN="|lesspipe.sh %s"; export LESSOPEN does activate the filter for less. Use the fully qualified path, if lesspipe.sh is not in the search path. The command to set LESSOPEN can also be displayed by calling lesspipe.sh without arguments. This can even be used to set LESSOPEN directly: eval `lesspipe.sh` (bash) or lesspipe.sh|source /dev/stdin (zsh) Having set the environment variable as described above, less will then dis- play textual information for a wide range of file formats. The filter is normally not called if input is piped to less as in cat somefile | less As described in the man page of less, the filtering in a pipe can however be forced by starting LESSOPEN with the characters |-. LESSOPEN starting with the two characters || is implemented in this lesspipe.sh only partly, usually on failures of commands within lesspipe.sh the error messages get displayed. The now obsolete variable LESS_ADVANCED_PREPROCESSOR was used to decide, whether html, xml and perl pod should be shown as pure text or not. This has been changed, these formats are now always interpreted, unless a colon is appended to the file name. If the correct file type (html, xml, pod) follows, the output can get colorized (see below). Example: less index.html:html To suppress informal messages in the first line of the filter output the ENV variable LESSQUIET can be set to a nonempty value. To disengage the filter temporarily a colon can be appended to the file name. If the file name contains a colon, then an equal sign should be used instead. OUTPUT COLORIZATION The filter is able to do syntax highlighting for a wide variety of language and other format files. If installed, bat/batcat is used for coloring the output. If not, pygmentize, source-highlight, code2color is tried in turn and finally vimcolor which is the slowest. As the default bat/batcat theme is for dark background, another theme might have been set in ~/.con- fig/bat/config. Among these colorizers a preferred one can be forced for coloring by set- ting the ENV variable LESSCOLORIZER to the name of the colorizer. As pyg- mentize has no other way to change the output style, there a style option can be specified as follows: LESSCOLORIZER='pygmentize -O style=somename' Syntax highlighting is activated, if the environment variable LESS exists and contains the option -R or less is called with this option. This guaran- tees, that escape sequences get converted into colors and do not garble the display. Using the option -r is not recommended, as the screen layout may be wrong, if long lines are in the output. Syntax highlighting can be switched off by appending a colon after the file name, if the output was colorful. If the wrong language was chosen for syn- tax highlighting, then another one can be forced by appending a colon and a suffix to the file name. In a pipe that method cannot be used. As a way out a last argument can be added that gets inspected by lesspipe.sh. A single colon (disengage fil- ter) or :extension (force language) is possible as e.g with command that generates c code | less - :c When the conditions for syntax highlighting are met directory listings and listings of tar file contents get colorized as well. As less is used as a default browser in many other programs (e.g. man, git, perldoc) the choice of the colorizer also affects the output of those programs. As by default bat/batcat does always color the output, pygmentize has a dark theme, which is not well suited for light background and code2color covers only a few cases, vimcolor is the most safe choice, how- ever also the slowest program. WATCHING GROWING FILES As soon as lesspipe.sh calls a program to convert the input the ability to watch growing files (using the F command within less) is lost. This is usu- ally wanted for log files like syslog. To temporarily disengage lesspipe.sh a colon (:) as the last argument for less needs to be added as e.g in less /var/log/syslog : or less can be called with the +F argument, which is equivalent to F within the pager: less +F /var/log/syslog 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. On the other hand non growing log files can be colorized using ccze. Its recognition as a log file is difficult if not ending in .log but can be forced appending :.log to the file name as e.g in less /var/log/syslog:.log ADVANCED USAGE This version of lesspipe.sh allows you to view individual files contained in a file archive, which itself may even be contained in another archive. The notation for viewing files in multifile archives is less archive_file:contained_file or even less super_archive:archive_file:contained_file To display the last file in the chain raw format, a colon (:) has to be ap- pended to the file name. If it does contain a colon, then the alternate separator character equal sign (=) has to be used. Again, this method of extracting and displaying files does not work if less is called in an output pipe and LESSOPEN starts with the |- characters. As already for syntax highlighting the solution is to use a second argument that starts with a colon. Then the above command would be written as cat super_archive | less - :archive:contained_file COMPLETING MECHANISM FOR ARCHIVE CONTENTS With the provided lesscomplete (for zsh and bash), _less (for zsh) and less_completion (for bash) files a tab completion for files in archives can be accomplished. Entering after an archive file name a colon (:) or an equal sign (=) and then pressing the tab key triggers the completion mecha- nism. This also works in chained archives. The files lesscomplete and less_completion have to be in one of the directories listed in $PATH and the function _less for zsh in a directory listed by $fpath. The less_com- pletion script has to be sourced within a bash initialization script, e.g. in ~/.bashrc. New directories such as ~/scripts and ~/.fpath can be added using the commands PATH=~/scripts:$PATH and fpath=(~/.fpath $fpath) USER DEFINED FILTERING The lesspipe.sh filtering can be replaced or enhanced by a user defined program. Such a program has to be called either .lessfilter (and be placed in the users home directory), or lessfilter (and be accessible from a di- rectory mentioned in $PATH). It has to be executable and has to end with an exit code 0, if the filtering was done within that script. Otherwise, a nonzero exit code means the filtering is left to lesspipe.sh. This mechanism can be used to add filtering for new formats or e.g. inhibit filtering for certain file types. AUTHOR Wolfgang Friebel REPORTING BUGS Report bugs to <wp.friebel AT gmail DOT com>. COPYRIGHT Copyright (C) 2005-2022 Wolfgang Friebel This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO less(1) A description of lesspipe.sh is also contained in the file README contained in the source code package lesspipe.sh Feb 2022 LESSPIPE.SH(1)
NAME | SYNOPSIS | DESCRIPTION | FILTER ACTIVATION | OUTPUT COLORIZATION | WATCHING GROWING FILES | ADVANCED USAGE | COMPLETING MECHANISM FOR ARCHIVE CONTENTS | USER DEFINED FILTERING | AUTHOR | REPORTING BUGS | COPYRIGHT | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=lesspipe&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>