Catalyst::Model::Search

[Peter Karman]

I see Catalyst::Model::Search on CPAN now. As the maintainer of
Catalyst::Model::SWISH, I'd love to get in on that namespace action. Is
Catalyst::Model::Search intentionally undocumented? Are there plans for a
formal API to which subclasses of Catalyst::Model::Search must adhere?

signed,
a search junkie

--
Peter Karman  .  peter@...  .  http://peknet.com/


_______________________________________________
List: Catalyst@...
Listinfo: http://lists.rawmode.org/mailman/listinfo/catalyst
Searchable archive: http://www.mail-archive.com/catalyst@.../
Dev site: http://dev.catalyst.perl.org/

[Jonathan Rockway]

Peter Karman wrote:
> I see Catalyst::Model::Search on CPAN now. As the maintainer of
> Catalyst::Model::SWISH, I'd love to get in on that namespace action. Is
> Catalyst::Model::Search intentionally undocumented? Are there plans for a
> formal API to which subclasses of Catalyst::Model::Search must adhere?
>  

People can upload whatever they want to CPAN for any reason with any
name :)  Please mail the maintainer directly and collaborate with him.
If there's something seriously wrong with the module (no docs for an
important namespace like "Search" is a good reason), please let the core
team know on the dev list, and we'll do what we can to make sure the
users of the module have the best experience possible.

Collaboration is the key.  Modules that one guy uploads to the CPAN on a
whim are rarely useful.

Finally, what do you envision for the ::Search namespace?  A common
interface to various search mechanisms?

Regards,
Jonathan Rockway



_______________________________________________
List: Catalyst@...
Listinfo: http://lists.rawmode.org/mailman/listinfo/catalyst
Searchable archive: http://www.mail-archive.com/catalyst@.../
Dev site: http://dev.catalyst.perl.org/

[Peter Karman]

On 09/21/2007 09:39 AM, Jonathan Rockway wrote:

> Peter Karman wrote:
>> I see Catalyst::Model::Search on CPAN now. As the maintainer of
>> Catalyst::Model::SWISH, I'd love to get in on that namespace action. Is
>> Catalyst::Model::Search intentionally undocumented? Are there plans for a
>> formal API to which subclasses of Catalyst::Model::Search must adhere?
>>  
>
> People can upload whatever they want to CPAN for any reason with any
> name :)  Please mail the maintainer directly and collaborate with him.
> If there's something seriously wrong with the module (no docs for an
> important namespace like "Search" is a good reason), please let the core
> team know on the dev list, and we'll do what we can to make sure the
> users of the module have the best experience possible.

The C::M::Search package is under Marcus Ramberg's acct, though the author
listed in the POD is Andy Grundman. Since both those gentlemen are core devs, I
figured this list was as good as any, especially since the resulting
conversation might be of interest to all Catalyst users. But I'll write to them
directly as you suggest.

>
> Collaboration is the key.  Modules that one guy uploads to the CPAN on a
> whim are rarely useful.

amen. That's why I asked. :)

>
> Finally, what do you envision for the ::Search namespace?  A common
> interface to various search mechanisms?
>

Exactly. My original question, though, was more along the lines of "what do the
*maintainers* envision for the namespace." 'Search' is (as you point out) an
important namespace, and the idea of a uniform API for writing models seems
like a Good Idea. The lack of documentation was what piqued me.


--
Peter Karman  .  peter@...  .  http://peknet.com/


_______________________________________________
List: Catalyst@...
Listinfo: http://lists.rawmode.org/mailman/listinfo/catalyst
Searchable archive: http://www.mail-archive.com/catalyst@.../
Dev site: http://dev.catalyst.perl.org/

[Jonathan Rockway]

Peter Karman wrote:
> The C::M::Search package is under Marcus Ramberg's acct, though the author
> listed in the POD is Andy Grundman. Since both those gentlemen are core devs, I
> figured this list was as good as any, especially since the resulting
> conversation might be of interest to all Catalyst users. But I'll write to them
> directly as you suggest.

