Provided by: tfortune_1.0.0-2_amd64 bug

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)