#
# $Id: Saryer.pm,v 1.10 2005/07/10 17:19:01 tsuchiya Exp $
#
# Search::Saryer
#
# /* Copyright: LGPL */

package Search::Saryer;

=head1 NAME

Search::Saryer - a perl interface of libsary

=head1 SYNOPSIS

  my $saryer = new Search::Saryer(filename=>'search.txt');
  print $saryer->grep($pattern)

=head1 CONSTRUCTOR

=over 4

=item new ( FILE )

=item new ( OPTIONS )

Create C<Search::Saryer> object.  If creation process was failed, it
returns undef.  These following options are avaiable.

=over 4

=item file

This option is used to set the target file name.

=item filename

This option is the alias of C<file>.

=item array

This option is used to set the array file name.  It can be omitted.

=item arrayfile

=item arrayfilename

These options are aliases of C<array>.

=back

If it is required to specify the array file name cleary, the following
expression can be used.

  Example:

    $sary = new Search::Saryer( file => "foo", array => "bar" );

=back

=head1 DESTRUCTOR

=over 4

=item destroy

Destruct C<Search::Saryer> object. It is automatically called by
destructor.  It is unnecessary that this function is called
explicitly.

=back

=head1 METHODS

=over 4

=item grep ( PATTERN, [IGNORE_CASE] )

Search for the PATTERN, and return the list of lines which include it.
When IGNORE_CASE is true, do case-insensitive search.

=item look ( PATTERN, [START_TAG, END_TAG, IGNORE_CASE] )

Search for the PATTERN, and return the list of regions which include
it.  Each of them is surrounded by START_TAG and END_TAG.  When
IGNORE_CASE is true, do case-insensitive search.

=back

=head1 LOW LEVEL APIS

=over 4

=item enable_cache

Enable the cache engine. Cache the search results and reuse them for
the same pattern later.

=item search ( PATTERN )

Search for the PATTERN, and return true if success.

=item icase_search ( PATTERN )

Do case-insensitive search for the PATTERN, and return true if
success.

=item get_next_line

=item get_next_context_lines

=item get_next_tagged_region ( START_TAG, END_TAG )

Get the next search result of search/icase_search.

=back

=head1 COPYRIGHT

LGPL

=cut

require Exporter;
require DynaLoader;
require 5.003;

use Carp;
use strict;
use vars qw/ @ISA @EXPORT_OK %EXPORT_TAGS $VERSION /;

@ISA = qw(Exporter DynaLoader);

@EXPORT_OK = qw();
%EXPORT_TAGS = (all => [qw()]);

$VERSION = '0.30';

bootstrap Search::Saryer $VERSION;

sub new {
    my( $proto, %args );
    if( @_ == 2 ){
	$proto = shift;
	$args{'filename'} = shift;
    } else {
	( $proto, %args ) = @_;
    }

    my $file  = $args{'filename'} || $args{'file'};
    my $array = $args{'arrayfile'} || $args{'array'} || "$file.ary";

    croak "No 'file' argument" unless $file;

    my $self = {};
    $self->{_sary_ptr} = perl_saryer_new($file,$array);
    if( $self->{_sary_ptr} ){
	# NOTE: Adhoc workaround to accept old-style constructor.
	$proto->isa(__PACKAGE__) ? bless $self, $proto : bless $self;
    } else {
	undef;
    }
}

sub destroy {
    my( $self ) = @_;
    perl_saryer_destroy($self->{_sary_ptr}) if defined $self->{_sary_ptr};
    delete $self->{_sary_ptr};
}

sub DESTROY {
    my( $self ) = @_;
    destroy($self);
}

sub enable_cache {
    my( $self ) = @_;
    perl_saryer_enable_cache($self->{_sary_ptr});
}

sub search {
    my( $self, $pattern ) = @_;
    perl_saryer_search($self->{_sary_ptr}, $pattern, length($pattern));
}

sub icase_search {
    my( $self, $pattern ) = @_;
    perl_saryer_icase_search($self->{_sary_ptr}, $pattern, length($pattern));
}

sub get_next_line {
    my( $self ) = @_;
    perl_saryer_get_next_line($self->{_sary_ptr});
}

sub get_next_context_lines {
    my( $self, $backward, $forward ) = @_;
    perl_saryer_get_next_context_lines($self->{_sary_ptr}, $backward, $forward);
}

sub get_next_tagged_region {
    my( $self, $start_tag, $end_tag ) = @_;
    perl_saryer_get_next_tagged_region($self->{_sary_ptr}, $start_tag, $end_tag);
}

sub sort_occurrences {
    my( $self ) = @_;
    perl_saryer_sort_occurrences($self->{_sary_ptr});
}

sub grep {
    my( $self, $pattern, $ignore_case ) = @_;
    &look( $self, $pattern, '', '', $ignore_case );
}

sub look {
    my( $self, $pattern, $start_tag, $end_tag, $ignore_case ) = @_;
    if( defined( $ignore_case ? &icase_search($self,$pattern) : &search($self,$pattern) ) ){
	&sort_occurrences($self);
	my( $line, @buf );
	if( $start_tag or $end_tag ){
	    while( defined( $line = &get_next_tagged_region($self,$start_tag,$end_tag||$start_tag)) ){
		push( @buf, $line );
	    }
	} else {
	    while( defined( $line = &get_next_line($self) ) ){
		push( @buf, $line );
	    }
	}
	@buf;
    } else {
	wantarray ? () : 0;
    }
}

1;