NAME

       Fortune - read and write fortune (strfile) databases

SYNOPSIS

          # input
          $ffile = new Fortune ($base_filename);
          $ffile->read_header ();
          $num_fortunes = $ffile->num_fortunes ();
          $fortune = $ffile->read_fortune ($num);
          $fortune = $ffile->get_random_fortune ();

          # create header file from data file -- NOT IMPLEMENTED YET
          $ffile = new Fortune ($base_filename);
          $ffile->write_header ();

          # write to data file -- NOT IMPLEMENTED YET
          $ffile = new Fortune (">>$base_filename");
          $ffile->write_fortune ($fortune);

DESCRIPTION

       The "fortune" program is a small but important part of the Unix culture, and this module aims to provide
       support for its "fortune cookie" databases to Perl programmers.  For efficiency, all versions of
       "fortune" rely on a binary header consisting mainly of offsets into the fortune file proper.  Modern
       versions of fortune keep this header in a separate file, and this is the style adopted by the "Fortune"
       module; the older style of munging the header and data into one large "compiled" file is not (currently)
       supported.

       Using the "Fortune" module makes it trivial to write a simplified version of the "fortune" program:

          # trivial 'fortune' progam
          my $fortune_filename = $ARGV[0];
          my $fortune_file = new Fortune ($fortune_filename);
          $fortune_file->read_header ();
          my $fortune = $fortune_file->get_random_fortune ();
          print $fortune;

       This can be compressed considerably:

          print new Fortune ($ARGV[0])->read_header()->get_random_fortune();

       Of course, this doesn't provide all of "fortune"'s interesting features, such as parallel databases of
       offensive fortunes, selection of long or short fortunes, dealing with multiple fortune files, etc.  If
       you want "fortune", use it -- but if you just want a simple Perl interface to its data files, the
       "Fortune" module is for you.

       Currently, the "Fortune" module does not support writing fortune databases.  If it did, writing a
       simplified "strfile" (the program that processes a fortune database to create the header file) would also
       be trivial:

          # trivial (and hypothetical) 'strfile' program
          my $fortune_filename = @ARGV[0];
          my $fortune_file = new Fortune ($fortune_filename);
          $fortune_file->write_header ();

       Note that the header filename is assumed to be just the name of the main fortune database, with ".dat"
       appended.  You can supply an alternate header filename to the constructor, "new()", if you wish.

METHODS

   Initialization/cleanup
       new (FILE [, HEADER_FILE])
           Opens  a  fortune  cookie  database.   FILE is the name of the data file to open, and HEADER_FILE (if
           given) the name of the header file that contains  (or  will  contain)  meta-data  about  the  fortune
           database.  If HEADER_FILE is not given, it defaults to FILE with ".dat" appended.

           The  data  file  is  opened via "open_file()", which "die"s if the file cannot be opened.  The header
           file is not opened, whether you supply its filename or not -- after all,  it  might  not  exist  yet.
           Rather, you must explicitly call "read_header()" or "write_header()" as appropriate.

       open_file ()
           Opens the fortune file whose name was supplied to the constructor.  Dies on failure.

       close_file ()
           Closes the fortune file if it's open; does nothing otherwise.

   Header functions (read and write)
       read_header ()
           Reads  the  header  file  associated  with  this  fortune  database.   The name of the header file is
           determined by the constructor "new": either it is based on the name of the data file, or supplied  by
           the caller.

           If  the  header  file does not exist, this function calls "compute_header()" automatically, which has
           the same effect as reading the header from a file.

           The header contains the following values, which are stored as attributes of the "Fortune" object:

           "version"
               version number

           "numstr"
               number of strings (fortunes) in the file

           "max_length"
               length of longest string in the file

           "min_length"
               length of shortest string in the file

           "flags"
               bit field for flags (see strfile(1) man page)

           "delim"
               character that delimits fortunes

           "numstr" is available via the "num_fortunes()" method; if you're interested  in  the  others,  you'll
           have to go grubbing through the "Fortune" object, e.g.:

              $fortune_file = new Fortune ('fortunes');
              $fortune_file->read_header ();
              $delim = $fortune_file->{'delim'};

           "read_header()"  "die"s  if  there  are  any problems reading the header file, e.g. if it seems to be
           corrupt or truncated.

           "read_header()" returns the current "Fortune"  object,  to  allow  for  sneaky  one-liners  (see  the
           examples above).

       compute_header ([DELIM])
           Reads  the  contents  of  the fortune file and computes the header information that would normally be
           found in a header (.dat) file.  This is useful if you maintain a file of fortunes by hand and do  not
           have the corresponding data file.

           An  optional  delimiter  argument  may be passed to this function; if present, that delimiter will be
           used to separate entries in the fortune file.  If not provided, the existing "delim" attribute of the
           Fortune object will be used.  If that is not defined, then a percent sign ("%") will be used.

       num_fortunes ()
           Returns the number of fortunes found by "read_header()".

       write_header ([DELIM])
           is not yet implemented.

   Fortune input
       get_fortune (NUM)
           Reads string number NUM from the open fortune file.  NUM is zero-based, ie. it must be between 0  and
           "num_fortunes()-1"  (inclusive).   "croak"s if you haven't opened the file and read the header, or if
           NUM is out of range.  (Opening the file is pretty hard to screw up, since it's taken care of for  you
           by  the  constructor,  but you have to read the header explicitly with "read_header()".)  Returns the
           text of the fortune as a (possibly) multiline string.

       get_random_fortune ()
           Picks a random fortune for you and reads it with "read_fortune()".

   Fortune output
       write_fortune (FORTUNE)
           is not yet implemented.

AUTHOR AND COPYRIGHT

       Written by Greg Ward <gward@python.net>, 20 February 1999.

       Copyright (c) 1999-2000  Gregory  P.  Ward.  All  rights  reserved.   This  is  free  software;  you  can
       redistribute it and/or modify it under the same terms as Perl itself.

AVAILABILITY

       You can download the "Fortune" module from my web page:

          http://starship.python.net/~gward/perl/

       and it can also be found on CPAN.

       If you are using an operating system lacking a sufficient sense of humour to include "fortune" as part of
       its  standard  installation  (most  commercial  Unices  seem  to  be so afflicted), the Linux world has a
       solution: the "fortune-mod" distribution.  The latest version as of this writing  is  "fortune-mod-9708",
       and the README file says you can find it at

          http://www.progsoc.uts.edu.au/~dbugger/hacks/hacks.html

       This is the "fortune" implementation on which the "Fortune" module is based.

perl v5.36.0                                       2022-11-19                                       Fortune(3pm)