view release on metacpan or  search on metacpan

Wabby.pm  view on Meta::CPAN

=over 8

=item min_len

The minimum length for a generated sentence. (3)

=item max_len

The maximum length for a generated sentence. (30)

=item punctuation

A reference to an array containing possible punctuation with which to end sentences. ([".","?","!","..."])

=item case_sensitive

Whether or not to treat text in a case sensitive manner. (1)

=item hash_file

The file to/from which the hash data will be stored/loaded if requested. ("./wabbyhash.dat")

=item list_file

The file to/from which the list data will be stored/loaded if requested. ("./wabbylist.dat")

=item autosave_on_destroy

Whether or not to automatically save the state upon object destruction. (0)

=item max_attempts

The maximum number of attempts to create a sentence before giving up. (1000)

=back

=head2 Adding text to the state

To have an amusing experience, you will need to feed the object a body of text.
This text can come from virtually any source, although I enjoy using e-Texts
from the good folks at Project Gutenberg (http://promo.net/pg).  To add text to
the state, simply call the B<add()> method on the object, passing it a scalar
containing the text.

  $wabby->add($complete_works_of_shakespeare);

It is acceptable for the input text to contain embedded newlines or other such
things.  It is acceptable to call the B<add()> method many times, and at any
point in the object's life-span.  The B<add()> method will return B<undef> upon
error, and true upon success.

=head2 Generating random sentences

Once you have some text loaded into the object, you can generate random
sentences.  To do this, we use the B<spew()> method.  The B<spew()> method has
two modes of operation:  If no argument is given, it will generate and return a
random sentence.  If a single string is passed in, it will generate and return
a random sentence beginning with the provided string.

  my $random_sentence = $wabby->spew;
  my $not_so_random_sentence = $wabby->spew("Romeo and Juliet");

The B<spew()> method will return the generated string, or B<undef> upon error.
There are several error conditions which can occur in the B<spew()> method.
None of them are fatal, but they must be taken into account by the calling
program.  They are:

* At least (min_len * 10) words haven't been run through yet. (Must B<add()>
more text before trying again.)

* A string was passed in containing nothing. (Don't do that.)

* We don't know the last word in the string passed in, and can therefore not
generate a sentence with it. (Either teach us about it with B<add()>, or try
something else.)

* A sentence of at least min_len words could not be generated, even after
max_attempts tries at doing so. (Likely need to B<add()> more text before
trying again.)

=head2 Saving / loading state

Acme::Wabby can save and load state to disk using the Storable module.  To do
this, simply use the B<save()> and/or B<load()> methods.

  $wabby->save;
  $wabby->load;

These methods take no arguments, they simply save or load the state to or from
the file names which were defined when the object was created.  Loading a
saved state is much faster than re-parsing a large body of text.

=head2 Getting statistics

Using the B<stat()> method will provide you with some simple statistics about
the current state of an object.  When used in a scalar context, the B<stat()>
method will return a string containing a description of what the object knows.
When used in a list context, it will return a list of two numbers.  The first
entry in the list is the number of words that the object knows.  The second
entry in the list is the average number of connections between words.

  my ($wordcount, $average) = $wabby->stats;
  print "count=$wordcount, average=$average\n";
  print scalar($wabby->stats), "\n";

=head1 BUGS

 * Uses a lot of memory (not so much a bug as an implementation quirk).

=head1 TODO

 * Be better about normalizing input text.
 * Fix english assumtions about single-letter words besides I and a.
 * See about making the parsing into phrases and words more configurable.
 * Investigate using longer-order chains to improve generation quality.
 * Try to use less memory!

=head1 AUTHOR

Nathan Poznick <kraken@wang-fu.org>