Provided by: tfortune_1.0.2-1_amd64 
NAME
tfortune - fortune cookies with tags
SYNOPSIS
tfortune [global-options...] [--] [<subcommand> [subcommand-options...]]
DESCRIPTION
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.
OPTIONS
-h, --help
print help and exit
--detailed-help
print help, including all details, and exit
-V, --version
print version and exit
-l, --loglevel=<severity>
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.
-b, --basedir=<directory>
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.
SUBCOMMANDS
compgen - perform bash command line completion
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.
-c, --current-word-index=<num>
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.
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.
ede - edit epigrams
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.
edx - edit tag expressions
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.
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. 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.
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.
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.
-c, --sort-by-count
sort by occurrence count rather than alphabetically.
-r, --reverse
reverse sort order
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.
print - print epigram(s)
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.
-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.
-a, --all
print all admissible epigrams, not just a random one.
-t, --tags
print also the tags of the selected epigram
stats - show statistics
Usage: stats [--verbose]
This prints several counts and averages about the epigrams, tags and tag expressions.
-v, --verbose
include statistics about hash table utilization
INPUT FILE FORMAT
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
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/
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)"
COPYRIGHT
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: ⟨https://people.tuebingen.mpg.de/maan/tfortune/⟩
Git clone URL: ⟨https://git.tuebingen.mpg.de/tfortune/⟩
Gitweb: ⟨https://git.tuebingen.mpg.de/tfortune.git⟩
Author's home page: ⟨https://people.tuebingen.mpg.de/maan/⟩
Report bugs to Andre Noll ⟨maan@tuebingen.mpg.de⟩
SEE ALSO
fortune(6)