/ 
File-Strfile-0.03
River stage zero No dependents
/ File::Strfile

NAME

File::Strfile - OO strfile interface

SYNOPSIS

use File::Strfile;

$strfile = File::Strfile->new($src);

$strfile->read_strfile($datafile);

$strfile->random();

$strfile->order();

$str0 = $strfile->string(0);

foreach my $str ($strfile->strings()) {
  ...
}

$strfile->write_strfile($datafile);

DESCRIPTION

File::Strfile provides an object oriented interface for reading and writing strfiles, a file format often associated with the classic UNIX program fortune(6). Strfiles are used to provide random access to strings stored in another file, called the strfile source. The source files consists of a collection of strings seperated by delimiting lines, which are lines containing only a single delimiting character, typically a percentage (%) sign. The strfile data files are usually stored in the same directory as the source files, with the same name but with the ".dat" suffix added. They contain a header that describes the strfile database and a table of offsets pointing to each string in the source file.

This module only provides an interface for manipulating strfile data files, not the source text files themselves.

Object Methods

File::Strfile->new($srcpath, [{opt => 'val'}])

Returns a new File::Strfile object. $srcpath is the path to the source strfile.

new() can be given a hash reference of options. Note that all options are case-sensitive.

DataFile

Path to the strfile-generated data file. Instead of new() creating strfile data from scratch, it will read data the from the given data file by calling read_strfile(). Some fields can be overrided by passing additional options.

Version

Set version for outputted strfile. The following are acceptable version numbers:

  1. Original strfile version. Stores string offsets as unsigned 64-bit integars. Most common. Default.

  2. Newer strfile version. Stores string offsets as unsigned 32-bit integars.

Random

Randomize the order of string offsets.

Order

Order string offsets alphabetically.

FcOrder

Order string offsets alphabetically, case-insensitive.

Rotate

Mark the source file as being ROT-13 ciphered.

Delimit

Set delimitting character. Default is a percentage sign (%). This option does not work with the DataFile option.

new() dies upon failure.

$strfile->read_strfile($file)

Read strfile data from $file.

$strfile->order([$fc])

Order strings alphabetically. If $fc is true, sort is done insensitive to case.

$strfile->random()

Randomize the order of strings.

$strfile->string($n)

Get $n-th string from string file. Returns undef if $n-th string does not exist.

$strfile->strings()

Returns list of all strings in strfile, in the order specified by the offset table.

$strfile->strings_like($re)

Return list of strings that evaluate true given the qr regex $re.

For example, to get every string that starts with 'YOW!':

my @yows = $strfile->strings_like(qr/^YOW!/)

Note that the 'm' (multiline) option is automatically used and does not need to be specified.

$strfile->get($member)

Return value of $member in $strfile object. Note $member is case-sensitive. The following are valid members:

SrcFile

Absolute path to strfile source file.

Version

Version of $strfile.

StrNum

Number of strings in $strfile.

LongLen

Length (in bytes) of the longest string in $strfile.

ShortLen

Length (in bytes) of the shortest string in $strfile.

Flags

Flag bitfield for $strfile. See documentation for %STRFLAGS for what each bitmask means.

Delimit

Delimitting character.

Offsets

Array ref of strfile offsets. The last offset will not be a string offset but the EOF offset.

On failure, get() returns undef.

$strfile->write_strfile([$file])

Write $strfile data file to either $file. If $file is not supplied, write to source file path + '.dat' suffix.

Global Variables

$File::Strfile::VERSION

File::Strfile version.

%File::Strfile::STRFLAGS

Hash of strfile flags and their bitmasks.

RANDOM => 0x1

Strings were randomly sorted.

ORDERED => 0x2

Strings were sorted alphabetically. Takes priority over Random.

ROTATED => 0x4

Strings are ROT-13 ciphered.

Able to be exported.

use File::Strfile qw(%STRFLAGS);

EXAMPLES

Here is an example of a typical source strfile:

A can of ASPARAGUS, 73 pigeons, some LIVE ammo, and a FROZEN DAIQUIRI!!
%
A dwarf is passing out somewhere in Detroit!
%
A wide-eyed, innocent UNICORN, poised delicately in a MEADOW filled
with LILACS, LOLLIPOPS & small CHILDREN at the HUSH of twilight??
%
Actually, what I'd like is a little toy spaceship!!

RESTRICTIONS

Despite version 1 strfiles storing string offsets as unsigned 64-bit integars, they are still read as 32-bit. This means that File::Strfile will not be able to read strfile sources larger than 4GB (about the size of 1,000 plaintext KJV Bibles).

File::Strfile tries to emulate the original BSD strfile's behavior as close as possible, which means it will also inherit some of its quirks.

AUTHOR

Written by Samuel Young <samyoung12788@gmail.com>.

COPYRIGHT

Copyright 2024, Samuel Young

This library is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

fortune(6), strfile(8)