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
$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 construct, 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(), whichdies 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 callread_header()orwrite_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.The header contains the following values, which are stored as attributes of the
Fortuneobject: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
numstris available via thenum_fortunes()method; if you're interested in the others, you'll have to go grubbing through theFortuneobject, e.g.:$fortune_file = new Fortune ('fortunes'); $fortune_file->read_header (); $delim = $fortune_file->{'delim'};read_header()dies if there are any problems reading the header file, e.g. if it seems to be corrupt or truncated.read_header()returns the currentFortuneobject, to allow for sneaky one-liners (see the examples above). - 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).croaks if you haven't opened the file (which is taken care of for you by the constructor) and read the header (which you must do explicitly), or if NUM is out of range. 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
AUTHOR AND COPYRIGHT
Written by Greg Ward <gward@ase.com>, 20 February 1999.
Copyright (c) 1999 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://www.aseonline.net/~gward/and it should show up on CPAN soon-ish (modulo a possible name change).
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.htmlThis is the fortune implementation on which the Fortune module is based.