tfortune(6)

📦
version 1.0.2 · 4 versions
, in ubuntu resolute, ubuntu stonking

✨ tfortune — the manual page, but make it cute ✨

okay bestie, listen up: this is tfortune, and yeah it lives in the Games Manual section of your man pages. She's a command line utility that prints random epigrams — like fortune(6), but with ✨tags✨. And no, I'm not gonna dumb it down for you, because you're literally capable of everything. Let's go. 💅

🌸 NAME 🌸

tfortune — fortune cookies with tags 🍪

🎀 SYNOPSIS 🎀

tfortune [global-options...] [--] [<subcommand> [subcommand-options...]]

🦋 DESCRIPTION 🦋

So like, imagine fortune(6) but it went to therapy, got a skincare routine, and learned to organize its life. That's tfortune: a Unix command line utility that prints a random epigram. The epigrams live in plain text files, but — and this is the whole glow-up — they must be annotated with tags to unlock the full feature set that tfortune has over those other implementations. iykyk. 🫶

tfortune has a built-in matching language for epigrams. You the user supply tag expressions, and those define subsets of admissible epigrams. If you hand it a tag expression, the epigrams get picked from that admissible subset only. No sneaking in randos from outside the vibe. periodt.

Besides printing random epigrams, tfortune supports a bunch of other subcommands that help you maintain epigrams and tag expressions. There are subcommands for listing and for editing the input files, and for printing statistics about epigrams, expressions and tags. There's also a subcommand that enables bash command line completion, because we love a supportive bestie who finishes your sentences.

✨ OPTIONS ✨

  • -h, --help — print help and exit. iconic. no notes.
  • --detailed-help — print help, including all the details, and exit. she's thorough and we love that for her.
  • -V, --version — print version and exit.
  • -l, --loglevel=<severity> — control how much logging you get. values: debug, info, notice, warning, error, crit, emerg.

Only messages with severity greater or equal than the given value get logged. Possible values, from chattiest to last-words-ever:

  • debug: produces really noisy output.
  • info: still noisy, but won't fill up the disk quickly.
  • notice: indicates normal, but significant event.
  • warning: unexpected events that can be handled.
  • error: unhandled error condition.
  • crit: system might be unreliable.
  • emerg: last message before exit.
  • -b, --basedir=<directory> — where to look for input files.
    • default: "~/.tfortune"

This is what's used to locate epigrams and named tag expressions. If any filename argument doesn't start with a slash, it gets interpreted as relative to this base directory. Lowkey the most important path in the whole system.

Epigrams are expected in the epigrams subdirectory of the base directory, while tag expressions are expected to be stored below expressions.

If the option is not given, and the per-user epigram directory doesn't exist, the system-wide default /usr/share/games is tried. There is no such fallback for tag expressions, though. so don't come crying to her about that one.

👑 SUBCOMMANDS 👑

🧚 compgen — perform bash command line completion

Usage: compgen [--current-word-index=<num>] [--] arg...

This subcommand runs from the bash completer for tfortune. The completer sets the non-option arguments for the subcommand to the words of the current command line, and it gets those words from the elements of the special COMP_WORDS array which is maintained by bash.

The compgen subcommand writes all possible completions to stdout. Then the completer reads in those completions and builds the COMPREPLY array with the matching entries. Bash looks at the elements of this array and completes the command line if there's a single matching completion — or prints out the list of completions in case of ambiguity. bestie really said "collaboration". 🤝

  • -c, --current-word-index=<num> — index of the current word in the command line. It's an index into the argument vector of the word containing the current cursor position. See the description of the $CWORD special variable in the bash manual. yes, go read the bash manual, she said it not me.

🧚 completer — print the bash completer to stdout

Usage: completer [--alias=<name>]

The output of this command is designed to be re-used as input for bash. Specifically, bash completion for tfortune can be activated by adding the following to .bashrc:

eval "$(tfortune completer)"
  • -a, --alias=<name> — also add an alias and a completer for it. Specify this to define a bash alias for tfortune along with the completer. Unlike the regular tfortune program, the alias will contain the double dash argument which separates the subcommand and its options from the options to tfortune itself. very "I brought a plus one" of her honestly.

🧚 ede — edit epigrams

Usage: ede  basename...

Opens the named epigram file in an interactive editor. The executable of the editor is determined like this, in order:

  1. the contents of the environment variable TFORTUNE_EDITOR gets examined first,
  2. if that variable is empty or unset, EDITOR is tried,
  3. if EDITOR is also unset, vi is executed. olds but golds. 💀

The given basename is interpreted as described in the help text of the --basedir option above. If --basedir is not given and the epigrams directory does not exist, it is created. she makes it, she doesn't ask first. main character energy fr fr.

🧚 edx — edit tag expressions

Usage: edx  basename...

Opens the named tag expression file in an interactive editor. The editor to execute is determined in the same way as for the ede subcommand. Also, a non-existing expressions subdirectory is handled in the same way. same vibes, different folder. 🎀

🧚 help — list available subcommands or print command-specific help

