summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorjluehrs2 <jluehrs2@uiuc.edu>2008-02-02 18:42:23 -0500
committerjluehrs2 <jluehrs2@uiuc.edu>2008-02-02 18:42:23 -0500
commit0cbef3716f8ecfc5fd40edc8b1e0e9770b8357df (patch)
treebb3715429b9dc0fa0f841cbd0324a719ebd1e9ef
parent5ecfe845a9e93f481c0a1e63b4df33a293b10ca9 (diff)
downloadgames-word-0cbef3716f8ecfc5fd40edc8b1e0e9770b8357df.tar.gz
games-word-0cbef3716f8ecfc5fd40edc8b1e0e9770b8357df.zip
add documentation to Games::Word::Wordlist
-rw-r--r--lib/Games/Word/Wordlist.pm153
1 files changed, 130 insertions, 23 deletions
diff --git a/lib/Games/Word/Wordlist.pm b/lib/Games/Word/Wordlist.pm
index f5aa6d1..59e35e0 100644
--- a/lib/Games/Word/Wordlist.pm
+++ b/lib/Games/Word/Wordlist.pm
@@ -5,6 +5,58 @@ use warnings;
use Games::Word qw/all_permutations is_subpermutation/;
use List::MoreUtils qw/uniq/;
+=head1 NAME
+
+Games::Word::Wordlist - manages a list of words
+
+=head1 VERSION
+
+Version 0.01 released ???
+
+=cut
+
+our $VERSION = '0.01';
+
+=head1 SYNOPSIS
+
+ use Games::Word::Wordlist;
+ my $wl = Games::Word::Wordlist->new('/usr/share/dict/words');
+ my $word = $wl->random_word;
+ print "we have a word" if $wl->is_word($word);
+
+=head1 DESCRIPTION
+
+Games::Word::Wordlist manages a list of words, either from a wordlist file on
+your computer or from a list of words you specify. You can use it to query
+things about the list, such as whether a given string is a word, or how many
+words are in the list, and you can also get words from the list, either
+randomly or by regex.
+
+=cut
+
+=head1 CONSTRUCTOR
+
+=head2 new()
+
+The constructor initializes the word list with words, either from a file or
+from an arrayref, given as the first argument. The remaining arguments are a
+paramhash which recognizes these options:
+
+=over 4
+
+=item cache
+
+Whether or not we want to keep an in memory cache of the words in the word
+list. Defaults to true, since this is what we want in almost all cases, as it
+speeds up lookups by several orders of magnitude. Can be set to false if either
+memory is a significant issue (word lists can be several megabytes in size) or
+if the word list is expected to change frequently during the running of the
+program.
+
+=back
+
+=cut
+
sub new {
my $class = shift;
my $word_list = shift;
@@ -40,6 +92,17 @@ sub new {
return $self;
}
+=head1 METHODS
+
+=head2 add_words
+
+Add words to the word list. Only works if the word list has been cached.
+
+Takes either a reference to an array containing the new words, or the name of a
+file to read in the words from. Ignores any words already in the word list.
+
+=cut
+
sub add_words {
my $self = shift;
my $word_list = shift;
@@ -57,6 +120,14 @@ sub add_words {
$self->{word_list} = [keys %{$self->{word_hash}}];
}
+=head2 remove_words
+
+Removes words from the word list. Only works if the word list is cached.
+
+Takes a list of words to remove (ignoring words that aren't in the word list).
+
+=cut
+
sub remove_words {
my $self = shift;
@@ -64,6 +135,12 @@ sub remove_words {
$self->{word_list} = [keys %{$self->{word_hash}}];
}
+=head2 words
+
+Returns the number of words in the word list.
+
+=cut
+
sub words {
my $self = shift;
@@ -109,6 +186,15 @@ sub _random_word_nocache {
return $word;
}
+=head2 random_word
+
+Returns a random word from the word list, optionally of a specified length.
+
+Takes a single optional integer argument, which will make it only consider
+words of that length in its search.
+
+=cut
+
sub random_word {
my $self = shift;
@@ -137,6 +223,16 @@ sub _is_word_nocache {
return 0;
}
+=head2 is_word
+
+Tests whether a word is in the word list.
+
+Takes a single argument, the word to be tested.
+
+Returns true if the word is found in the word list, false otherwise.
+
+=cut
+
sub is_word {
my $self = shift;
@@ -170,6 +266,17 @@ sub _each_word {
return $self->_each_word_nocache(@_);
}
+=head2 anagrams
+
+Finds all anagrams of a given string.
+
+Takes an argument of a string.
+
+Returns a list of all permutations of that string that are found in the word
+list.
+
+=cut
+
sub anagrams {
my $self = shift;
my $word = shift;
@@ -177,6 +284,16 @@ sub anagrams {
return uniq grep { $self->is_word($_) } all_permutations($word);
}
+=head2 words_like
+
+Searches through the word list by regex.
+
+Takes an argument of a regex.
+
+Returns a list containing all words in the word list matching that regex.
+
+=cut
+
sub words_like {
my $self = shift;
my $re = shift;
@@ -187,6 +304,17 @@ sub words_like {
return @words;
}
+=head2 subwords_of
+
+Searches for words which can be made using the letters of a given string.
+
+Takes an argument of a string.
+
+Returns a list of words from the word list which can be made using the letters
+in that string.
+
+=cut
+
sub subwords_of {
my $self = shift;
my $string = shift;
@@ -198,30 +326,9 @@ sub subwords_of {
return @words;
}
-=head1 NAME
-
-Games::Word::Wordlist - ???
-
-=head1 VERSION
-
-Version 0.01 released ???
-
-=cut
-
-our $VERSION = '0.01';
-
-=head1 SYNOPSIS
-
- use Games::Word::Wordlist;
- do_stuff();
-
-=head1 DESCRIPTION
-
-
-
=head1 SEE ALSO
-L<Foo::Bar>
+L<Games::Word>
=head1 AUTHOR
@@ -239,7 +346,7 @@ L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Games-Word>.
You can find this documentation for this module with the perldoc command.
- perldoc Games::Word
+ perldoc Games::Word::Wordlist
You can also look for information at: