pistol

README

Pistol

Introduction

Pistol is a file previewer for command line file managers such as Ranger and Lf intended to replace the file previewer scope.sh commonly used with them.

scope.sh is a Bash script that uses case switches and external programs to decide how to preview every file it encounters. It knows how to handle every file according to it's MIME type and/or file extension using case switches and external programs. This design makes it hard to configure / maintain and it makes it slow for startup and heavy when running.

Pistol is a Go program (with (almost) 0 dependencies) and it's MIME type detection is internal. Moreover, it features native preview support for almost any archive file and for text files along with syntax highlighting while scope.sh relies on external programs to do these basic tasks.

The following table lists Pistol's native previewing support:

File/MIME Type	Notes on implementation
text/*	Prints text files with syntax highlighting thanks to chroma.
Archives	Prints the contents of archive files using archiver.

In case Pistol encounters a MIME type it doesn't know how to handle natively and you haven't configured a program to handle it, it'll print a general description of the file type it encountered. For example, the preview for an executable might be:

ELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, BuildID[sha1]=a34861a1ae5358dc1079bc239df9dfe4830a8403, for GNU/Linux 3.2.0, not stripped

This feature is available out of the box just like the previews for the common mime types mentioned above.

A Note on MIME type Detection

Some pure Go libraries provide MIME type detection. Here are the top search results I got using a common web search engine:

• https://github.com/gabriel-vasile/mimetype
• https://github.com/h2non/filetype
• https://github.com/rakyll/magicmime

Pistol uses the last one which leverages the well known C library libmagic(3). I made this choice after experimenting with the other candidates and due to their lack of an extensive database such as libmagic(3) has, I chose magicmime.

Note that this choice also features compatibility with the standard command file which is available by default on most GNU/Linux distributions ¹.

A Note on Archive Previews

Pistol previews all archive / compression formats supported by the Go library archiver. Some formats do nothing but compression, meaning they operate on 1 file alone and some files are a combination of archive, compressed in a certain algorithm.

For example, a .gz file is a single file compressed with gzip. A .tar file is an uncompressed archive (collection) of files. A .tar.gz is a .tar file compressed using gzip.

When pistol encounters a single file compressed using a known compression algorithm, it doesn't know how to handle it's content, it displays the type of the archive. If a known compression algorithm has compressed a .tar file, Pistol lists the files themselves.

brotli compressed archives, (.tar.br) and brotli compressed files (.br) are not detected by libmagic so Pistol doesn't know how to handle them. ²

Install

If someone has packaged Pistol for your distribution, you might find a package for of it linked in the WiKi. If not, you can install it from source according to the following instructions:

Prerequisites

Since Pistol depends on magicmime, you'll need a libmagic package installed. Please refer to this section in magicmime's README for the appropriate commands for every OS.

Assuming you've installed libmagic properly and you have setup a Go environment, Use the following command to install Pistol to $GOPATH/bin/pistol:

env GO111MODULE=on go get -u github.com/doronbehar/pistol/cmd/pistol

³

Usage

$ pistol --help
Usage: pistol OPTIONS <file>

OPTIONS

-c, --config <config>  configuration file to use (defaults to ~/.config/pistol/pistol.conf)
-h, --help             print help and exit
-v, --verbosity        increase verbosity

ARGUMENTS

file                   the file to preview

Integrations

Ranger / Lf

You can use Pistol as a file previewer in Ranger and Lf. For Ranger, set your preview_script in your rc.conf as follows:

set preview_script ~/.go/bin/pistol

The same goes for Lf, but in lfrc:

set previewer ~/.go/bin/pistol

fzf

If you use fzf to search for files, you can tell it to use pistol as the previewer. For example, the following command edits with your $EDITOR selected python file(s) using pistol as a previewer:

$EDITOR "$(find -name '*.py' | fzf --preview='pistol {}')"

Configuration

Although Pistol previews files of certain MIME types by default, it doesn't force you to use these internal previewers for these MIME types. You can change this behaviour by writing a configuration file in $XDG_CONFIG_HOME/pistol/pistol.conf (or ~/.config/pistol/pistol.conf) with the syntax as explained below.

Syntax

You can configure preview commands according to file path or mime type regex. The 1st word may is always interpreted first as a mime type regex such as: text/*.

If a line is not matched but the 1st word is exactly fpath, then the 2nd argument is interpreted as a file path regex, such as: /var/src/.*/README.md.

On every line, whether you used fpath or not, the next arguments are the command's arguments, where %s is substituted by pistol to the file at question. You'll see more examples in the following sections.

Both regular expressions (for file paths and for mime types) are interpreted by the built-in library's regexp.match. Please refer to this link for the full reference regarding syntax.

Matching Mime Types

You can inspect the MIME type of any file on a GNU/Linux OS and on Mac OS with the command file --mime-type <file>.

