.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Fortune 3pm"
.TH Fortune 3pm "2016-11-25" "perl v5.24.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Fortune \- read and write fortune (strfile) databases
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 6
\&   # 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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \f(CW\*(C`fortune\*(C'\fR program is a small but important part of the Unix
culture, and this module aims to provide support for its \*(L"fortune
cookie\*(R" databases to Perl programmers.  For efficiency, all versions of
\&\f(CW\*(C`fortune\*(C'\fR 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 \f(CW\*(C`Fortune\*(C'\fR module;
the older style of munging the header and data into one large \*(L"compiled\*(R"
file is not (currently) supported.
.PP
Using the \f(CW\*(C`Fortune\*(C'\fR module makes it trivial to write a simplified
version of the \f(CW\*(C`fortune\*(C'\fR program:
.PP
.Vb 6
\&   # trivial \*(Aqfortune\*(Aq 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;
.Ve
.PP
This can be compressed considerably:
.PP
.Vb 1
\&   print new Fortune ($ARGV[0])\->read_header()\->get_random_fortune();
.Ve
.PP
Of course, this doesn't provide all of \f(CW\*(C`fortune\*(C'\fR'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 \f(CW\*(C`fortune\*(C'\fR, use it \*(-- but if you just want a simple Perl
interface to its data files, the \f(CW\*(C`Fortune\*(C'\fR module is for you.
.PP
Currently, the \f(CW\*(C`Fortune\*(C'\fR module does not support writing fortune
databases.  If it did, writing a simplified \f(CW\*(C`strfile\*(C'\fR (the program that
processes a fortune database to create the header file) would also be
trivial:
.PP
.Vb 4
\&   # trivial (and hypothetical) \*(Aqstrfile\*(Aq program
\&   my $fortune_filename = @ARGV[0];
\&   my $fortune_file = new Fortune ($fortune_filename);
\&   $fortune_file\->write_header ();
.Ve
.PP
Note that the header filename is assumed to be just the name of the main
fortune database, with \f(CW".dat"\fR appended.  You can supply an alternate
header filename to the constructor, \f(CW\*(C`new()\*(C'\fR, if you wish.
.SH "METHODS"
.IX Header "METHODS"
.SS "Initialization/cleanup"
.IX Subsection "Initialization/cleanup"
.IP "new (\s-1FILE\s0 [, \s-1HEADER_FILE\s0])" 4
.IX Item "new (FILE [, HEADER_FILE])"
Opens a fortune cookie database.  \s-1FILE\s0 is the name of the data file to
open, and \s-1HEADER_FILE \s0(if given) the name of the header file that
contains (or will contain) meta-data about the fortune database.  If
\&\s-1HEADER_FILE\s0 is not given, it defaults to \s-1FILE\s0 with \f(CW".dat"\fR appended.
.Sp
The data file is opened via \f(CW\*(C`open_file()\*(C'\fR, which \f(CW\*(C`die\*(C'\fRs if the file
cannot be opened.  The header file is \fInot\fR opened, whether you supply
its filename or not \*(-- after all, it might not exist yet.  Rather, you
must explicitly call \f(CW\*(C`read_header()\*(C'\fR or \f(CW\*(C`write_header()\*(C'\fR as
appropriate.
.IP "open_file ()" 4
.IX Item "open_file ()"
Opens the fortune file whose name was supplied to the constructor.  Dies
on failure.
.IP "close_file ()" 4
.IX Item "close_file ()"
Closes the fortune file if it's open; does nothing otherwise.
.SS "Header functions (read and write)"
.IX Subsection "Header functions (read and write)"
.IP "read_header ()" 4
.IX Item "read_header ()"
Reads the header file associated with this fortune database.  The name
of the header file is determined by the constructor \f(CW\*(C`new\*(C'\fR: either it is
based on the name of the data file, or supplied by the caller.
.Sp
If the header file does not exist, this function calls \f(CW\*(C`compute_header()\*(C'\fR
automatically, which has the same effect as reading the header from a file.
.Sp
The header contains the following values, which are stored as attributes
of the \f(CW\*(C`Fortune\*(C'\fR object:
.RS 4
.ie n .IP """version""" 4
.el .IP "\f(CWversion\fR" 4
.IX Item "version"
version number
.ie n .IP """numstr""" 4
.el .IP "\f(CWnumstr\fR" 4
.IX Item "numstr"
number of strings (fortunes) in the file
.ie n .IP """max_length""" 4
.el .IP "\f(CWmax_length\fR" 4
.IX Item "max_length"
length of longest string in the file
.ie n .IP """min_length""" 4
.el .IP "\f(CWmin_length\fR" 4
.IX Item "min_length"
length of shortest string in the file
.ie n .IP """flags""" 4
.el .IP "\f(CWflags\fR" 4
.IX Item "flags"
bit field for flags (see \fIstrfile\fR\|(1) man page)
.ie n .IP """delim""" 4
.el .IP "\f(CWdelim\fR" 4
.IX Item "delim"
character that delimits fortunes
.RE
.RS 4
.Sp
\&\f(CW\*(C`numstr\*(C'\fR is available via the \f(CW\*(C`num_fortunes()\*(C'\fR method; if you're
interested in the others, you'll have to go grubbing through the
\&\f(CW\*(C`Fortune\*(C'\fR object, e.g.:
.Sp
.Vb 3
\&   $fortune_file = new Fortune (\*(Aqfortunes\*(Aq);
\&   $fortune_file\->read_header ();
\&   $delim = $fortune_file\->{\*(Aqdelim\*(Aq};
.Ve
.Sp
\&\f(CW\*(C`read_header()\*(C'\fR \f(CW\*(C`die\*(C'\fRs if there are any problems reading the header file,
e.g. if it seems to be corrupt or truncated.
.Sp
\&\f(CW\*(C`read_header()\*(C'\fR returns the current \f(CW\*(C`Fortune\*(C'\fR object, to allow for
sneaky one-liners (see the examples above).
.RE
.IP "compute_header ([\s-1DELIM\s0])" 4
.IX Item "compute_header ([DELIM])"
Reads the contents of the fortune file and computes the header
information that would normally be found in a header (\fI.dat\fR) file.
This is useful if you maintain a file of fortunes by hand and do not
have the corresponding data file.
.Sp
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 \f(CW\*(C`delim\*(C'\fR attribute of the Fortune
object will be used.  If that is not defined, then a percent sign (\*(L"%\*(R")
will be used.
.IP "num_fortunes ()" 4
.IX Item "num_fortunes ()"
Returns the number of fortunes found by \f(CW\*(C`read_header()\*(C'\fR.
.IP "write_header ([\s-1DELIM\s0])" 4
.IX Item "write_header ([DELIM])"
is not yet implemented.
.SS "Fortune input"
.IX Subsection "Fortune input"
.IP "get_fortune (\s-1NUM\s0)" 4
.IX Item "get_fortune (NUM)"
Reads string number \s-1NUM\s0 from the open fortune file.  \s-1NUM\s0 is zero-based,
ie. it must be between 0 and \f(CW\*(C`num_fortunes()\-1\*(C'\fR (inclusive).  \f(CW\*(C`croak\*(C'\fRs if
you haven't opened the file and read the header, or if \s-1NUM\s0 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
\&\f(CW\*(C`read_header()\*(C'\fR.)  Returns the text of the fortune as a (possibly)
multiline string.
.IP "get_random_fortune ()" 4
.IX Item "get_random_fortune ()"
Picks a random fortune for you and reads it with \f(CW\*(C`read_fortune()\*(C'\fR.
.SS "Fortune output"
.IX Subsection "Fortune output"
.IP "write_fortune (\s-1FORTUNE\s0)" 4
.IX Item "write_fortune (FORTUNE)"
is not yet implemented.
.SH "AUTHOR AND COPYRIGHT"
.IX Header "AUTHOR AND COPYRIGHT"
Written by Greg Ward <gward@python.net>, 20 February 1999.
.PP
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.
.SH "AVAILABILITY"
.IX Header "AVAILABILITY"
You can download the \f(CW\*(C`Fortune\*(C'\fR module from my web page:
.PP
.Vb 1
\&   http://starship.python.net/~gward/perl/
.Ve
.PP
and it can also be found on \s-1CPAN.\s0
.PP
If you are using an operating system lacking a sufficient sense of
humour to include \f(CW\*(C`fortune\*(C'\fR as part of its standard installation (most
commercial Unices seem to be so afflicted), the Linux world has a
solution: the \f(CW\*(C`fortune\-mod\*(C'\fR distribution.  The latest version as of
this writing is \f(CW\*(C`fortune\-mod\-9708\*(C'\fR, and the \s-1README\s0 file says you can
find it at
.PP
.Vb 1
\&   http://www.progsoc.uts.edu.au/~dbugger/hacks/hacks.html
.Ve
.PP
This is the \f(CW\*(C`fortune\*(C'\fR implementation on which the \f(CW\*(C`Fortune\*(C'\fR module is
based.