NAME

WWW::MSA::Hadith

SYNOPSIS

use WWW::MSA::Hadith;

my $h = new WWW::MSA::Hadith();
$h->query('(paradise or heaven) and laugh and man and last');
$h->submit();

while ( my $result = $h->get_result() ) {
  print $h->read( $result->{id} );
  print "-" x 32;
  print "\n";
}

DESCRIPTION

WWW::MSA::Hadith is Perl interface to MSA-USC's Classic Hadith Search engine located at http://www.usc.edu/dept/MSA/reference/searchhadith.html

As of this release, only Sahih Bukhari database is supported. Will try to add other databases in subsequent releases.

PROGRAMMING STYLE

Searching Hadith database is very straight-forward, and consists of the following steps:

1. Create WWW::MSA::Hadith object:

   my $h = new WWW::MSA::Hadith();

2. Define the search query:

   $h->query("warn and peace");

3. Submit the search to remote server:

   $h->submit();

4. Iterate through the results:

   while (my $result = $h->get_result() ) {
     # do something....
   }

get_result() method, as seen above, results the next result fetched from the database. To iterate over all the results, you should use it in a while() loop or alternative.

Return value of get_result() is a reference to a hash-table. Hash consists of such keys as id - unique id for the returned Hadith, url - address of the resource, volume - volume number of the hadith, book - book number of the hadith and report - report number of the hadith.

As you noticed, returned result does not include the full content. To fetch the full content for a specific hadith, you need to call read() method and pass it id field of the result:

$full_text = $h->read($result->{id});

To view the demo of this library, send an e-mail to hadith@handalak.com and submit the search keyword in the subject of the mail. You will receive the results in the reply.

result_count() method can be used to retrieve how many results were fetched. user_agent() method returned UserAgent object, although you may not need it. In case you do, here it is.

TODO

I've been thinking of creating better programming interface through XML-RPC API.

SEE ALSO

http://www.usc.edu/dept/MSA/reference/searchhadith.html

AUTHOR

Sherzod B. Ruzmetov, <sherzodr@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2003 by Sherzod B. Ruzmetov.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.