NAME

Text::Phonetic - A base class for phonetic algorithms

SYNOPSIS

use Text::Phonetic::Metaphone;

      my $phonetic = Text::Phonetic::Metaphone->new();
      $encoded_string = $phonetic->encode($string);
      @encoded_list = $phonetic->encode(@list);
  
      my $same = $phonetic->compare($string1,$string2);

Or

      use Text::Phonetic;
      my $phonetic = Text::Phonetic->load( algorithm => 'Phonix' );
      $encoded_string = $phonetic->encode($string);

This module provides an easy and convinient way to encode names with various phonetic algorithms. It acts as a wrapper arround other phonetic algorithm modules like Text::Metaphone, Text::DoubleMetaphone, Text::Soundex and also implements some other algorithms such as Text::Phonetic::DaitchMokotoff, Text::Phonetic::Koeln, Text::Phonetic::Phonem and Text::Phonetic::Phonix.

The module can easily be subclassed.

DESCRIPTION
Constructors
new
$obj = Text::Phonetic::SUBCLASS->new(%PARAMETERS)

You can pass arbitrary attributes to the constructor. The only global attribute is "unidecode" which defaults to 1 if not set. This attribute controlls if non-latin characters should be transliterated to A-Z (see also Text::Unidecode).

Additional attributes may be defined by the various implementation classes.

load
$obj = Text::Phonetic->new(algorithm => $algorithm, %PARAMETERS)

Alternative constructor which also loads the requested algorithm subclass.

Methods
encode

     $RETURN_STRING = $obj->encode($STRING);
     OR
     @RETURN_LIST = $obj->encode(@LIST);
     OR
     $RETURN_LIST_REF = $obj->encode(@LIST);

Encodes the given string or list of strings. Returns a single value, array or array reference depending on the caller context and parameters.

Returns undef on an empty/undefined/whitespace only string.

compare
$RETURN_CODE = $obj->compare($STRING1,$STRING2);

The return code is an integer between 100 and 0 indicating the likelihood that the to results are the same. 100 means that the strings are completely identical. 99 means that the strings match after all non-latin characters have been transliterated. Values in between 98 and 1 usually mean that the given strings match. 0 means that the used alogorithm couldn't match the two strings at all. "compare" is a shortcut to the "$obj->docompare($CODE1,$CODE2)" method.

Class Methods
available_algorithms
my @available = Text::Phonetic->available_algorithms;

Returns a list of all available/installed algorithms

SUBLCASSING

You can easily subclass Text::Phonetic and add your own phonetic algorithm. All subclasses must use Text::Phonetic as their base class, reside in the Text::Phonetic namespace, and implement the following

methods

doencode

$RESULT = $obj->doencode($STRING);

This method does the actual encoding. It should return either a string or an array reference.

docompare

$RETURN_STRING = $obj->docompare($RESULT1,$RESULT2);

If your "doencode" method doesn't return a single scalar value you also might need to implement a comparison method. It takes two results as returned by "doencode" and returns an integer value between 98 and 0 (see "compare").

predicates
Third party modules can be marked as predicates by adding the "predicates" method whick should return al list of package names. All predicates will be loaded if installed. If missing an exception will be thrown.

Object structure
Text::Phonetic uses Moose to declare attributes.

Helper class methods
isinlist

       Text::Phonetic::isinlist($STRING,@LIST);
       OR
       Text::Phonetic::isinlist($STRING,$LIST_REF);

      Returns a true value if $STRING is in the supplied list. Otherwise
      returns false.

comparelist

Text::Phonetic::comparelist($LIST1_REF,$LIST2_REF);

      Compares the two arrays and returns true if at least one element is
      equal (ignoring the position) in both lists.

Example class

     package Text::Phonetic::MyAlgorithm;
     use Moose;
     extends qw(Text::Phonetic);
 
     has someattribute => (
        is  => 'rw',
        isa => 'Str',
     );
 
     __PACKAGE__->meta->make_immutable;
 
     sub doencode {
         my ($self,$string) = @;
         # Do something
         return $phoneticrepresentation;
     }
     1;

SEE ALSO

DBIx::Class::PhoneticSearch (Build phonetic indices via DBIx::Class), Text::Phonetic::VideoGame (Phonetic encoding for video game titles)

SUPPORT

Please report any bugs or feature requests to "text-phonetic@rt.cpan.org", or through the web interface at <http://rt.cpan.org/Public/Bug/Report.html?Queue=Text::Phonetic>. I will be notified, and then you'll automatically be notified of progress on your report as I make changes.

AUTHOR

        Maroš Kollár
        CPAN ID: MAROS
        maros [at] k-1.com
        http://www.k-1.com

COPYRIGHT

Text::Phonetic is Copyright (c) 2006,2007 Maroš. Kollár.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.