Ah, I should look at modules before I assume :)  I'm sure Marcus and
Andy have everything under control.  The dev list is still a fine place
to discuss your plans for extending the module, though.

Regards,
Jonathan Rockway



_______________________________________________
List: Catalyst@...
Listinfo: http://lists.rawmode.org/mailman/listinfo/catalyst
Searchable archive: http://www.mail-archive.com/catalyst@.../
Dev site: http://dev.catalyst.perl.org/

[Matt S Trout-2]

On Fri, Sep 21, 2007 at 10:00:14AM -0500, Peter Karman wrote:

>
>
> On 09/21/2007 09:39 AM, Jonathan Rockway wrote:
> > Peter Karman wrote:
> >> I see Catalyst::Model::Search on CPAN now. As the maintainer of
> >> Catalyst::Model::SWISH, I'd love to get in on that namespace action. Is
> >> Catalyst::Model::Search intentionally undocumented? Are there plans for a
> >> formal API to which subclasses of Catalyst::Model::Search must adhere?
> >>  
> >
> > People can upload whatever they want to CPAN for any reason with any
> > name :)  Please mail the maintainer directly and collaborate with him.
> > If there's something seriously wrong with the module (no docs for an
> > important namespace like "Search" is a good reason), please let the core
> > team know on the dev list, and we'll do what we can to make sure the
> > users of the module have the best experience possible.
>
> The C::M::Search package is under Marcus Ramberg's acct, though the author
> listed in the POD is Andy Grundman. Since both those gentlemen are core devs, I
> figured this list was as good as any, especially since the resulting
> conversation might be of interest to all Catalyst users. But I'll write to them
> directly as you suggest.

No, leave the discussion on here. John's just uninformed as usual.

--
      Matt S Trout       Need help with your Catalyst or DBIx::Class project?
   Technical Director                    http://www.shadowcat.co.uk/catalyst/
 Shadowcat Systems Ltd.  Want a managed development or deployment platform?
http://chainsawblues.vox.com/            http://www.shadowcat.co.uk/servers/

_______________________________________________
List: Catalyst@...
Listinfo: http://lists.rawmode.org/mailman/listinfo/catalyst
Searchable archive: http://www.mail-archive.com/catalyst@.../
Dev site: http://dev.catalyst.perl.org/

[Marcus Ramberg-3]

Catalyst::Model::Search is a quite old module which have been living
in Catalyst trunk for quite a while. It's being used by MojoMojo, and
it just happened to work, so I pushed it to CPAN so that MojoMojo
could depend on it. If anyone want to clean it up or document the
Search base class, patches are more than welcome.

Marcus

On 9/23/07, Matt S Trout <dbix-class@...> wrote:

> On Fri, Sep 21, 2007 at 10:00:14AM -0500, Peter Karman wrote:
> >
> >
> > On 09/21/2007 09:39 AM, Jonathan Rockway wrote:
> > > Peter Karman wrote:
> > >> I see Catalyst::Model::Search on CPAN now. As the maintainer of
> > >> Catalyst::Model::SWISH, I'd love to get in on that namespace action. Is
> > >> Catalyst::Model::Search intentionally undocumented? Are there plans for a
> > >> formal API to which subclasses of Catalyst::Model::Search must adhere?
> > >>
> > >
> > > People can upload whatever they want to CPAN for any reason with any
> > > name :)  Please mail the maintainer directly and collaborate with him.
> > > If there's something seriously wrong with the module (no docs for an
> > > important namespace like "Search" is a good reason), please let the core
> > > team know on the dev list, and we'll do what we can to make sure the
> > > users of the module have the best experience possible.
> >
> > The C::M::Search package is under Marcus Ramberg's acct, though the author
> > listed in the POD is Andy Grundman. Since both those gentlemen are core devs, I
> > figured this list was as good as any, especially since the resulting
> > conversation might be of interest to all Catalyst users. But I'll write to them
> > directly as you suggest.
>
> No, leave the discussion on here. John's just uninformed as usual.
>
> --
>       Matt S Trout       Need help with your Catalyst or DBIx::Class project?
>    Technical Director                    http://www.shadowcat.co.uk/catalyst/
>  Shadowcat Systems Ltd.  Want a managed development or deployment platform?
> http://chainsawblues.vox.com/            http://www.shadowcat.co.uk/servers/
>
> _______________________________________________
> List: Catalyst@...
> Listinfo: http://lists.rawmode.org/mailman/listinfo/catalyst
> Searchable archive: http://www.mail-archive.com/catalyst@.../
> Dev site: http://dev.catalyst.perl.org/
>

