Author image Maroš Kollár
and 1 contributors


Text::Phonetic - A base class for phonetic algorithms


  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);


  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 around 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.

This module can easily be subclassed.




 $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 controls if non-latin characters should be transliterated to A-Z (see also Text::Unidecode).

Additional attributes may be defined by the various implementation classes.


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

Alternative constructor which also loads the requested algorithm subclass.



 $RETURN_STRING = $obj->encode($STRING);
 @RETURN_LIST = $obj->encode(@LIST);
 $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.


 $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


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

Returns a list of all available/installed algorithms


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:


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

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


 $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 "compare").


Third party modules can be marked as predicates by adding the _predicates method which 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 Moo to declare attributes.

Helper class methods



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 Moo;
 extends qw(Text::Phonetic);

 has someattribute => (
    is  => 'rw',

 sub _do_encode {
     my ($self,$string) = @_;
     # Do something
     return $phonetic_representation;

 no Moo;


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


Please report any bugs or feature requests to, or through the web interface at I will be notified, and then you'll automatically be notified of progress on your report as I make changes.


    Maroš Kollár
    maros [at]


Text::Phonetic is Copyright (c) 2006-2012 Maroš Kollár -


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