Provided by: tfortune_1.0.1-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: ⟨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 ⟨maan@tuebingen.mpg.de⟩
SEE ALSO
fortune(6)