--
With regards
Marcus Ramberg

_______________________________________________
List: Catalyst@...
Listinfo: http://lists.rawmode.org/mailman/listinfo/catalyst
Searchable archive: http://www.mail-archive.com/catalyst@.../
Dev site: http://dev.catalyst.perl.org/

[Peter Karman]

On 09/23/2007 11:28 AM, Marcus Ramberg wrote:
> Catalyst::Model::Search is a quite old module which have been living
> in Catalyst trunk for quite a while. It's being used by MojoMojo, and
> it just happened to work, so I pushed it to CPAN so that MojoMojo
> could depend on it. If anyone want to clean it up or document the
> Search base class, patches are more than welcome.
>

See attached.

I'd like to also suggest that C::M::Search, C::M::Search::Results and
C::M::Search::Item be de-coupled from all the Lucene and Plucene classes that
are currently bundled with them. That way someone could install C::M::Search
and get all they need to implement a new subclass, without also needing to
satisfy all the Plucene dependencies.

cheers,
pek

--
Peter Karman  .  peter@...  .  http://peknet.com/


--- Search.pm.orig 2007-09-24 10:33:51.534326000 -0500
+++ Search.pm 2007-09-24 10:56:49.088527000 -0500
@@ -4,69 +4,151 @@
 use NEXT;
 use base qw/Catalyst::Base/;
 
-our $VERSION = '0.01';
+our $VERSION = '0.02';
 
-sub new {
+sub new {
     my ( $self, $c ) = @_;
-
-    return $self->NEXT::new( $c );
+    $self->init($c);
+    return $self->NEXT::new($c);
 }
 
 sub init {
     my $self = shift;
-    
+    my $c    = shift;
+
     Catalyst::Exception->throw(
-        message => ( ref $self || $self ) . ' does not implement init()'
-    );
+        message => ( ref $self || $self ) . ' does not implement init()' );
 }
 
 sub add {
     my $self = shift;
-    
+    my $data = shift;
+
     Catalyst::Exception->throw(
-        message => ( ref $self || $self ) . ' does not implement add()'
-    );
+        message => ( ref $self || $self ) . ' does not implement add()' );
 }
 
 sub update {
     my $self = shift;
-    
+    my $data = shift;
+
     Catalyst::Exception->throw(
-        message => ( ref $self || $self ) . ' does not implement update()'
-    );
+        message => ( ref $self || $self ) . ' does not implement update()' );
 }
 
 sub remove {
     my $self = shift;
-    
+    my $data = shift;
+
     Catalyst::Exception->throw(
-        message => ( ref $self || $self ) . ' does not implement remove()'
-    );
+        message => ( ref $self || $self ) . ' does not implement remove()' );
 }
 
 sub query {
-    my $self = shift;
-    
+    my $self  = shift;
+    my $query = shift;
+
     Catalyst::Exception->throw(
-        message => ( ref $self || $self ) . ' does not implement query()'
-    );
+        message => ( ref $self || $self ) . ' does not implement query()' );
 }
 
 sub is_indexed {
     my $self = shift;
-    
-    Catalyst::Exception->throw(
-        message => ( ref $self || $self ) . ' does not implement is_indexed()'
-    );
+    my $key  = shift;
+
+    Catalyst::Exception->throw( message => ( ref $self || $self )
+            . ' does not implement is_indexed()' );
 }
 
 sub optimize {
     my $self = shift;
-    
-    Catalyst::Exception->throw(
-        message => ( ref $self || $self ) . ' does not implement optimize()'
-    );
+
+    Catalyst::Exception->throw( message => ( ref $self || $self )
+            . ' does not implement optimize()' );
 }
 
 1;
 __END__