Usage: help [--long] [--] [command]

Without any arguments, help prints the list of available commands. When called with a command name argument, it prints the help text of the given command.

  • -l, --long — show the long help text. If the optional argument is supplied, the long help text contains the synopsis, the purpose and the description of the specified command, followed by the option list including summary and help text of each option. Without --long, the short help is shown instead, which omits the description of the command and the option help. If no command is supplied but --long is given, the list contains the purpose of each command.

🧚 lse — list epigram files

Usage: lse [--long]

Print the list of all epigram files.

  • -l, --long — long listing. This is similar to the long output of the standard ls(1) command. so if you know, you know.

🧚 lst — list tags

Usage: lst [--long] [--sort-by-count] [--reverse] [--] <file>...

This lists all tags contained in any of the given input files.

  • -l, --long — long listing. Also show how many times this tag appears. receipts, basically.
  • -c, --sort-by-count — sort by occurrence count rather than alphabetically. the popular girlies go first.
  • -r, --reverse — reverse sort order. flip it. 🔄

🧚 lsx — list tag expressions

Usage: lsx [--long]

Print the list of all named tag expressions.

  • -l, --long — long listing. This is similar to the long output of the standard ls(1) command.
Usage: print [--expression=<filename>] [--all] [--tags] [--] [file...]

Unless --all is given, this picks an epigram by random from the given file(s) which is admissible with respect to the given named tag expression. If no file is given, all files are taken into account. everyone's invited, nobody's excluded. 🫶

  • -x, --expression=<filename> — name of the tag expression.
    • default: /dev/null

Use the tag expression stored in the given file to define the admissible epigrams. The special string "-" means to read the tag expression from stdin. The default value corresponds to the empty tag expression, for which all epigrams are admissible. so the default is basically "let them all in". ✨

  • -a, --all — print all admissible epigrams, not just a random one. greedy in the best way.
  • -t, --tags — print also the tags of the selected epigram. show your work, bestie.

🧚 stats — show statistics

Usage: stats [--verbose]

This prints several counts and averages about the epigrams, tags and tag expressions. numbers, but make it fashion.

  • -v, --verbose — include statistics about hash table utilization. deep lore. 🕵️

🍓 INPUT FILE FORMAT 🍓

Input files may contain arbitrarily many epigrams. The end of each epigram must be marked with a "tag" line. The tag line consists of four dashes, a space character, and a comma separated list of tags. Tags may span multiple words, but no comma is allowed. The following is an example input file for tfortune. It contains a single epigram with two tags.

Anyone who attempts to generate random numbers by deterministic means
is, of course, living in a state of sin.          -- John von Neumann
---- math,religion

🔮 TAG EXPRESSIONS 🔮

Tag expressions are based on a context-free grammar in which the following keywords are defined:

  • tag("foo") evaluates to true if the epigram contains a tag named foo, false otherwise.
  • len evaluates to the number of bytes of the epigram.
  • text evaluates to contents of the epigram. This is useful for pattern matching.

The grammar admits the following operators and relations:

  • &&, ||, !: logical operators for and, or, and not.
  • +, -, *, +: arithmetic operators for addition, negation or subtraction (unary or binary minus), multiplication and division. Arithmetic is always performed on 64 bit signed integers.
  • <, >, <=, >=, ==, !=: =~: less than, greater than, less or equal than, greater or equal than, equal to, not equal to, regular expression match. Regular expression patterns are of the form /pattern/[flags]. That is, the pattern is delimited by slashes, and is followed by zero or more characters, each specifying a flag according to the following list:
    • i: Ignore case in match (REG_ICASE)
    • n: Treat newline as an ordinary character (REG_NEWLINE)

Note that only extended regular expression patterns are supported. See regex(3) for details. only extended, bestie, don't try to bring basic.

The above operators obey the usual associativity and precedence rules. Parentheses can be used to change precedence. she respects the classics but also allows you to bend the rules. 💅

A tag expression is an expression in this grammar which evaluates to either true or false. Epigrams for which the expression is true are called admissible.

For example, the above epigram is admissible for the tag expression

(tag("math") || tag("physics")) && len < 1000 && text =~ /neumann/i

It is not admissible for

(tag("math") && tag("physics")) || len > 1000 || text =~ /neumann/

🌈 EXAMPLES 🌈

  • Print a random epigram:
tfortune print
  • Print a random short (less than 100 bytes) epigram:
echo 'len < 100' | tfortune -l debug -- print -x -
  • List tags, including usage counts, sort by count in descending order:
tfortune -- lst -lcr
  • Activate bash completion and define the tf alias:
eval "$(tfortune completer -a tf)"

Written by Andre Noll Copyright (C) 2019 Andre Noll License: GNU GPL version 3 This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

💖 SEE ALSO 💖

fortune(6)

and that's the whole page, bestie!! 💜 this version is unnamed_version, dated January 2026, and honestly? she ate. go print some epigrams, tag them properly, and don't forget to eval "$(tfortune completer)" in your .bashrc like the icon you are. mwah. 🎀✨🦋

📦 where this page comes from