supertxt.net/git/cats

Secure CAT (cats)

This is an enhanced version of the venerable cat command from Unix. Here is a quick tour of its features.

Read a file over SSH.

   cats [e-mail]:browsing.s.txt

Automatically page (more) a file.

    cats some_long_file.txt # We don't need to pipe this to more

Show an image as ASCII art in the terminal using ascii-image-converter:

    cats ~/Pictures/homebrew.png

It looks something like this depending on your terminal width and configuration. Select the area with your mouse to reveal any colors.

⠀⠀⠀⠀⠀⠀⠀⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⢹⣿⣦⡀⠀⠀⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠻⣿⣧⠀⡰⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⢀⣀⡈⠛⠀⡇⠀⠀⣀⣀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⢀⣴⣿⣿⣿⣿⣿⣶⣷⣶⣿⣿⣿⣿⣷⡄⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⢀⡾⠿⠿⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡄⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠈⣴⣶⣷⣦⡙⣿⠿⠿⠿⣿⠟⣡⣤⣤⣌⠻⡧⠀⠀⠀⠀⠀⠀⠀
⠀⢀⣤⣾⣿⣿⣿⣿⡇⢠⣶⣶⣶⡌⢸⣿⣿⣿⣿⣧⣴⣶⣤⠀⠀⠀⠀⠀
⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠃⠀⠀⠀⠀
⠀⠀⠙⠛⠻⠿⠿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⠿⠛⠋⠁⠀⠀⠀⠀⠀
⠀⠀⠀⢸⣿⣶⣶⣦⣤⣤⣤⣬⣭⣍⠻⣿⣿⣿⢁⣾⣿⣄⣀⣀⣀⠀⠀⠀
⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⠘⣿⡇⢸⣿⣿⡿⠿⠿⠿⣿⡆⠀
⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⣤⣴⣿⣿⣿⠀⠀⠀⠀⣿⡇⠀
⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⣿⡇⠀
⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⣿⡇⠀
⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⣿⡇⠀
⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⣿⡇⠀
⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣤⣤⣤⣤⣿⡇⠀
⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠟⠛⠛⠛⠋⠀⠀
⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠿⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠈⠉⠉⠛⠛⠛⠛⠛⠛⠛⠛⠉⠉⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀

Show an image using the kitty graphic protocol if the local terminal supports it. Install the 'kitty' tool and then display a jpeg image:

    cats ~/Pictures/my_picture.jpg

Summarize a git repo at a glance.

    cats ~/git/cats.s.txt # Add the supertxt file extension to a git directory name

You will see summaries like this including a recent log of activity and the README.md, if available.

    # cats

    ``` .sh
    git clone "/home/supertxt/git/cats"
    ```

    ## Log

    ``` .swv
    --hash=a07e72d --date=2023-03-29T07:29:06-04:00 "Update tostxt tool to add explicit data types"
    --hash=ebd998e --date=2023-02-26T14:01:33-05:00 "Change the site-specific handler delegation convention from a hyphenat
    --hash=673e176 --date=2023-02-22T13:50:00-05:00 "Cats redirects should handle targets with round brackets by wrapping t
    --hash=0dfcee2 --date=2023-02-20T20:04:55-05:00 "Add more detailed online help for cats"
    ```

    ## Secure CAT (cats)
    ...

Read EXIF metadata for a jpeg image as text.

    cats my_jpg_picture.s.txt # Add the supertxt file extension in place of .jpg to request a text representation

Plus, you can add your own file format conversions, or customize the built-in ones. Add a program/script to your PATH with the name "to" and cats will use it. You can add your own site-specific handlers for a internet site by adding a program with the host name of the website. It's highly customizable to suit your needs.

There are special reflective capabilities so that cats works with well with a SuperTXT browser.

Installation

Installation on macOS and Linux is available via homebrew

brew tap supertxt/tap ssh://[e-mail]/git/st-brew
brew install supertxt/tap/cats

Since cats is written in Go you can also install it with the go tool.

go install supertxt.net/git/cats/cmd/cats@latest

Site-specific Hooks

There is a pluggable mechanism for site-specific handling in cats so that you can plug in your own custom tool for reading a site in plain text. Cats uses a tool on the PATH named for the site (eg. somesite.net) to view any files on that site. If a tool is present then cats will delegate to it with the "cats" subcommand to view the file. Using this mechanism site-specific tools can be used for sites that don't support SSH.

Content Conversion Request

Cats can perform simple on-the-fly conversions of a file from one extension to another if such a conversion is possible in the environment.

   cats my_image.s.txt # This file doesn't exist, but there is a file called my_image.jpg

If a conversion can be found from ".jpg" file extension to ".s.txt" file extension then the result might look something like this:

   # my_image.jpg
   * dateCreated: 2014-06-02T11:44:00Z
   * geo: 43.6425662,-79.3892508

The conversion relies on the availability of a tool on the system path (PATH variable) that can convert ".jpg" to ".s.txt" called "jpgtostxt". Note that the tool (script or program) must accept the source path as the first argument and produce the converted output to stdout.

Reflection

The cats command supports two kinds of command-line reflection through the '--srefl' option so that external applications can query it for more information. It's often difficult for an external program to determine what sort of output to expect from a command-line, but commands can often determine this for themselves. Agent programs like the shell could do more with program output if they are aware of the type of data going to the output, such as syntax highlighting, or even rendering images on the screen. You can ask cats to output the file extension of a command without actually running it like this:

   cats --srefl=extension some/path/to/file.jpg

If cats can determine the file extension from the path provided then it prints it to stdout.

   .jpg

Another kind of reflection is available for redirection. An agent program (eg. a shell or browser) may not know how to rewrite the command line arguments for a program given relative path or other kind of link fragment shown in its output. A program like cats can reconstruct its own command-line options and arguments using the command that was run before, with the redirect option, and the link fragment from stdin like this:

   echo 'browsing.s.txt' | cats --srefl=redirect supertxt.net:00-intro.s.txt

Cats then outputs to stdout what the new command should be for this redirect.

   cats supertxt.net:browsing.s.txt

You can read more about reflection and the srefl option on the superxt.net website in the browsing section.

Legal

See the license for more information.