+
+
+=head1 NAME
+
+Catalyst::Model::Search - base class for Catalyst search models
+
+=head1 SYNOPSIS
+
+ package Catalyst::Model::MySearchApp;
+ use base qw(Catalyst::Model::Search);
+
+ # must implement all the following methods
+ sub init       {}
+ sub add        {}
+ sub update     {}
+ sub remove     {}
+ sub query      {}
+ sub is_indexed {}
+ sub optimize   {}
+
+=head1 DESCRIPTION
+
+Catalyst::Model::Search is a base class for providing full-text search
+to a Catalyst application. The premise is that existing search projects
+can be integrated with Catalyst's Model framework using a common API, allowing
+you to swap in Xapian or KinoSearch or Plucene or Swish-e or
+I<YourSearchAppHere> without needing to change any Controller or View code.
+
+=head1 METHODS
+
+The following methods are implemented. Those methods
+that must be overridden in your subclass are marked as such.
+
+=head2 new
+
+The basic boilerplate new() required by Catalyst::Model subclasses.
+The init() method is called by new().
+
+=head2 init
+
+Setup your search indexes or any other initialization required.
+B<This method must be overridden.>
+
+=head2 add( I<data> )
+
+Add I<data> to an index.
+
+=head2 update( I<data> )
+
+Update I<data> in an index.
+
+=head2 remove( I<data> )
+
+Remove I<data> from an index.
+
+=head2 query ( I<query> )
+
+Search an index for I<query>. In scalar context should return
+a Catalyst::Model::Search::Results object. In array context should
+return the value of a Results object's get_items() method.
+
+=head2 is_indexed( I<key> )
+
+Test the index for the presence of a record identified by I<key>
+Returns true if the record is in the index.
+
+=head2 optimize
+
+Perform optimizing magic on the index.
+
+=head1 AUTHOR
+
+Andy Grundman, <andy@...>
+Marcus Ramberg, <mramberg@...>
+
+=head1 COPYRIGHT
+
+This program is free software, you can redistribute it and/or modify it under
+the same terms as Perl itself.
+
+=cut
+
+

_______________________________________________
List: Catalyst@...
Listinfo: http://lists.rawmode.org/mailman/listinfo/catalyst
Searchable archive: http://www.mail-archive.com/catalyst@.../
Dev site: http://dev.catalyst.perl.org/

[Peter Karman]

On 09/24/2007 11:02 AM, Peter Karman wrote:

>
> On 09/23/2007 11:28 AM, Marcus Ramberg wrote:
>> Catalyst::Model::Search is a quite old module which have been living
>> in Catalyst trunk for quite a while. It's being used by MojoMojo, and
>> it just happened to work, so I pushed it to CPAN so that MojoMojo
>> could depend on it. If anyone want to clean it up or document the
>> Search base class, patches are more than welcome.
>>
>
> See attached.
>

oops. Forgot to include the 'required' boilerplate.

new version attached.
--
Peter Karman  .  peter@...  .  http://peknet.com/


--- Search.pm.orig 2007-09-24 10:33:51.534326000 -0500
+++ Search.pm 2007-09-24 11:16:11.646096000 -0500
@@ -4,69 +4,157 @@
 use NEXT;
 use base qw/Catalyst::Base/;
 
-our $VERSION = '0.01';
+our $VERSION = '0.02';
 
