Skip to content

MANICX100/outfieldr

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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

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.