Fortune - read and write fortune (strfile) databases

   # 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);

The CWfortune 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 CWfortune 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 CWFortune module; the older style of munging the header and data into one large compiled file is not (currently) supported.

Using the CWFortune module makes it trivial to write a simplified version of the CWfortune 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 CWfortune'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 CWfortune, use it but if you just want a simple Perl interface to its data files, the CWFortune module is for you.

Currently, the CWFortune module does not support writing fortune databases. If it did, writing a simplified CWstrfile (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 CW".dat" appended. You can supply an alternate header filename to the constructor, CWnew(), if you wish.

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 CW".dat" appended. The data file is opened via CWopen_file(), which CWdies 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 CWread_header() or CWwrite_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.

read_header ()

Reads the header file associated with this fortune database. The name of the header file is determined by the constructor CWnew: 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 CWcompute_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 CWFortune object: version number number of strings (fortunes) in the file length of longest string in the file length of shortest string in the file bit field for flags (see strfile(1) man page) character that delimits fortunes CWnumstr is available via the CWnum_fortunes() method; if you're interested in the others, you'll have to go grubbing through the CWFortune object, e.g.:

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

CWread_header() CWdies if there are any problems reading the header file, e.g. if it seems to be corrupt or truncated. CWread_header() returns the current CWFortune 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 CWdelim 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 CWread_header().

write_header ([DELIM])

is not yet implemented.

get_fortune (NUM)

Reads string number NUM from the open fortune file. NUM is zero-based, ie. it must be between 0 and CWnum_fortunes()-1 (inclusive). CWcroaks 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 CWread_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 CWread_fortune().

write_fortune (FORTUNE)

is not yet implemented.

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.

You can download the CWFortune 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 CWfortune as part of its standard installation (most commercial Unices seem to be so afflicted), the Linux world has a solution: the CWfortune-mod distribution. The latest version as of this writing is CWfortune-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 CWfortune implementation on which the CWFortune module is based.