The Perl and Raku Conference 2025: Greenville, South Carolina - June 27-29 Learn more

 / 
Text-Phonetic-2.09
River stage one • 2 direct dependents • 3 total dependents
/ Text::Phonetic

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

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

load


            

              
              
$obj = Text::Phonetic->load(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 "compare").

_predicates

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

_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 Moo;
extends qw(Text::Phonetic);
has someattribute => (
   is  => 'rw',
);
sub _do_encode {
    my ($self,$string) = @_;
    # Do something
    return $phonetic_representation;
}
__PACKAGE__->meta->make_immutable;
no Moo;
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-2012 Maroš Kollár - http://www.k-1.com

LICENCE

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