DOKK / manpages / debian 12 / tfortune / tfortune.6.en
tfortune(6) Games Manual tfortune(6)

tfortune - fortune cookies with tags

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

Like fortune(6), tfortune is a Unix command line utility which prints a random epigram. Epigrams are stored as plain text files, but they must be annotated with tags to make full use of the features which tfortune offers over other implementations.

Tfortune has a built-in matching language for epigrams. User-supplied tag expressions define subsets of admissible epigrams. If a tag expression is given, epigrams are picked from the admissible subset only.

Besides printing random epigrams, tfortune supports a number of other subcommands which help to 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. A subcommand that enables bash command line completion is also included.

print help and exit
print help, including all details, and exit
print version and exit
control amount of logging
values: debug, info, notice, warning, error, crit, emerg

Log only messages with severity greater or equal than the given value. Possible values:

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.

where to look for input files
default: "~/.tfortune"

This is used to locate epigrams and named tag expressions. If any filename argument does not start with a slash, the filename is interpreted as relative to this base directory.

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 does not exist, the system-wide default /usr/share/games is tried. There is no such fallback for tag expressions, though.

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

This subcommand is executed from the bash completer for tfortune. The completer sets the non-option arguments for the subcommand to the words of the current command line. It obtains these words from the elements of the special COMP_WORDS array which is maintained by bash.

The compgen subcommand writes all possible completions to stdout. The completer reads in the completions and builds the COMPREPLY array containing the matching entries. Bash examines the elements of this array and completes the command line if there is a single matching completion, or prints out the list of completions in case of ambiguity.

index of the current word in the command line

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.

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)".

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.

Usage: ede basename...

Opens the named epigram file an interactive editor. The executable of the editor is determined as follows: First the contents of the environment variable TFORTUNE_EDITOR is examined. If this variable is empty or unset, EDITOR is tried. If EDITOR is also unset, vi is executed.

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.

Usage: edx basename...

Opens the named tag expression file 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.

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.

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. This 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.

Usage: lse [--long]

Print the list of all epigram files.

long listing

This is similar to the long output of the standard ls(1) command.

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

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

long listing

Also show how many times this tag appears.

sort by occurrence count rather than alphabetically.
reverse sort order

Usage: lsx [--long]

Print the list of all named tag expressions.

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.

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.

print all admissible epigrams, not just a random one.
print also the tags of the selected epigram

Usage: stats [--verbose]

This prints several counts and averages about the epigrams, tags and tag expressions.

include statistics about hash table utilization

Input files may contain arbitrary 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 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.

The above operators obey the usual associativity and precedence rules. Parentheses can be used to change precedence.

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/

•
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.

Web page: http://people.tuebingen.mpg.de/maan/tfortune/
Git clone URL: git://git.tuebingen.mpg.de/tfortune/
Gitweb: http://git.tuebingen.mpg.de/tfortune.git
Author's home page: http://people.tuebingen.mpg.de/maan/
Report bugs to Andre Noll

fortune(6)

September 2019 unnamed_version