.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "Data::Random::WordList 3"
.TH Data::Random::WordList 3 2025-11-02 "perl v5.42.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Data::Random::WordList \- Perl module to get random words from a word list
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  use Data::Random::WordList;
\&
\&  my $wl = new Data::Random::WordList( wordlist => \*(Aq/usr/dict/words\*(Aq );
\&
\&  my @rand_words = $wl\->get_words(10);
\&
\&  $wl\->close();
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Data::Random::WordList is a module that manages a file containing a list of words.
.PP
The module expects each line of the word list file to contain only one word.  It could thus be easily used to select random lines from a file, but for coherency\*(Aqs sake, I\*(Aqll keep referring to each line as a word.
.PP
The module uses a persistent filehandle so that there isn\*(Aqt a lot of overhead every time you want to fetch a list of random words.  However, it\*(Aqs much more efficient to grab multiple words at a time than it is to fetch one word at a time multiple times.
.PP
The module also refrains from reading the whole file into memory, so it can be safer to use with larger files.
.SH METHODS
.IX Header "METHODS"
.SS \fBnew()\fP
.IX Subsection "new()"
Returns a reference to a new Data::Random::WordList object.  Use the "wordlist" param to initialize the object:
.IP \(bu 4
wordlist \- the path to the wordlist file.  If a path isn\*(Aqt supplied, the wordlist distributed with this module is used.
.SS get_words([NUM])
.IX Subsection "get_words([NUM])"
NUM contains the number of words you want from the wordlist.  NUM defaults to 1 if it\*(Aqs not specified.  \fBget_words()\fR dies if NUM is greater than the number of words in the wordlist.  This function returns an array or an array reference depending on the context in which it\*(Aqs called.
.SS \fBclose()\fP
.IX Subsection "close()"
Closes the filehandle associated with the word list.  It\*(Aqs good practice to do this every time you\*(Aqre done with the word list.
.SH VERSION
.IX Header "VERSION"
0.12
.SH AUTHOR
.IX Header "AUTHOR"
Originally written by: Adekunle Olonoh
.PP
Currently maintained by: Buddy Burden (barefoot@cpan.org), starting with version 0.06
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (c) 2000\-2011 Adekunle Olonoh.
Copyright (c) 2011\-2015 Buddy Burden.
All rights reserved.  This program is free software; you
can redistribute it and/or modify it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Data::Random