/[SWISH-PlusPlus]/trunk/PlusPlus.pm

This is repository of my old source code which isn't updated any more. Go to git.rot13.org for current projects!

Diff of /trunk/PlusPlus.pm

Parent Directory | Revision Log | View Patch Patch

-revision 1 by dpavlin,
Fri Dec  3 13:31:43 2004 UTC
+revision 8 by dpavlin,
Sat Dec  4 17:49:20 2004 UTC
 Line 4 
 use 5.008004;
  use strict;
  use warnings;
- our $VERSION = '0.01';
+ our $VERSION = '0.02';
  use Carp;
+ use File::Temp qw/ tempdir /;
+ #use YAML;
  =head1 NAME
-Line 20 
 SWISH::PlusPlus - Perl extension SWISH++
+Line 22 
 SWISH::PlusPlus - Perl extension SWISH++
  =head1 DESCRIPTION
  This is perl module to use SWISH++ indexer by Paul J. Lucas. SWISH++ is
- rewrite of swish-e in C++ with blazingly fast performance, but without
+ rewrite of swish-e in C++ which is extremly fast (thank to mmap), but without
- support for properties (which this module tries to fix)
+ support for properties (which this module tries to fix).
+ Implementation of this module is crafted after L<Plucene::Simple> and it
+ should be easy to replace Plucene with this module for increased
+ performance. However, this module is not plug-in replacement.
  =head1 METHODS
