Class: File_Fortune

Initializes the PEAR_ErrorStack and assigns it to $error.

If a fortune file is provided to the constructor, it attempts to open it. If no $headerFilename is provided, "$filename.dat" will be used. The open operation is performed by open(); if an error occurs with that operation, an error will be pushed onto the $error.

If no data file is given, the class will be instantiated with no data, and you will need to open a file before performing any operations.

Parameters:

Closes fortune file, utilizing close().

Closes the fortune file if it's open, and unsets all header-related properties (except $delim); does nothing otherwise.

Retrieves all fortunes in a file, returning them as an array and placing them in the $fortunes property. If the $numstr property has not been set, or if an error occurs elsewhere along the chain, throws an exception.

Picks a random fortune for you and reads and returns it with read(). If the $numstr propery has not been set, throws an exception.

Returns a random fortune from a list of fortune files. The list of files may be either specified as individual arguments, as a single array argument, or as a mixture of individual files and arrays of files. Invalid arguments -- non-files -- will be skipped.

Returns the number of fortunes found by readHeader(). If the $numstr property has not been set, throws an exception.

Opens a fortune file. If no $headerFilename is given, "$filename.dat" is used; if $headerFilename is invalid or not present, the class will parse the fortune file in order to build the necessary header elements.

Once the file has been opened, its file handle will be assigned to $file. Additionally, a number of other properties will be set:

• $numstr
• $offsets
• $delim
• $flags
• $maxLength
• $minLength
• $version

If no header file is present, open() will read the entire file into memory, and store all fortunes in $fortunes.

Returns true on success; on failure, throws an exception.

Note: If a file is already open when open() is called, that file is first closed.

Parameters:

Reads string number $num from the open fortune file. $num is ordinal, ie. it must be between 1 and $numstr (inclusive). Throws an exception 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 open(), and any real errors should occur during that call.) Returns the text of the fortune as a (possibly) multiline string.

In order to read a fortune, one of the following actions is taken:

• If $fortunes is populated, it grabs the fortune from there.
• Otherwise, it utilizes _readFromFile() to grab the fortune from the fortune file.

Parameters:

Reads the contents of the fortune file and computes the header information that would normally be found in a header (.dat) file and read by _readHeader(). This is useful if you maintain a file of fortunes by hand and do not have the corresponding data file. (If this is the case, you may also want to look at File_Fortune_Writer::write().

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, a percent sign ("%") will be used (this is the standard fortune file delimiter).

Additionally, the $noHeader property will be set to true.

NOTE: It is most efficient to use fortune files that have header files. In order to get offsets and fortunes, this method actually must read the entire fortune file, and stores all fortunes in the $fortunes array.

Parameters:

Loops through an array, searching for files. An array of unique files found is returned.

Parameters:

Reads a fortune directly from the file. If an error occurs, an exception is thrown. Otherwise, on sucess, the fortune is returned.

Parameters:

Reads the header file associated with this fortune database. The name of the header file is determined by the constructor: 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 _computeHeader() 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 File_Fortune object:

• $version; version number
• $numstr; number of strings (fortunes) in the file
• $maxLength; length of longest string in the file
• $minLength; 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 numFortunes() method; if you're interested in the others, you'll have to go grubbing through the File_Fortune object, e.g.:

 $fortune_file = new Fortune('fortunes');

 $delim        = $fortune_file->delim;
 $maxLength    = $fortune_file->maxLength;

_readHeader() throws an exception if there are any problems reading the header file, e.g. if it seems to be corrupt or truncated.