NAME
WWW::Lipsum - perl interface to www.lipsum.com
SYNOPSIS
use WWW::Lipsum;
my $lipsum = WWW::Lipsum->new(
html => 1, amount => 50, what => 'bytes', start => 0
);
print "$lipsum\n"; # auto-fetches lipsum text
# Change an arg and check for errors explicitly
$lipsum->generate( html => 0 )
or die "Error: " . $lipsum->error;
print $lipsum->lipsum . "\n";
# Change some args and fetch using interpolation overload
$lipsum->start(0);
$lipsum->amount(5);
$lipsum->what('paras');
print "$lipsum\n";
# generate a whole bunch of lipsums
my @lipsums = map "$lipsum", 1..10;
DESCRIPTION
Generate Lorem Ipsum place holder text from perl, using www.lipsum.com
SEE ALSO
You most likely want Text::Lorem or Text::Lorem::More instead of this module, as those generate Lorem Ipsum text without using a web service.
METHODS
new
my $lipsum = WWW::Lipsum->new;
my $lipsum = WWW::Lipsum->new(
html => 1, amount => 50, what => 'bytes', start => 0
);
Creates and returns a brand new WWW::Lipsum object. Takes
a number of optional arguments that are given as key/value
pairs. These specify the format of the generated lipsum
text and can be changed either individually, using the
appropriate accessor methods, or when calling ->generate method.
Possible arguments are as follows:
what
my $lipsum = WWW::Lipsum->new( what => 'paras' );
my $lipsum = WWW::Lipsum->new( what => 'lists' );
my $lipsum = WWW::Lipsum->new( what => 'words' );
my $lipsum = WWW::Lipsum->new( what => 'bytes' );
Optional. Specifies in what form to get the
Lorem Ipsum text. Valid values are lowercase strings
paras, lists, words, and bytes that mean to get the text
as paragraps, lists, words, or bytes respectively.
Defaults to: paras.
The meaning is most relevant for the amount argument (see below). The
lists value will cause generation of variable-item-number lists of
Lorem Ipsum text. Note: there seems to be very loose adherence
to the amount you specified and what you get when you
request bytes, and the value seems to be ignored
if amount is set too low.
amount
my $lipsum = WWW::Lipsum->new( amount => 10 );
Optional. Takes a positive integer as a value. Large values
will likely be abridged by www.lipsum.com to something reasonable.
Specifies the number of what (see above) things to get.
Defaults to: 5.
html
my $lipsum = WWW::Lipsum->new( html => 1 );
Optional. Takes true or false values. Specifies whether to wrap
Lorem Ipsum text in HTML markup (will wrap in HTML when set to
a true value). This will be <ul>/<li>
elements when what is set to lists and <p> elements
for everything else. When set to false, paragraphs and lists will
be separated by double new lines. Defaults to: 0 (false).
start
my $lipsum = WWW::Lipsum->new( start => 0 );
Optional. Takes true or false values as a value. When set
to a true value, will ask www.lipsum.com
to start the generated
text with "Lorem Ipsum". Defaults to: 1 (true)
Note: it seems sometimes www.lipsum.com would return text that starts with "Lorem Ipsum" simply by chance.
generate
my $text = $lipsum->generate(
html => 1, amount => 50, what => 'bytes', start => 0
) or die $lipsum->error;
my $x = $text;
# or
$lipsum->generate or die $lipsum->error;
$text = $lipsum->lipsum;
# or
my $text = "$lipsum";
Accesses www.lipsum.com to obtain requested
chunk of Lorem Ipsum text.
Takes the same arguments as new (see above); all optional.
On success returns generated Lorem Ipsum text. On failure
returns undef or an empty list, depending on the context, and
the reason for failure will be available via the ->error method.
Note: if you call ->generate with arguments, the new
values will persist for all subsequent calls to ->generate,
until you change them either by, again, passing arguments to
->generate, or by using accessor methods.
You can call ->generate by simply interpolating the WWW::Lipsum
object in a string. When called this way, if an error occurs, the
interpolated value will be [Error: ERROR_DESCRIPTION_HERE], where
ERROR_DESCRIPTION_HERE is the return value of ->error method.
On success, the interpolated value will be the generated Lorem Ipsum
text.
lipsum
$lipsum->generate or die $lipsum->error;
$text = $lipsum->lipsum;
Takes no arguments. Must be called after a successful call to
->generate. Returns the same thing the last successful call
to ->generate returned.
error
$lipsum->generate
or die 'Error occured: ' . $lipsum->error;
Takes no arguments. Returns the human-readable message, explaining
why the last call to ->generate failed.
what
my $current_what = $lipsum->what;
$lipsum->what('paras');
$lipsum->what('lists');
$lipsum->what('words');
$lipsum->what('bytes');
Takes a single optional argument that is the same as the value for the
what argument of the ->new method.
When given an argument, modifies the currently active value for the
what argument.
Returns the currently active value of what argument (which
will be the provided argument, if one is given).
See ->new method for more info.
start
my $current_start = $lipsum->start;
$lipsum->start(0);
$lipsum->start(1);
Takes a single optional argument that is the same as the value for the
start argument of the ->new method.
When given an argument, modifies the currently active value for the
start argument. Returns the currently active value of start
argument (which will be the provided argument, if one is given).
See ->new method for more info.
amount
my $current_amount = $lipsum->amount;
$lipsum->amount(50);
$lipsum->amount(15);
Takes a single optional argument that is the same as the value for the
amount argument of the ->new method.
When given an argument, modifies the currently active value for the
amount argument.
See ->new method for more info.
html
my $current_html = $lipsum->html;
$lipsum->html(1);
$lipsum->html(0);
Takes a single optional argument that is the same as the value for the
html argument of the ->new method.
When given an argument, modifies the currently active value for the
html argument. Returns the currently active value of html
argument (which will be the provided argument, if one is given).
See ->new method for more info.
REPOSITORY
Fork this module on GitHub: https://github.com/zoffixznet/WWW-Lipsum
BUGS
To report bugs or request features, please use https://github.com/zoffixznet/WWW-Lipsum/issues
If you can't access GitHub, you can email your request
to bug-www-lipsum at rt.cpan.org
AUTHOR
Zoffix Znet (http://zoffix.com/, http://haslayout.net/)
LICENSE
You can use and distribute this module under the same terms as Perl itself.
See the LICENSE file included in this distribution for complete
details.
HISTORY AND NOTES ON OLD VERSION
There used to be another version of WWW::Lipsum on CPAN, developed
by Earle Martin. I have a couple of modules that depend on
WWW::Lipsum. Earle, or someone else, subsequently deleted it from
CPAN, leaving my modules dead.
At first, I resurrected Earle's version, but it had a bug. The code was using HTML::TokeParser and was a pain in the butt to maintain, and the interface really irked me. So, I rewrote the whole thing from scratch, broke the API (more or less), and released the module under a same-as-perl license.
If you are looking for Earle's version, it can still be accessed on BackPAN.