A TLDR client in Zig.

This is taken from vent on gitlab but lacks maintenance and needs fixing for newest versions of Zig and Windows compilation.

I intend to use it as a playground as I work on teaching myself Zig programming.

Usage

To view the TLDR page for chmod:

tldr chmod

Works with multiple-word pages as well, for example:

tldr git rebase

Update your local cache (you'll need to do this before using it for the first time):

tldr --update

To specify language (in this case, español):

tldr --language es bash

You can specify the platform too, it defaults to the platform the source was built for.

tldr --platform osx caffeinate

You can list all pages, as well as supported languages and operating systems:

tldr --list
tldr --list-languages
tldr --list-platforms

Specifying your language/platform alongside list-pages works as expected.

tldr --language fr --platform linux --list-pages

You can also fetch a random page, just for fun. This respects your language and platform choice too.

tldr --random

For more, try:

tldr --help

Building

You'll need zig-0.9.1 and Git.

Clone this repo and then cd into the working directory

git submodule update --init

zig build -Drelease-fast

Performance

This is the fastest tldr client that I am aware of. If someone knows of a faster client, please open an issue with a link to the repository and I will update this section.

The original author benchmarked against a few other tldr programs using Hyperfine. These results were consistent on my machine, however they are probably inaccurate due to Outfieldr sitting on the lower bound of what Hyperfine is capable of measuring.

Here are the results:

Program	Build Flags	Mean Time (ms)	User (ms)	System (ms)
Outfieldr	`-Drelease-fast`	0.1 ± 0.0	0.4	0.3
Tealdeer	`--release`	3.2 ± 0.2	2.1	1.6
C Client	`-O3`	3.6 ± 0.5	2.4	1.8
Bash Client	N/A	15.0 ± 1.6	13.2	3.9
Go Client	Prebuilt from repo	92.6 ± 1.2	87.5	5.0
Node.js Client	N/A	471.0 ± 5.6	480.1	49.3

Here is the raw log from Hyperfine:

Benchmark #1: ./bin/bash_client ip
  Time (mean ± σ):      15.0 ms ±   1.6 ms    [User: 13.2 ms, System: 3.9 ms]
  Range (min … max):    13.4 ms …  19.5 ms    183 runs

Benchmark #2: ./bin/c_client ip
  Time (mean ± σ):       3.6 ms ±   0.5 ms    [User: 2.4 ms, System: 1.8 ms]
  Range (min … max):     3.2 ms …   6.0 ms    493 runs

Benchmark #3: ./bin/go_client ip
  Time (mean ± σ):      92.6 ms ±   1.2 ms    [User: 87.5 ms, System: 5.0 ms]
  Range (min … max):    91.8 ms …  96.9 ms    31 runs

Benchmark #4: ./bin/outfieldr ip
  Time (mean ± σ):       0.1 ms ±   0.0 ms    [User: 0.4 ms, System: 0.3 ms]
  Range (min … max):     0.0 ms …   0.6 ms    1094 runs

Benchmark #5: ./bin/tealdeer ip
  Time (mean ± σ):       3.2 ms ±   0.2 ms    [User: 2.1 ms, System: 1.6 ms]
  Range (min … max):     3.0 ms …   5.4 ms    522 runs

Benchmark #6: ./bin/node_modules/tldr/bin/tldr ip
  Time (mean ± σ):     471.0 ms ±   5.6 ms    [User: 480.1 ms, System: 49.3 ms]
  Range (min … max):   465.9 ms … 481.8 ms    10 runs

Summary
  './bin/outfieldr ip' ran
   34.06 ± 15.16 times faster than './bin/tealdeer ip'
   38.35 ± 17.62 times faster than './bin/c_client ip'
  160.36 ± 72.35 times faster than './bin/bash_client ip'
  987.72 ± 433.12 times faster than './bin/go_client ip'
 5021.80 ± 2201.98 times faster than './bin/node_modules/tldr/bin/tldr ip'

As you can see, Outfieldr is the clear winner here, being an order of magnitude faster than second place. It's worth noting that the Node.js Client is the slowest by far, taking almost half a second to show you a tldr page.

Before anyone asks, yes I did do a test run of every client viewing the ip page before benchmarking, and so no fetching/caching of the pages were performed during the benchmarks.

Features

Pretty-print tldr pages
Update the local cache by fetching/extracting a tarball from the tldr repo
Make language overridable
Make OS overridable
Improve help page
List all available languages
List all supported operating systems
List all available pages with small description
Handle terminals that don't like color

TODO

Successfully build against current/ development Zig builds
Linux
Windows
Conform to the TLDR Client Specification

Why the name?

The original author did a regex on a dictionary to find words that contained the letters 't', 'l', 'd', and 'r' in that order. This was the word I liked the most. Just be thankful it wasn't named kettledrum.

MANICX100 / outfieldr