NAME

SWISH::Prog::Object - index Perl objects with Swish-e

SYNOPSIS

    package My::Object;
    use base qw( SWISH::Prog::Object );
    
    1;
    
    package My::Object::Doc;
    use base qw( SWISH::Prog::Object::Doc );
    
    sub url_filter
    {
        my $doc = shift;
        my $obj = $doc->obj;
        $doc->url( $obj->method_I_want_as_url );
    }
    
    1;
    
    package main;
    use Carp;
    
    my $indexer = My::Object->new(
        methods => [qw( foo bar something something_else )],
        class   => 'My::Class',
        title   => 'mytitle',
        url     => 'myurl',
        modtime => 'mylastmod'
    );
    
    my $data = my_func_for_fetching_data();
    
    # $data is either iterator or arrayref of objects
    $indexer->create( $data );

DESCRIPTION

SWISH::Prog::Object is a SWISH::Prog subclass designed for providing full-text search for your Perl objects with Swish-e.

Since SWISH::Prog::Object inherits from SWISH::Prog, read the SWISH::Prog docs first. Any overridden methods are documented here.

If it seems odd at first to think of indexing objects, consider the advantages:

sorting

Particularly for scalar method values, time for sorting objects by method value is greatly decreased thanks to Swish-e's pre-sorted properties.

SWISH::API::Object integration

If you use SWISH::API::Object, you can get a Storable-like freeze/thaw effect with SWISH::Prog::Object.

caching

If some methods in your objects take a long while to calculate values, but don't change often, you can use Swish-e to cache those values, similar to the Cache::* modules, but in a portable, fast index.

METHODS

new( class => classname, methods => array ref of method names to call )

Create new indexer object.

NOTE: The new() method simply inherits from SWISH::Prog, so any params valid for that method() are allowed here.

methods

The methods param takes an array ref of method names. Each method name will be called on each object in create(). Each method name will also be stored as a PropertyName in the Swish-e index, unless you explicitly pass a config param to new() that defines your PropertyNames.

If not specified, a simple symbol table lookup will be done on class and all non-built-in methods will be used by default.

class

The name of the class each object belongs to. The class value will be stored in the index itself for later use with SWISH::API::Object (or for your own amusement).

If not specified, defaults to SWISH::Prog::Object::Doc::Instance.

title

Which method to use as the swishtitle value. Defaults to title.

url

Which method to use as the swishdocpath value. Defaults to url.

modtime

Which method to use as the swishlastmodified value. Defaults to Perl built-in time().

serial_format

Which format to use in serialize(). Default is yaml. You can also use json. If you don't like either of those, subclass SWISH::Prog::Object and override serialize() to provide your own format.

init

Initialize object. This overrides SWISH::Prog init() base method.

init_indexer

Adds the PropertyNames for each of methods. The special PropertyNamesNoStripChars config option is used so that all whitespace etc is preserved verbatim.

Each method is also configured as a MetaName. A top level MetaName using the classname value is also configured.

create( data )

Index your objects.

data should either be an array ref of objects, or an iterator object with a next method. If data is an iterator, it will be used like:

 while( my $object = $data->next )
 {
     $indexer->method_to_index( $object );
 }
 

Returns number of objects indexed.

obj2xml( class, object, title )

Returns object as an XML string. obj2xml calls the serialize() method so if you want a serialization format other than the default, override serialize() in your subclass. See serialize().

serialize( object, method_name )

Returns a serialized (stringified) version of the return value of method_name. If the return value is already a scalar string (i.e., if ref() returns false) then the return value is returned untouched. Otherwise, the return value is serialized with either JSON or YAML, depending on how you configured serial_format in new().

If you subclass SWISH::Prog::Object, then you can (of course) return whatever serialized format you prefer.

obj_filter( object )

Override this method if you need to alter the object data prior to being indexed.

This method is called prior to title_filter() so all object data is affected.

NOTE: This is different from the obj() method in the ::Doc subclass. This obj_filter() gets called before the Doc object is created.

IMPORTANT: This method MUST return an object. It can either be the same object object that was passed in, or a different object altogether. An example might be if you took data from object and created a new object in a different class (or even the same one).

Example:

 sub obj_filter
 {
    my ($prog,$obj) = @_;
    
    my $newobj = SomeClass->new;
    $newobj->foo( $obj->bar );
    
    return $newobj; # MUST return an object. Need not be $obj
 }

title_filter( object )

Override this method if you do not provide a title param in new() or if you have no title method to call on object.

The return value of title_filter() will be used as the swishtitle for the object's virtual XML document.

REQUIREMENTS

SWISH::Prog, YAML::Syck, JSON::Syck

LIMITATIONS and BUGS

None known. Please point some out.

SEE ALSO

http://swish-e.org/docs/

SWISH::Prog, SWISH::API:Object

AUTHOR

Peter Karman, <perl@peknet.com>

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

COPYRIGHT AND LICENSE

Copyright 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::Prog

perl -MCPAN -e shell
install SWISH::Prog