For example, say you wish to replace Pistol's internal text previewer with that of bat's, you'd put the following in your pistol.conf:

text/* bat --paging=never --color=always %s

Naturally, your configuration file overrides the internal previewers.

Here's another example which features w3m as an HTML previewer:

text/html w3m -T text/html -dump %s

And here's an example that leverages ls for printing directories' contents:

inode/directory ls -l --color %s

Matching File Path

For example, say you wish to preview all files that reside in a certain ./bin directory with bat's syntax highlighting for bash. You could use:

fpath /var/src/my-bash-project/bin/[^/]+$ bat --map-syntax :bash --paging=never --color=always %s

A Note on RegEx matching

When Pistol parses your configuration file, as soon as it finds a match be it a file path match or a mime type match, it stops parsing it and it invokes the command written on the rest of the line. Therefor, if you wish to use the examples from above which use w3m and bat, you'll need to put w3m's line before bat's line. Since otherwise, text/* will be matched first and text/html won't be checked at all.

Similarly, you'd probably want to put fpath lines at the top.

Of course that this is a mere example, the same may apply to any regular expressions you'd choose to match against.

For a list of the internal regular expressions tested against when Pistol reverts to it's native previewers, read the file internal_writers/map.go.

More examples can be found in this WiKi page.

Quoting and Shell Piping

Pistol is pretty dumb when it parses your config, it splits all line by spaces, meaning that e.g:

application/json jq '.' %s

This will result in an error by jq:

jq: error: syntax error, unexpected INVALID_CHARACTER, expecting $end (Unix shell quoting issues?) at <top-level>, line 1:
'.'
jq: 1 compile error

Indicating that jq got a literal '.'. When you run in your shell jq '.' file.json you don't get an error because your shell is stripping the quotes around .. However, Pistol is not smarter then your shell because if you'd try for example:

application/json jq '.[] | .' %s

That would be equivalent to running in the typical shell:

jq "\'.[]" "|" ".'" file.json

That's because Pistol doesn't consider your quotes as interesting instructions, it just splits words by spaces. Hence, to overcome this disability, you can use:

application/json sh: jq '.' %s

Thanks to the sh: keyword at the beginning of the command's definition, the rest of the line goes straight as a single argument to sh -c.

You can worry not about quoting / escaping the rest of the line - it's not like when you run e.g sh -c 'command' in your shell where you need to make sure single quotes are escaped or not used at all inside command.

More over, with sh: you can use shell pipes:

fpath .*.md$ sh: bat --paging=never --color=always %s | head -8

Environmental Variables

Pistol's internal previewer for text files includes syntax highlighting thanks to the Go library chroma. You can customize Pistol's syntax highlighting formatting and style through environmental variables.

Chroma Formatters

The term formatter refers to the way the given file is presented in the terminal. These include:

• terminal: The default formatter that uses terminal control codes to change colors between every key word. This formatter has 8 colors and it's the default.
• terminal256: Same as terminal but with 256 colors available.
• terminal16m: Same as terminal but with 24 Bits colors i.e True-Color.

Other formatters include json, and html but I'd be surprised if you'll find them useful for Pistol's purpose.

To tell Pistol to use a specific formatter, set PISTOL_CHROMA_FORMATTER in your environment, e.g:

export PISTOL_CHROMA_FORMATTER=terminal16m

Recent versions of Lf support 256 colors in it's preview window. AFAIK⁴, Ranger supports 8 colors and Lf's color256 isn't enabled by default.

Therefor, I decided that it'll be best to keep this variable unset in your general environment. If you do set color256 in your lfrc, you may feel free to set PISTOL_CHROMA_FORMATTER in your environment.

Chroma Styles

The term style refers to the set of colors used to print a given file. the chroma project documents all styles here and here.

The default style used by Pistol is pygments. To tell Pistol to use a specific style set PISTOL_CHROMA_STYLE in your environment, e.g:

export PISTOL_CHROMA_STYLE=monokai

Footnotes

1 Considering Pistol's indirect dependence on libmagic(3), I will never take the trouble to personally try and make it work on Windows natively. If you'll succeed in the heroic task of compiling libmagic for Windows and teach magicmime to use it, please let me know. ↩

2 file bug report; brotli bug report. ↩

3 env GO111MODULE=on is needed due to a recent bug / issue with Go, see #6 for more details. ↩

4 I don't use Ranger anymore, ever since I moved to Lf. If you have evidence it does support 256 colors, let me know and I'll change the default. ↩

Documentation

Index

• type Previewer
  • func NewPreviewer(filePath, configPath string) (Previewer, error)
  • func (p *Previewer) Write(w io.Writer) error

Types

type Previewer

type Previewer struct {
	// contains filtered or unexported fields
}

func NewPreviewer

func NewPreviewer(filePath, configPath string) (Previewer, error)

func (*Previewer) Write

func (p *Previewer) Write(w io.Writer) error