Fortune(3pm)

🎀 Fortune(3pm) — the vibe-y guide 🎀

okay bestie, we're doing Fortune, a Perl module that lives in User Contributed Perl Documentation, section 3pm, and it's literally here to read and write your fortune (strfile) databases. no cap. let's go 💅

---

✨ NAME ✨

Fortune — read and write fortune (strfile) databases 🍓

---

🦋 SYNOPSIS 🦋

the input era 💖:

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

making a header file out of a data file — NOT IMPLEMENTED YET 😭:

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

writing to the data file — also NOT IMPLEMENTED YET 🙈:

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

---

💜 DESCRIPTION 💜

so the fortune program is this small but iconic little slice of Unix culture, and this module's whole mission is to bring support for its "fortune cookie" databases to Perl girlies everywhere. for efficiency reasons, every version of fortune leans on a binary header that's mostly just offsets pointing into the actual fortune file. modern versions of fortune keep that header in a separate file, and that's the style Fortune adopted. the older style — munging the header and the data together into one big "compiled" file — is not (currently) supported, periodt.

using Fortune makes writing a simplified version of the fortune program genuinely trivial, like:

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

and it can be compressed considerably ✨:

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

obviously this does not serve all of fortune's interesting features — parallel databases of offensive fortunes? selection of long or short fortunes? dealing with multiple fortune files? none of that here, bestie. if you want fortune, use it. but if you just want a simple Perl interface to its data files, Fortune is your main character 💅

currently, the Fortune module does not support writing fortune databases. if it did, writing a simplified strfile (that's the program that processes a fortune database and makes 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 ();

quick note though 👀 — the header filename is assumed to be just the name of the main fortune database with .dat appended. you can hand an alternate header filename to the constructor, new(), if that's more your vibe.

---

🌸 METHODS 🌸

🌈 Initialization/cleanup 🌈

• new (FILE [, HEADER_FILE]) — opens a fortune cookie database, slay. FILE is the name of the data file you're opening, and HEADER_FILE (if you give it) is the name of the header file that contains (or will contain) the meta-data about the fortune database. if HEADER_FILE isn't given, it defaults to FILE with .dat appended.

the data file gets opened via open_file(), which dies 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, and we're not about to embarrass ourselves. instead, you must explicitly call read_header() or write_header() as appropriate. do not skip this step fr fr.

• 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 absolutely nothing otherwise. no notes.

🧚 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's based on the name of the data file, or it was supplied by the caller.

if the header file doesn't exist, this function calls compute_header() automatically, which has the same effect as reading the header from a file. cute, right?

the header contains these values, 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, like:

$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. no saving you there bestie 😭

read_header() returns the current Fortune object, which allows for sneaky one-liners (peep 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. super useful if you maintain a file of fortunes by hand and don't have the corresponding data file.

an optional delimiter argument may be passed to this function; if present, that delimiter gets used to separate entries in the fortune file. if not provided, the existing delim attribute of the Fortune object is used. and if that is not defined, then a percent sign (%) is used. iconic fallback behavior honestly.

• 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 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(). that part is on you.) 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(). it's giving chaos, it's giving destiny 🎲

🫶 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're using an operating system that's 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. 🫡

---

and that's the whole page, bestie 🎀 this was Fortune(3pm) from perl v5.36.0, dated 2022-11-19 — go read some fortunes, you ate 💅✨