Update README

This commit is contained in:
Shav Kinderlehrer 2023-05-01 18:39:27 -04:00
parent e4f517c020
commit 36c5d3f68a
2 changed files with 65 additions and 52 deletions

View File

@ -3,38 +3,44 @@
[![Build](https://github.com/secondary-smiles/lat/actions/workflows/c-cpp.yml/badge.svg)](https://github.com/secondary-smiles/lat/actions/workflows/c-cpp.yml) [![Build](https://github.com/secondary-smiles/lat/actions/workflows/c-cpp.yml/badge.svg)](https://github.com/secondary-smiles/lat/actions/workflows/c-cpp.yml)
![lat demo](social/render/lat_demo.gif)
## About ## About
`lat` is a solution to a problem that doesn't exist. It's the awkward middle child in-between `cat` and `bat`. It was created because the author didn't want to have to configure `bat` just to get decent file printing, but wanted a little more control than `cat` offered. `lat` is a solution to a problem that doesn't exist. It's the awkward middle child in-between `cat` and `bat`. It was created because the author didn't want to have to configure `bat` just to get decent file printing, but wanted a little more control than `cat` offered.
`lat` does not expect to be used. `lat` expects to be forgotten and shunted into a corner because it does not belong in the slightest. `lat` does not expect to be used. `lat` expects to be forgotten and shunted into a corner because it does not belong in the slightest.
`lat` is fast. Here are the hyperfine results comparing `cat`, `lat`, and `bat` on a ~24MB text file: `lat` is fast. Here are the hyperfine results comparing `cat`, `lat`, and `bat` on a `lat`'s `main.c` source file:
```test ```text
hyperfine "cat log.log" "lat log.log" "bat log.log" -N --warmup 200 hyperfine "./build/lat src/main.c" "cat src/main.c" "bat src/main.c" -N --warmup 200
Benchmark 1: cat log.log Benchmark 1: ./build/lat src/main.c
Time (mean ± σ): 3.6 ms ± 0.3 ms [User: 0.4 ms, System: 2.3 ms] Time (mean ± σ): 0.2 ms ± 0.0 ms [User: 0.1 ms, System: 0.0 ms]
Range (min … max): 3.1 ms … 5.0 ms 851 runs Range (min … max): 0.1 ms … 0.7 ms 19651 runs
Benchmark 2: lat log.log
Time (mean ± σ): 6.2 ms ± 0.7 ms [User: 0.4 ms, System: 4.2 ms]
Range (min … max): 5.5 ms … 14.5 ms 496 runs
Warning: Statistical outliers were detected. Consider re-running this benchmark on a quiet system without any interferences from other programs. It might help to use the '--warmup' or '--prepare' options. Warning: Statistical outliers were detected. Consider re-running this benchmark on a quiet system without any interferences from other programs. It might help to use the '--warmup' or '--prepare' options.
Benchmark 3: bat log.log Benchmark 2: cat src/main.c
Time (mean ± σ): 103.9 ms ± 0.5 ms [User: 37.5 ms, System: 65.6 ms] Time (mean ± σ): 0.2 ms ± 0.0 ms [User: 0.2 ms, System: 0.0 ms]
Range (min … max): 103.2 ms … 104.8 ms 28 runs Range (min … max): 0.2 ms … 0.4 ms 13717 runs
Warning: Statistical outliers were detected. Consider re-running this benchmark on a quiet system without any interferences from other programs. It might help to use the '--warmup' or '--prepare' options.
Benchmark 3: bat src/main.c
Time (mean ± σ): 1.4 ms ± 0.7 ms [User: 1.1 ms, System: 0.3 ms]
Range (min … max): 1.1 ms … 6.5 ms 1057 runs
Warning: The first benchmarking run for this command was significantly slower than the rest (2.8 ms). This could be caused by (filesystem) caches that were not filled until after the first run. You are already using the '--warmup' option which helps to fill these caches before the actual benchmark. You can either try to increase the warmup count further or re-run this benchmark on a quiet system in case it was a random outlier. Alternatively, consider using the '--prepare' option to clear the caches before each timing run.
Summary Summary
'cat log.log' ran './build/lat src/main.c' ran
1.74 ± 0.26 times faster than 'lat log.log' 1.29 ± 0.28 times faster than 'cat src/main.c'
29.10 ± 2.85 times faster than 'bat log.log' 9.14 ± 4.56 times faster than 'bat src/main.c'
``` ```
> tested on a 2020 M1 MacBook Pro 16GB ~~as you can see, the extra features do take their toll on performance, but overall, `lat` is generally nearly on-par with `cat`, and *far* faster than `bat`.~~
as you can see, the extra features do take their toll on performance, but overall, `lat` is generally nearly on-par with `cat`, and *far* faster than `bat`. **As of v0.12.2 `lat` is the new fastest of the three!** (on my machine)
## Install ## Install
`lat` is not yet at a stable version (`v1.0.0`), so it is not on any package managers. `lat` is not yet at a stable version (`v1.0.0`), so it is not on any package managers.
@ -79,43 +85,27 @@ int main(void) {
#### `-c` color #### `-c` color
Completely disables or enables all colored output from `lat`. Completely disables or enables all colored output from `lat`.
##### Example
![Color in lat](social/render/color.gif)
> `lat` also respects [NO_COLOR](https://no-color.org/), but `-c` overrides it
#### `-l` line numbers #### `-l` line numbers
Print numbers for each line of the file. Print numbers for each line of the file.
##### Example
![Line numbers in lat](social/render/line_numbers.gif)
#### `-t` file title #### `-t` file title
Shows or hides formatted file data headers. Shows or hides formatted file data headers.
##### Example
![Headers in lat](social/render/headers.gif)
#### `-b` binary mode #### `-b` binary mode
By default, `lat` will attempt to detect if the file is printable or not. If the file isn't (e.g. you ran `lat file.pdf`) then lat will enter *`binary mode`*. In *`binary mode`*, `lat` will skip a lot of processing in favor of speed. By default, `lat` will attempt to detect if the file is printable or not. If the file isn't (e.g. you ran `lat file.pdf`) then lat will enter *`binary mode`*. In *`binary mode`*, `lat` will skip a lot of processing in favor of speed.
You can force *`binary mode`* to be `on` or `off` with the flags `-b` and `-bb` respectively. You can force *`binary mode`* to be `on` or `off` with the flags `-b` and `-bb` respectively.
##### Example
![Binary Mode in lat](social/render/binary.gif)
#### `-r` raw output #### `-r` raw output
`lat` is smart enough to print all non-file characters to a separate filestream. That way, the output of `lat` can be used to con**cat**enate files, the way it was originally meant to be (with `>` or `|`). `lat` is smart enough to print all non-file characters to a separate filestream. That way, the output of `lat` can be used to con**cat**enate files, the way it was originally meant to be (with `>` or `|`).
However, sometimes you want those extra symbols. However, sometimes you want those extra symbols.
`-r` prints everything out to the primary filestream (usually `stdout`) `-r` prints everything out to the primary filestream (usually `stdout`)
##### Example
![Literal output in lat](social/render/raw.gif)
#### `-p` pager #### `-p` pager
`lat` comes with out-of-the-box support for paging in `less`. If you don't want your file messing up your terminal, just `-p` it. `lat` comes with out-of-the-box support for paging in `less`. If you don't want your file messing up your terminal, just `-p` it.
### `-n` name ### `-n` name
`lat` allows you to customize the name of the file shown. This can be useful in demonstrations or when `lat` is embedded in another program. `lat` allows you to customize the name of the file shown. This can be useful in demonstrations or when `lat` is embedded in another program.
#### Example
![Custom filename in lat](social/render/name.gif)
##### Example
![Paging in lat](social/render/pager.gif)
#### If there is a feature you'd like to see, feel free to make an issue (1x points). If you're feeling especially savvy, make a PR with the feature (10x points). #### If there is a feature you'd like to see, feel free to make an issue (1x points). If you're feeling especially savvy, make a PR with the feature (10x points).
@ -126,21 +116,20 @@ However, sometimes you want those extra symbols.
```text ```text
lat | lazy cat - a cat clone with some quality-of-life embellishments lat | lazy cat - a cat clone with some quality-of-life embellishments
usage: lat [-cltbrpnVh] [file...] usage: lat [-cltbrpneVh] [file...]
options: options:
-c toggle color -c toggle color
-l toggle line numbers -l toggle line numbers
-t toggle file info headers -t toggle file info headers
-b toggle binary mode, -b forces binary and -bb forces NOT binary -b set binary mode, -b forces binary and -bb forces NOT binary
-r print everything to stdout (or equivalent) -r print everything (headers, line numbers, etc.) to stdout (or equivalent)
-p print file with the pager (uses less) -p print file with the pager (uses less)
-n set the name of the file in the title -n <name> manually set the name of the file shown in the title
-e <program> link extension to lat
-V show program version -V show program version
-h display this help text -h display this help text
environment: environment:
NO_COLOR, see https://no-color.org/ NO_COLOR, see https://no-color.org/
``` ```

24
social/lat_demo.tape Normal file
View File

@ -0,0 +1,24 @@
Require lat
Output social/render/name.gif
Set Theme "Gruvbox Dark"
Set WindowBar Rings
Set BorderRadius 10
Set Margin 10
Set FontSize 32
Set Width 2400
Set Height 1200
Set TypingSpeed 0.2
Type "lat Makefile"
Sleep 2s
Enter
Sleep 4s
Type "lat -h"
Sleep 2s
Enter
Sleep 4s