-sub new {
+sub new {
     my ( $self, $c ) = @_;
-
-    return $self->NEXT::new( $c );
+    $self->init($c);
+    return $self->NEXT::new($c);
 }
 
 sub init {
     my $self = shift;
-    
+    my $c    = shift;
+
     Catalyst::Exception->throw(
-        message => ( ref $self || $self ) . ' does not implement init()'
-    );
+        message => ( ref $self || $self ) . ' does not implement init()' );
 }
 
 sub add {
     my $self = shift;
-    
+    my $data = shift;
+
     Catalyst::Exception->throw(
-        message => ( ref $self || $self ) . ' does not implement add()'
-    );
+        message => ( ref $self || $self ) . ' does not implement add()' );
 }
 
 sub update {
     my $self = shift;
-    
+    my $data = shift;
+
     Catalyst::Exception->throw(
-        message => ( ref $self || $self ) . ' does not implement update()'
-    );
+        message => ( ref $self || $self ) . ' does not implement update()' );
 }
 
 sub remove {
     my $self = shift;
-    
+    my $data = shift;
+
     Catalyst::Exception->throw(
-        message => ( ref $self || $self ) . ' does not implement remove()'
-    );
+        message => ( ref $self || $self ) . ' does not implement remove()' );
 }
 
 sub query {
-    my $self = shift;
-    
+    my $self  = shift;
+    my $query = shift;
+
     Catalyst::Exception->throw(
-        message => ( ref $self || $self ) . ' does not implement query()'
-    );
+        message => ( ref $self || $self ) . ' does not implement query()' );
 }
 
 sub is_indexed {
     my $self = shift;
-    
-    Catalyst::Exception->throw(
-        message => ( ref $self || $self ) . ' does not implement is_indexed()'
-    );
+    my $key  = shift;
+
+    Catalyst::Exception->throw( message => ( ref $self || $self )
+            . ' does not implement is_indexed()' );
 }
 
 sub optimize {
     my $self = shift;
-    
-    Catalyst::Exception->throw(
-        message => ( ref $self || $self ) . ' does not implement optimize()'
-    );
+
+    Catalyst::Exception->throw( message => ( ref $self || $self )
+            . ' does not implement optimize()' );
 }
 
 1;
 __END__
+
+
+=head1 NAME
+
+Catalyst::Model::Search - base class for Catalyst search models
+
+=head1 SYNOPSIS
+
+ package Catalyst::Model::MySearchApp;
+ use base qw(Catalyst::Model::Search);
+
+ # must implement all the following methods
+ sub init       {}
+ sub add        {}
+ sub update     {}
+ sub remove     {}
+ sub query      {}
+ sub is_indexed {}
+ sub optimize   {}
+
+=head1 DESCRIPTION
+
+Catalyst::Model::Search is a base class for providing full-text search
+to a Catalyst application. The premise is that existing search projects
+can be integrated with Catalyst's Model framework using a common API, allowing
+you to swap in Xapian or KinoSearch or Plucene or Swish-e or
+I<YourSearchAppHere> without needing to change any Controller or View code.
+
+=head1 METHODS
+
+The following methods are implemented. Those methods
+that must be overridden in your subclass are marked as such.
+
+=head2 new
+
+The basic boilerplate new() required by Catalyst::Model subclasses.
+The init() method is called by new().
+
+=head2 init
+
+Setup your search indexes or any other initialization required.
+B<This method must be overridden.>
+
+=head2 add( I<data> )
+
+Add I<data> to an index.
+B<This method must be overridden.>
+
+=head2 update( I<data> )
+
+Update I<data> in an index.
+B<This method must be overridden.>
+
+=head2 remove( I<data> )
+
+Remove I<data> from an index.
+B<This method must be overridden.>
+
+=head2 query ( I<query> )
+
+Search an index for I<query>. In scalar context should return
+a Catalyst::Model::Search::Results object. In array context should
+return the value of a Results object's get_items() method.
+B<This method must be overridden.>
+
+=head2 is_indexed( I<key> )
+
+Test the index for the presence of a record identified by I<key>
+Returns true if the record is in the index.
+B<This method must be overridden.>
+
+=head2 optimize
+
+Perform optimizing magic on the index.
+B<This method must be overridden.>
+
+=head1 AUTHOR
+
+Andy Grundman, <andy@...>
+Marcus Ramberg, <mramberg@...>
+
+=head1 COPYRIGHT
+
+This program is free software, you can redistribute it and/or modify it under
+the same terms as Perl itself.
+
+=cut
+
+

_______________________________________________
List: Catalyst@...
Listinfo: http://lists.rawmode.org/mailman/listinfo/catalyst
Searchable archive: http://www.mail-archive.com/catalyst@.../
Dev site: http://dev.catalyst.perl.org/