# 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](http://search.cpan.org/search?mode=module&query=Text::Metaphone), [Text::DoubleMetaphone](http://search.cpan.org/search?mode=module&query=Text::DoubleMetaphone), [Text::Soundex](http://search.cpan.org/search?mode=module&query=Text::Soundex)
and also implements some other algorithms such as 
[Text::Phonetic::DaitchMokotoff](http://search.cpan.org/search?mode=module&query=Text::Phonetic::DaitchMokotoff), [Text::Phonetic::Koeln](http://search.cpan.org/search?mode=module&query=Text::Phonetic::Koeln),
[Text::Phonetic::Phonem](http://search.cpan.org/search?mode=module&query=Text::Phonetic::Phonem) and [Text::Phonetic::Phonix](http://search.cpan.org/search?mode=module&query=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](http://search.cpan.org/search?mode=module&query=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->_do_compare($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:

## _do_encode

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

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

## _do_compare

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

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

## Object structure

Text::Phonetic uses [Moose](http://search.cpan.org/search?mode=module&query=Moose) to declare attributes.

## Helper class methods

- _is_inlist

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

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

- _compare_list

 Text::Phonetic::_compare_list($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 _do_encode {
     my ($self,$string) = @_;
     # Do something
     return $phonetic_representation;
 }
 1;

# SEE ALSO

[DBIx::Class::PhoneticSearch](http://search.cpan.org/search?mode=module&query=DBIx::Class::PhoneticSearch) (Build phonetic indices via DBIx::Class),
[Text::Phonetic::VideoGame](http://search.cpan.org/search?mode=module&query=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.