NAME

SWISH::API::More - do more with the SWISH::API

SYNOPSIS

  # drop-in replacement for SWISH::API
  my $swish = SWISH::API::More->new('my/index.swish-e');
  
  # or subclass to do More
  package My::SwishAPI;
  use base qw( SWISH::API::More );
  
  sub init
  {
    my $self = shift;
    $self->SUPER::init(@_);    
  }
  
  sub do_something
  {
    my $self = shift;   # My::SwishAPI object
  }
  
  sub new_search_object
  {
    my $self = shift;
    my $swish_handle = $self->handle;
    
    # do something with $swish_handle
    # but make sure to return from superclass
    $self->SUPER::new_search_object(@_);
  }
  
  1;
    
  package main;
  
  my $swish = My::SwishAPI->new(
                indexes => [qw( path/to/index1 path/to/index2 )],
                log     => $a_filehandle
                );
                
  $swish->logger("opened a new swish-e handle");
  
  # use $swish just like you would with SWISH::API->new object.
  # only do More!
  

DESCRIPTION

SWISH::API::More is a base class for subclassing and extending SWISH::API. Since SWISH::API is just a thin Perl XS wrapper around the Swish-e C library, which isn't friendly for subclassing in a traditional Perlish way, SWISH::API::More allows you to subclass SWISH::API like you would a native Perl module.

Versions prior to 0.03 used ugly Symbol table mangling to achieve More magic. This was not thread-safe, nor played nicely with multiple subclasses using the same Perl process. Version 0.03 was a complete re-write.

REQUIREMENTS

SWISH::API, Class::Accessor::Fast, Class::Inspector, Class::ISA

METHODS

new( @args )

Creates a new SWISH::API::More object.

args may be either a string of space-separated index names (like SWISH::API uses) or key/value pairs.

Example:

 my $swish = SWISH::API::More->new(
            indexes => [qw( my/index )],
            log   => *{STDERR},     # logger will print to stderr
            );
            

You can use the returned $swish object just like a SWISH::API object. But you can also use the defined methods in SWISH::API::More -- or create your own by subclassing (see SYNOPSIS).

The new() method does a bunch of class magic to make sure the correct subclasses are called. You can usually trust this to Just Work.

You probably don't want to override new() in a subclass. See init() instead.

init

If you subclass SWISH::API::More you'll likely want to override init(). See SWISH::API::Stat for an example.

init() is called internally by new() every time you create a new object. Override init() not new().

handle

Returns the SWISH::API handle. The handle is simply a SWISH::API object. So this:

  my $s = SWISH::API->new;
  

and this:

  my $s = SWISH::API::More->new->handle;
  

give you the same thing. Except SWISH::API::More gives you More.

indexes

Get/set the indexes to which you connect with handle(). indexes() contains an arrayref only. The SWISH::API-style space-separated string feature in new() is stored as an arrayref internally and that's what indexes() returns.

log

Get/set the filehandle that logger() prints to. Defaults to STDERR. Set to 0 to disable the default (but then don't expect logger() to work...).

logger( msg )

Will print msg to the filehandle set in log(). If log() is false, logger() will just return and ignore msg.

debug

Get/set the debugging flag. Default is 0 (off).

die_on_error([ error_name ])

Convenience wrapper around the SWISH::API error handling methods. Will die() with the last error messages if error_name method returns true. error_name defaults to 'error'. Possible values include 'critical_error'. See SWISH::API.

register

This is a reserved accessor for use by subclasses that might want to create subclasses during runtime. If you get that deeply into the code that you think you might want to use register(), contact the author. Otherwise, just avoid creating a method called register in your subclasses of SWISH::API::More and you'll not step on any toes you didn't mean to step on.

setup

This method is called for every subclass during new(). It is intended to run only once per process. See the source code for how it is used. It is documented here for the same reason register() is: it's a reserved method that you don't want to override (accidentally or not) without knowing what you're doing.

search

Shortcut for new_search_object().

EXAMPLES

See the SWISH::API::Stat module for a working example.

SEE ALSO

http://swish-e.org/

SWISH::API, SWISH::API::Stat, SWISH::API::Object

AUTHOR

Peter Karman, <karman@cpan.org>

Thanks to Atomic Learning for supporting some of the development of this module.

COPYRIGHT AND LICENSE

Copyright (C) 2006 by Peter Karman

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

cpanm SWISH::API::More

perl -MCPAN -e shell
install SWISH::API::More