You can learn more about this git repository by cloning it like this:
git clone https://supertxt.net/git/cats--id=v0.2.4 --date=2024-05-12T19:46:20-04:00
--id=v0.2.3 --date=2023-09-09T16:31:59-04:00
--id=v0.2.2 --date=2023-08-29T21:17:06-04:00
--id=v0.2.1 --date=2023-08-28T20:19:51-04:00
--id=v0.2.0 --date=2023-08-27T13:07:10-04:00
--id=v0.1.0 --date=2023-02-26T14:01:33-05:00
--id=v0.0.1 --date=2022-11-28T16:39:06-05:00
--hash=c03664a --date=2024-05-12T19:46:20-04:00 "add chdir reflection mode to cats"
--hash=0af79e1 --date=2023-10-23T14:25:59-04:00 "fix formatting"
--hash=e59954e --date=2023-10-23T14:25:03-04:00 "add tags and branches to the git summary"
--hash=e844bed --date=2023-09-09T16:31:59-04:00 "Report correctly missing files where no pipeline is possible"
--hash=b502633 --date=2023-08-29T21:17:06-04:00 "Fix trivial pipeline case where data is just copied from file to stdout"
--hash=d7b7b7c --date=2023-08-28T20:19:51-04:00 "Remove cat dependency for cats so that it can be invoked as cat"
--hash=d2255c1 --date=2023-08-28T15:19:52-04:00 "Provide status information for git repos"
--hash=1a39fc1 --date=2023-08-27T13:07:10-04:00 "Major rework of cats"
--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 hyphenated cats command to a subcommand to support site-specific commands that support multiple verbs"--id=main --hash=c03664a --date=2024-05-12T19:46:20-04:00
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 nobody@supertxt.net: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](https://github.com/TheZoraiz/ascii-image-converter/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.
⠀⠀⠀⠀⠀⠀⠀⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ ⠀⠀⠀⠀⠀⠀⠀⢹⣿⣦⡀⠀⠀⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ ⠀⠀⠀⠀⠀⠀⠀⠀⠻⣿⣧⠀⡰⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ ⠀⠀⠀⠀⠀⠀⠀⢀⣀⡈⠛⠀⡇⠀⠀⣀⣀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ ⠀⠀⠀⠀⢀⣴⣿⣿⣿⣿⣿⣶⣷⣶⣿⣿⣿⣿⣷⡄⠀⠀⠀⠀⠀⠀⠀⠀ ⠀⠀⠀⢀⡾⠿⠿⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡄⠀⠀⠀⠀⠀⠀⠀ ⠀⠀⠀⠈⣴⣶⣷⣦⡙⣿⠿⠿⠿⣿⠟⣡⣤⣤⣌⠻⡧⠀⠀⠀⠀⠀⠀⠀ ⠀⢀⣤⣾⣿⣿⣿⣿⡇⢠⣶⣶⣶⡌⢸⣿⣿⣿⣿⣧⣴⣶⣤⠀⠀⠀⠀⠀ ⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠃⠀⠀⠀⠀ ⠀⠀⠙⠛⠻⠿⠿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⠿⠛⠋⠁⠀⠀⠀⠀⠀ ⠀⠀⠀⢸⣿⣶⣶⣦⣤⣤⣤⣬⣭⣍⠻⣿⣿⣿⢁⣾⣿⣄⣀⣀⣀⠀⠀⠀ ⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⠘⣿⡇⢸⣿⣿⡿⠿⠿⠿⣿⡆⠀ ⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⣤⣴⣿⣿⣿⠀⠀⠀⠀⣿⡇⠀ ⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⣿⡇⠀ ⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⣿⡇⠀ ⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⣿⡇⠀ ⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⣿⡇⠀ ⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣤⣤⣤⣤⣿⡇⠀ ⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠟⠛⠛⠛⠋⠀⠀ ⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⠀⠀⠀ ⠀⠀⠀⠸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠿⠀⠀⠀⠀⠀⠀⠀ ⠀⠀⠀⠀⠀⠈⠉⠉⠛⠛⠛⠛⠛⠛⠛⠛⠉⠉⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀
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 "<from>to<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](http://supertxt.net/browsing.s.txt).
Installation on macOS and Linux is available via [homebrew](https://brew.sh)
brew tap supertxt/tap ssh://nobody@supertxt.net/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
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.
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.
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](http://supertxt.net/browsing.s.txt) section.
See the [license](LICENSE.txt) for more information.