ACME-QuoteDB
view release on metacpan or search on metacpan
lib/ACME/QuoteDB.pm view on Meta::CPAN
# search all 'ralph' quotes for string 'wookie'
print $sq->get_quotes_contain({
Contain => 'wookie',
AttrName => 'ralph',
Limit => 1 # only return 1 quote (if any)
});
# output:
I bent my wookie.
-- Ralph Wiggums
# returns all quotes attributed to 'ralph', with a rating between
# (and including) 7 to 9
print join "\n", @{$sq->get_quotes({
AttrName => 'ralph',
Rating => '7-9'
})
};
# same thing but limit to 2 results returned
# (and including) 7 to 9
print join "\n", @{$sq->get_quotes({
AttrName => 'ralph',
Rating => '7-9',
Limit => 2
})
};
# get 6 random quotes (any attribution)
foreach my $q ( @{$sq->get_quotes({Limit => 6})} ) {
print "$q\n";
}
# get list of available attributions (that have quotes provided by this module)
print $sq->list_attr_names;
# any unique part of name will work
# i.e these will all return the same results (because of our limited
# quotes db data set)
print $sq->get_quotes({AttrName => 'comic book guy'});
print $sq->get_quotes({AttrName => 'comic book'});
print $sq->get_quotes({AttrName => 'comic'});
print $sq->get_quotes({AttrName => 'book'});
print $sq->get_quotes({AttrName => 'book guy'});
print $sq->get_quotes({AttrName => 'guy'});
# get all quotes, only using these categories (you have defined)
print @{$sq->get_quotes({ Category => [qw(Humor ROTFLMAO)] })};
# get all quotes from Futurama
print @{$sq->get_quotes({Source => Futurama})};
Also see t/02* included with this distribution.
(available from the CPAN if not included on your system)
=head1 SUBROUTINES/METHODS
For the most part this is an OO module. There is one function (quote) provided
for command line 'one liner' convenience.
=head2 quote
returns one quote. (is exported).
this takes identical arguments to 'get_quote'. (see below)
example:
perl -MACME::QuoteDB -le 'print quote()'
=head2 new
instantiate a ACME::QuoteDB object.
takes no arguments
# example
my $sq = ACME::QuoteDB->new;
=head2 get_quote
returns one quote
# get random quote from any attribution
print $sq->get_quote;
# get random quote from specified attribution
print $sq->get_quote({AttrName => 'chief wiggum'});
Optional arguments, a hash ref.
available keys: AttrName, Rating
my $args_ref = {
AttrName => 'chief wiggum'
Rating => 7,
};
print $sq->get_quote($args_ref);
Note: The 'Rating' option is very subjective.
It's a 0-10 scale of 'quality' (or whatever you decide it is)
To get a list of the available AttrNames use the list_attr_names method
listed below.
Any unique part of name will work
Example, for attribution 'comic book guy'
# these will all return the same results
print $sq->get_quotes({AttrName => 'comic book guy'});
print $sq->get_quotes({AttrName => 'comic book'});
print $sq->get_quotes({AttrName => 'comic'});
print $sq->get_quotes({AttrName => 'book'});
print $sq->get_quotes({AttrName => 'book guy'});
lib/ACME/QuoteDB.pm view on Meta::CPAN
returns zero or more quote(s), based on a basic text search.
# get specific quote based on basic text search.
# search all ralph wiggum quotes for string 'wookie'
print $sq->get_quotes_contain({
Contain => 'wookie',
AttrName => 'ralph',
Limit => 1 # only return 1 quote (if any)
})->[0]; # q{Ralph: I bent my wookie.};
Optional arguments, a hash ref.
available keys: AttrName, Contain, Limit
AttrName and Limit work exactly the same as for get_quotes (docs above)
Contain specifies a text string to search quotes for. If a AttrName
option is included, search is limited to that attribution.
Contain is a simple text string only. Regex not supported
Contain literally becomes: AND quote LIKE '%$contain%'
=head2 list_attr_names
returns a list of attributions (name) for which we have quotes.
# get list of available attributions (that have quotes provided by this module)
print $sq->list_attr_names;
=head2 list_categories
returns a list of categories defined in the database
# get list of available categories (that have quotes provided by this module)
print $sq->list_categories;
=head2 list_attr_sources
returns a list of attribution sources defined in the database
# get list of attribution sources (that have quotes provided by this module)
print $sq->list_attr_sources;
=head1 LOADING QUOTES
In order to actually use this module, one has to load quotes content,
hopefully this is relativly easy,... (see t/01-load_quotes.t in tests)
=over 4
=item 1 add_quote, one record at a time, probably within an iteration loop
see L</add_quote>
=item 1 (Batch Load) load quotes from a csv file. (tested with comma and tab delimiters)
format of file must be as follows: (headers)
"Quote", "Attribution Name", "Attribution Source", "Category", "Rating"
for example:
"Quote", "Attribution Name", "Attribution Source", "Category", "Rating"
"I hope this has taught you kids a lesson: kids never learn.","Chief Wiggum","The Simpsons","Humor",9
"Sideshow Bob has no decency. He called me Chief Piggum. (laughs) Oh wait, I get it, he's all right.","Chief Wiggum","The Simpsons","Humor",8
=item 1 if these dont suit your needs, ACME::QuoteDB::LoadDB is sub-classable,
so one can extract data anyway they like and populate the db themselves.
(there is a test that illustrates overriding the stub method, 'dbload')
you need to populate a record data structure:
$self->set_record(quote => q{}); # mandatory
$self->set_record(name => q{}); # mandatory
$self->set_record(source => q{}); # optional but useful
$self->set_record(catg => q{}); # optional but useful
$self->set_record(rating => q{}); # optional but useful
# then to write the record you call
$self->write_record;
NOTE: this is a record-by-record operation, so one would perform this within a
loop. there is no bulk (memory dump) write operation currently.
=back
For more see L<ACME::QuoteDB::LoadDB>
=begin comment
keep pod coverage happy.
# Coverage for ACME::QuoteDB is 71.4%, with 3 naked subroutines:
# Attr
# Quote
# Catg
# QuoteCatg
pod tests incorrectly state, Attr, Quote and Catg are subroutines, well they
are,... (as aliases) but act on a different object.
TODO: explore the above (is this a bug, if so, who's?, version effected,
create use case, etc)
=head2 Attr
=head2 Quote
=head2 Catg
=head2 QuoteCatg
=end comment
lib/ACME/QuoteDB.pm view on Meta::CPAN
a backup mechanism for your db to a regular text csv file.
=item 1 clean up tests 'skip if module X' not installed
(one of sqlite3 or mysql is required). currently dies if DBD::SQLite not
installed
=item 1 support multiple categories from LoadDB
how to load multipul categories from a csv file?
(try to avoid somthing ugly in our csv file format). or maybe don't support
this.
=item 1 (possibly) support long/short quotes output (see 'man fortune')
=back
=head1 BUGS AND LIMITATIONS
The CRUD stuff is weak for sure.
(i.e. add_quote, update_quote, delete_quote, get_quote_id)
For example, currently you can only get the quote id from the exact quote
In the future, I may just expose the DBI::Class object directly
to those that need/want it.
=begin comment
get_quotes_contain uses %search% to do it's pattern mattching, so that will
miss some obvious searches, which it should find.
i.e.
'Bill' will not find 'Bill' , beginning and endings of words will be off.
XXX - look at search_like, instead of what you are doing now
=end comment
currently, I am not encapsulating the record data structure used
by LoadDB->write. (i.e. it's a typical perl5 ojbect, the blessed hash)
I will for sure be encapsulating all data in a future version.
(so, don't have code that does $self->{record}->{name} = 'value', or you won't
be happy down the road). Instead use $self->get_record('name') (getter) or
$self->set_record(name => 'my attrib') (setter)
When we are using a SQLite database backend ('regular' local usage), we
should probably be using, ORLite instead of Class::DBI
(although we have not seen any issues yet).
Please report any bugs or feature requests to C<bug-acme-quotedb at rt.cpan.org>, or through
the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=ACME-QuoteDB>.
I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
=head1 SUPPORT
You can find documentation for this module with the perldoc command.
perldoc ACME::QuoteDB
You can also look for information at:
=over 4
=item * RT: CPAN's request tracker
L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=ACME-QuoteDB>
=item * AnnoCPAN: Annotated CPAN documentation
L<http://annocpan.org/dist/ACME-QuoteDB>
=item * CPAN Ratings
L<http://cpanratings.perl.org/d/ACME-QuoteDB>
=item * Search CPAN
L<http://search.cpan.org/dist/ACME-QuoteDB/>
=back
=head1 ACKNOWLEDGEMENTS
The construction of this module was guided by:
Perl Best Practices - Conway
Test Driven Development
Object Oriented Programming
Gnu
vim
Debian Linux
Mac OSX
The collective wisdom and code of The CPAN
this module was created with module-starter
module-starter --module=ACME::QuoteDB \
--author="David Wright" --mb --email=david_v_wright@yahoo.com
=head1 ERRATA
Q: Why did you put it in the ACME namespace?
A: Seemed appropriate. I emailed modules@cpan.org and didn't get a
different reaction.
Q: Why did you write this?
A: At a past company, a team I worked on a project with had a test suite,
in which at the completion of successful tests (100%), a 'wisenheimer'
success message would be printed. (Like a quote or joke or the like)
(Interestingly, it added a 'fun' factor to testing, not that one is needed
of course ;). It was hard to justify spending company time to find and
add decent content to the hand rolled process, this would have helped.
Q: Don't you have anything better to do, like some non-trivial work?
A: Yup
Q: Hey Dood! why are u uzing Class::DBI as your ORM!? Haven't your heard
of L<DBIx::Class>?
A: Yup, and I'm aware of 'the new hotness' L<Rose::DB>. If you use this
module and are unhappy with the ORM, feel free to change it.
So far L<Class::DBI> is working for my needs.
=head1 FOOTNOTES
=over 4
=item fortune
unix application in 'games' (FreeBSD) type 'man fortune' from the command line
=item copyright infringement
L<http://www.avvo.com/legal-answers/is-it-copyright-trademark-infringement-to-operate--72508.html>
=item wikiquote
interesting reading, wikiquote fair use doc: L<http://en.wikiquote.org/wiki/Wikiquote:Copyrights>
=back
=head1 LICENSE AND COPYRIGHT
Copyright 2009 David Wright, all rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
=cut
1; # End of ACME::QuoteDB
( run in 1.876 second using v1.01-cache-2.11-cpan-d8267643d1d )