SWISH-PlusPlus/trunk/PlusPlus.pm

package SWISH::PlusPlus;

use 5.008004;
use strict;
use warnings;

our $VERSION = '0.02';

use Carp;

=head1 NAME

SWISH::PlusPlus - Perl extension SWISH++

=head1 SYNOPSIS

  use SWISH::PlusPlus;
  blah blah blah

=head1 DESCRIPTION

This is perl module to use SWISH++ indexer by Paul J. Lucas. SWISH++ is
rewrite of swish-e in C++ which is extremly fast (thank to mmap), but without
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

=head2 open

Create new indexing object.

  my $i = SWISH::PlusPlus->open(
        index_dir => '/path/to/index',
        index => 'index++',
        search => 'search++',
  );

Options to open are following:

=over 5

=item C<index_dir>

Path to directory in which index will be created.

=item C<index>

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>.

=back

=cut

sub open {
        my $class = shift;
        my $self = {@_};
        bless($self, $class);

        foreach (qw(index_dir)) {
                croak "need $_" unless $self->{$_};
        }

        if (! -e $self->{'index_dir'}) {
                mkdir $self->{'index_dir'} || confess "can't create index ",$self->{'index'},": $!";
        }

        # default executables
        $self->{'index'} ||= 'index';
        $self->{'search'} ||= 'search';

        $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;
        }

}

1;
__END__

=head2 EXPORT

None by default.

=head1 RELATED

=head2 Debian

Debian version of swish++ is often old (version 5 at moment of this writing
while version 6 is available in source code), so this module by default
uses executable names B<index> and B<search> for self-compiled version
instead of one from Debian package. See L<open> how to specify Debian
default binaries B<index++> and B<search++>.

=head1 SEE ALSO

Mention other useful documentation such as the documentation of
related modules or operating system documentation (such as man pages
in UNIX), or any relevant external documentation such as RFCs or
standards.

If you have a mailing list set up for your module, mention it here.

If you have a web site set up for your module, mention it here.

=head1 AUTHOR

Dobrica Pavlinusic, E<lt>dpavlin@E<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2004 by Dobrica Pavlinusic

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.4 or,
at your option, any later version of Perl 5 you may have available.


=cut
1	package SWISH::PlusPlus;
2
3	use 5.008004;
4	use strict;
5	use warnings;
6
7	our $VERSION = '0.02';
8
9	use Carp;
10
11	=head1 NAME
12
13	SWISH::PlusPlus - Perl extension SWISH++
14
15	=head1 SYNOPSIS
16
17	use SWISH::PlusPlus;
18	blah blah blah
19
20	=head1 DESCRIPTION
21
22	This is perl module to use SWISH++ indexer by Paul J. Lucas. SWISH++ is
23	rewrite of swish-e in C++ which is extremly fast (thank to mmap), but without
24	support for properties (which this module tries to fix).
25
26	Implementation of this module is crafted after L<Plucene::Simple> and it
27	should be easy to replace Plucene with this module for increased
28	performance. However, this module is not plug-in replacement.
29
30	=head1 METHODS
31
32	=head2 open
33
34	Create new indexing object.
35
36	my $i = SWISH::PlusPlus->open(
37	index_dir => '/path/to/index',
38	index => 'index++',
39	search => 'search++',
40	);
41
42	Options to open are following:
43
44	=over 5
45
46	=item C<index_dir>
47
48	Path to directory in which index will be created.
49
50	=item C<index>
51
52	Full or partial path to SWISH++ index executable. By default, it's B<index>
53	for self-compiled version. If you use Debian GNU/Linux package specify
54	B<index++>. See C<Debian>.
55
56	=item C<search>
57
58	Full or partial path to SWISH++ search executable. By default, it's B<search>.
59
60	=back
61
62	=cut
63
64	sub open {
65	my $class = shift;
66	my $self = {@_};
67	bless($self, $class);
68
69	foreach (qw(index_dir)) {
70	croak "need $_" unless $self->{$_};
71	}
72
73	if (! -e $self->{'index_dir'}) {
74	mkdir $self->{'index_dir'} \|\| confess "can't create index ",$self->{'index'},": $!";
75	}
76
77	# default executables
78	$self->{'index'} \|\|= 'index';
79	$self->{'search'} \|\|= 'search';
80
81	$self ? return $self : return undef;
82	}
83
84
85	=head2 check_bin
86
87	Check if swish++ binaries specified in L<open> are available and verify
88	version signature.
89
90	if ($i->check_bin) {
91	print "swish++ binaries found\n";
92	};
93
94	It will also setup property
95
96	$i->{'version'}
97
98	which you can examine to see version.
99
100	=cut
101
102	sub check_bin {
103	my $self = shift;
104
105	my $i = `$self->{'index'} -V 2>&1` \|\| confess "can't find '",$self->{'index'},"' binary";
106	my $s = `$self->{'search'} -V 2>&1` \|\| confess "can't find '",$self->{'search'},"' binary";
107
108	chomp $i;
109	chomp $s;
110
111	confess $self->{'index'}," binary is not SWISH++" unless ($i =~ m/^SWISH\+\+/);
112	confess $self->{'search'}," binary is not SWISH++" unless ($s =~ m/^SWISH\+\+/);
113
114	if ($i eq $s) {
115	$self->{'version'} = $i;
116	return 1;
117	} else {
118	carp "version difference: index is $i while search is $s";
119	return;
120	}
121
122	}
123
124	1;
125	__END__
126
127	=head2 EXPORT
128
129	None by default.
130
131	=head1 RELATED
132
133	=head2 Debian
134
135	Debian version of swish++ is often old (version 5 at moment of this writing
136	while version 6 is available in source code), so this module by default
137	uses executable names B<index> and B<search> for self-compiled version
138	instead of one from Debian package. See L<open> how to specify Debian
139	default binaries B<index++> and B<search++>.
140
141	=head1 SEE ALSO
142
143	Mention other useful documentation such as the documentation of
144	related modules or operating system documentation (such as man pages
145	in UNIX), or any relevant external documentation such as RFCs or
146	standards.
147
148	If you have a mailing list set up for your module, mention it here.
149
150	If you have a web site set up for your module, mention it here.
151
152	=head1 AUTHOR
153
154	Dobrica Pavlinusic, E<lt>dpavlin@E<gt>
155
156	=head1 COPYRIGHT AND LICENSE
157
158	Copyright (C) 2004 by Dobrica Pavlinusic
159
160	This library is free software; you can redistribute it and/or modify
161	it under the same terms as Perl itself, either Perl version 5.8.4 or,
162	at your option, any later version of Perl 5 you may have available.
163
164
165	=cut