-Line 29 
 support for properties (which this modul
+Line 35 
 support for properties (which this modul
  Create new indexing object.
-   my $i = new SWISH::PlusPlus(
+   my $i = SWISH::PlusPlus->open(
-         index => '/path/to/index',
+         index_dir => '/path/to/index',
+         index => 'index++',
+         search => 'search++',
+         debug => 1,
    );
  Options to open are following:
  =over 5
+ =item C<index_dir>
+ Path to directory in which index will be created.
  =item C<index>
- path to directory in which index will be created.
+ Full or partial path to SWISH++ index executable. By default, it's B<index>
+ for self-compiled version. If you use Debian GNU/Linux package specify
+ B<index++>. See C<Debian>.
+ =item C<search>
+ Full or partial path to SWISH++ search executable. By default, it's B<search>.
+ =item C<debug>
+ This option (off by default) will produce a lot of debugging output on
+ C<STDERR> prefixed by C<##>.
  =back
  =cut
- sub new {
+ sub open {
          my $class = shift;
          my $self = {@_};
          bless($self, $class);
-         foreach (qw(index)) {
+         foreach (qw(index_dir)) {
                  croak "need $_" unless $self->{$_};
          }
-         if (! -e $self->{'index'}) {
+         if (! -e $self->{'index_dir'}) {
-                 mkdir $self->{'index'} || confess "can't create index ",$self->{'index'},": $!";
+                 mkdir $self->{'index_dir'} || confess "can't create index ",$self->{'index'},": $!";
          }
+         # default executables
+         $self->{'index'} ||= 'index';
+         $self->{'search'} ||= 'search';
+         print STDERR "## open index_dir: ",$self->{'index_dir'}," index: ",$self->{'index'}, " search: ",$self->{'search'},"\n" if ($self->{'debug'});
          $self ? return $self : return undef;
  }
+ =head2 check_bin
+ Check if swish++ binaries specified in L<open> are available and verify
+ version signature.
+   if ($i->check_bin) {
+         print "swish++ binaries found\n";
+   };
+ It will also setup property
+   $i->{'version'}
+ which you can examine to see version.
+ =cut
+ sub check_bin {
+         my $self = shift;
+         my $i = `$self->{'index'} -V 2>&1` || confess "can't find '",$self->{'index'},"' binary";
+         my $s = `$self->{'search'} -V 2>&1` || confess "can't find '",$self->{'search'},"' binary";
+         chomp $i;
+         chomp $s;
+         confess $self->{'index'}," binary is not SWISH++" unless ($i =~ m/^SWISH\+\+/);
+         confess $self->{'search'}," binary is not SWISH++" unless ($s =~ m/^SWISH\+\+/);
+         if ($i eq $s) {
+                 $self->{'version'} = $i;
+                 return 1;
+         } else  {
+                 carp "version difference: index is $i while search is $s";
+                 return;
+         }
+ }
+ =head2 index_document
+ Quick way to add simple data to index.
+   $i->index_document($key, $data);
+   $i->index_document( 42 => 'meaning of life' );
+ =cut
+ sub index_document {
+         my $self = shift;
+         my %doc = @_;
+         foreach my $id (keys %doc) {
+                 $self->_create_doc(
+                         path => $id,
+                         body => $doc{$id},
+                 );
+         }
+         return 1;
+ }
+ =head2 search
+ Search your index.
+   my @results = $i->search("swhish query");
+ Returns array with result IDs.
+ =cut
+ sub search {
+         my $self = shift;
+         my $query = shift || return;
+         $self->_close_index;
+         my @results;
+         # escape double quotes in query for shell
+         $query =~ s/"/\\"/g;
+         my $open_cmd = $self->{'search'}." -i ".$self->{'index_dir'}.'/index "'.$query.'" |';
+         print STDERR "## search $open_cmd\n" if ($self->{'debug'});
+         CORE::open(SEARCH, $open_cmd) || confess "can't start $open_cmd: $!";
+         while(<SEARCH>) {
+                 next if (/^#/);
+                 chomp;
+                 print STDERR "## $_\n" if ($self->{'debug'});
+                 my ($rank,$path,$size,$title) = split(/ /,$_,4);
+                 push @results, {
+                         rank => $rank,
+                         path => $path,
+                         size => $size,
+                         title => $title,
+                 }
+         }
+         close(SEARCH) || confess "can't close search";
+         #print STDERR "## results: ",Dump(@results),"\n" if ($self->{'debug'});
+         return @results;
+ }
+ =head1 PRIVATE METHODS
+ Private methods implement internals for creating temporary file needed for
+ swish++. You should have no need to call them directly, and they are here
+ just to have documentation.
+ =head2 _init_index
+ Create temporary directory in which files for indexing will be created and
+ start index process.
+   my $i->_init_index || die "can't start indexer";
+ =cut
+ sub _init_index {
+         my $self = shift;
+         $self->{'tmp_dir'} = tempdir( CLEANUP => 1 ) || confess "can't create temporary directory: $!";
+         my $opt = "-v 4";
+         my $open_cmd = '| '.$self->{'index'}.' '.$opt.' -e "html:*" -i '.$self->{'index_dir'}.'/index -';
+         chdir $self->{'tmp_dir'} || confess "can't chdir to ".$self->{'tmp_dir'}.": $!";
+         CORE::open($self->{'index_fh'}, $open_cmd) || confess "can't start index with $open_cmd: $!";
+         return $self->{'index_fh'};
+ }
+ =head2 _create_doc
+ Create temporary file and pass it's name to swish++
+   $i->_create_doc(
+         path => 'path/to/store/in/index',
+         body => 'data to story in body tag',
+         meta => {
+                 'meta name' => 'data for this meta',
+                 'another' => 'again more data',
+         }
+   );
+ To delete document, just omit body and meta data.
+ =cut
+ sub _create_doc {
+         my $self = shift;
+         my $arg = {@_};
+         # open indexer if needed
+         $self->{'index_fh'} ||= $self->_init_index;
+         my $path = $self->{'tmp_dir'} || confess "no tmp_dir?";
+         CORE::open(TMP, '>', $arg->{'path'}) || die "can't create temp file ".$arg->{'path'}.": $!";
+         print TMP '<html>';
+         if ($arg->{'meta'}) {
+                 confess "not yet implemented";
+         }
+         print TMP '<body>' . ($arg->{'body'} || '') . '</body></html>';
+         close(TMP) || confess "can't close tmp file ".$arg->{'path'}.": $!";
+         print { $self->{'index_fh'} } $arg->{'path'}."\n";
+ }
+ =head2 _close_index
+ Close index after indexing.
+   $i->_close_index;
+ You have to close index before searching.
+ =cut
+ sub _close_index {
+         my $self = shift;
+         return unless ($self->{'index_fh'});
+         print STDERR "## close index\n" if ($self->{'debug'});
+         close($self->{'index_fh'});
+         undef $self->{'index_fh'};
+ }
 ;
  __END__
-Line 69 
 __END__
+Line 302 
 __END__
  None by default.
- =head1 SEE ALSO
+ =head1 RELATED
+ =head2 Debian
- Mention other useful documentation such as the documentation of
+ Debian version of swish++ is often old (version 5 at moment of this writing
- related modules or operating system documentation (such as man pages
+ while version 6 is available in source code), so this module by default
- in UNIX), or any relevant external documentation such as RFCs or
+ uses executable names B<index> and B<search> for self-compiled version
- standards.
+ instead of one from Debian package. See L<open> how to specify Debian
+ default binaries B<index++> and B<search++>.
+ =head2 SWISH++
+ Aside from very good rewrite in C++, SWISH++ is fatster because it has
+ claver heuristics about which data in input files are words to index and
+ which are not. It's based on English language and might be best choice if
+ you plan to install large amount of long text documents.
+ However, if you plan to index all data from structured storage (e.g. RDBMS)
+ you might want B<all> words from data to end up in index as opposed to just
+ those which look like English words. This is especially important if you
+ don't plan to index English texts with this module.
+ With distribution build versions of SWISH++ you might have problems with
+ disepearing words. To overcome this problem, you will have to compile and
+ configure SWISH++ yourself (because language characteristics are
+ compilation-time option).
+ Compilation of SWISH++ is easy process well described on project's web
+ pages. To see my very relaxed sample configuration take a look at C<swish++>
+ directory included in distribution.
- If you have a mailing list set up for your module, mention it here.
+ =head1 SEE ALSO
- If you have a web site set up for your module, mention it here.
+ C<swish++> web site L<http://homepage.mac.com/pauljlucas/software/swish/>
  =head1 AUTHOR
- Dobrica Pavlinusic, E<lt>dpavlin@E<gt>
+ Dobrica Pavlinusic, E<lt>dpavlin@rot13.orgE<gt>
  =head1 COPYRIGHT AND LICENSE

 Legend:



Removed from v.1
 


changed lines


 
Added in v.8
 Legend:



Removed from v.1
 


changed lines


 
Added in v.8
-Removed from v.1
+Added in v.8

	ViewVC Help
Powered by ViewVC 1.1.26