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


  # 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;
  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
  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!


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.


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


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.


 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.


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


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.


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.


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.


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.


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.


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.

Shortcut for new_search_object().


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




Peter Karman, <>

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


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.