package Fuzzy::Matcher;
use strict;
use warnings;
use Carp qw(croak confess);
use vars qw/$VERSION/;
$VERSION=0.01;

# This is a base class for fuzzy matchers to inherit.
# Its where stuff that will be common to all matchers
# is located. It also defines the interface that all
# matchers will have to follow.

# Constructor CLASS->new($fuzz,$strlen,$words);
#
# Takes the amount of fuzz to use for matching
# and the length of the strings to be matched.
#
# Should not be overriden.
#

sub new {
  my $class  = shift;
  my $fuzz   = shift;
  my $strlen = shift;

  my $self=bless {
              fuzz   => $fuzz||0,
              strlen => $strlen,
          },$class;

  croak "Failed build!" unless $self;

  $self->_init(@_);
  return $self;
}

#
# $obj->_init()
#
# This is a hook for subclass to override without
# having to override the default object creation
# process. It is called in void context before the
# object is returned to the user with any args
# remaining after the default ($fuzz,$strlen)
#
# By default it is a No-Op.
#
sub _init { }

#
# $obj->fuzz_store($string)
#
# Store a string into the object for fuzzy matching
# later.
#
# Default behaviour is to build a hash of stored strings
# for dupe checking and a corresponding array of strings.
# The array is named fuzz_strings and the hash is named
# str_hash.
#
#

sub fuzz_store {
  my ($self,$str)=@_;
  push @{$self->{str_array}},$str
    unless $self->{str_hash}{$str}++;
}

#
# $obj->prepare($string)
#
# If necessary a subclass may define this sub so
# that any actions that need to occur after
# adding the words but before search starts.
#
# By default it deletes the str_hash entry from the object to
# preserve memory.
#

sub prepare {
  my ($self,$str)=@_;
  delete $self->{str_hash};
}

#
# $obj->fuzz_search($string)
#
# Search a string for results and return
# a reference to a list of matches. The list will be
# of triples so that the first match returns:
# ($match_ofs,$chars_diff,$string_matched)=@$ret;
#
#
# Must be overriden
#

sub fuzz_search {
  confess((caller(0))[3],"() method must be overriden in ".
           ref($_[0]));
}


1;
[download]