NAME

String::CaseProfile - Get/Set the letter case profile of a string

VERSION

Version 0.05 - February 3, 2008

SYNOPSIS

use String::CaseProfile qw(get_profile set_profile copy_profile);

my $reference_string = 'Some reference string';
my $string = 'sample string';

# Typical, single-line usage
my $target_string = set_profile($string, get_profile($reference_string));

# Alternatively, you can use the 'copy_profile' convenience function:
my $target_string = copy_profile(
                                    from => $reference_string,
                                    to   => $string,
                                );

# Get the profile of a string, access the details, 
# and apply it to another string
my %ref_profile = get_profile($reference_string);

my $string_type = $ref_profile{string_type};
my $word        = $ref_profile{words}[2]->{word}; # third word
my $word_type   = $ref_profile{words}[2]->{type};

my $new_string  = set_profile($string, %ref_profile);

# Use custom profiles
my %profile1 = ( string_type => '1st_uc' );
$new_string  = set_profile($string, %profile1);

my %profile2 = ( string_type => 'all_lc', force_change => 1 );
$new_string  = set_profile($string, %profile2);

my %profile3 = (
                custom => {
                            default => 'all_lc',
                            all_uc  => '1st_uc',
                            index   => {
                                        3 => '1st_uc',
                                        5 => 'all_lc',
                                       },
                           }
                );
$new_string  = set_profile($string, %profile3);

DESCRIPTION

This module provides a convenient way of handling the letter case conversion of sentences/phrases/chunks in machine translation, case-sensitive search and replace, and other text processing applications.

String::CaseProfile contains three functions:

get_profile determines the letter case profile of a string.

set_profile applies a letter case profile to a string; you can apply a profile determined by get_profile, or you can create your own custom profile.

copy_profile gets the profile of a string and applies it to another string in a single step.

These functions are Unicode-aware and support text in most European languages. You must feed them utf8-encoded strings.

get_profile and set_profile use the following identifiers to classify word and string types according to their case:

• all_lc

  In word context, it means that all the letters are lowercase. In string context, it means that every word is of all_lc type.

• all_uc

  In word context, it means that all the letters are uppercase. In string context, it means that every word is of all_uc type.

• 1st_uc

  In word context, it means that the first letter is uppercase, and the other letters are lowercase. In string context, it means that the type of the first word is 1st_uc, and the type of the other words is all_lc.

• other

  Undefined type (e.g. a CamelCase code identifier in word context, or a string containing several alternate types in string context.)

FUNCTIONS

get_profile($string)

Returns a hash containing the profile details for $string. The string provided must be encoded as utf8. The hash keys are the following:

• string_type

  Scalar containing the string type, if it can be determined; otherwise, its value is 'other'.

• words

  Reference to an array containing a hash for every word in the string. Each hash has two keys: word and type.

set_profile($string, %profile)

Applies %profile to $string and returns a new string. $string must be encoded as utf8. The profile configuration parameters (hash keys) are the following:

• string_type

  You can specify one of the string types mentioned above (except 'other') as the type that should be applied to the string.

• custom

  As an alternative, you can define a custom profile as a reference to a hash in which you can specify types for specific word (zero-based) positions, conversions for the types mentioned above, and you can define a 'default' type for the words for which none of the preceding rules apply. The order of evaluation is 1) index, 2) type conversion, 3) default type. For more information, see the examples below.

• force_change

  By default, set_profile will ignore words with type 'other' when applying the profile. You can use this boolean parameter to enable changing this kind of words.

copy_profile(from => $source, to => $target)

Gets the profile of $source and applies it to $target. Returns the resulting string.

EXAMPLES

use String::CaseProfile qw(
                            get_profile
                            set_profile
                            copy_profile
                           );
use Encode;

my @strings = (
                'Entorno de tiempo de ejecución',
                'è un linguaggio veloce',
                'langages dérivés du C',
              );

# Encode strings as utf-8
my @samples = map { decode('iso-8859-1', $_) } @strings;

my $new_string;


# EXAMPLE 1: Get the profile of a string

my %profile = get_profile($samples[0]);

print "$profile{string_type}\n";   # prints '1st_uc'
my @types = $profile{string_type}; # 1st_uc all_lc all_lc all_lc all_lc
my @words = $profile{words};       # returns an array of hashes



# EXAMPLE 2: Get the profile of a string and apply it to another string

my $ref_string1 = 'REFERENCE STRING';
my $ref_string2 = 'Another reference string';

$new_string = set_profile( $samples[1], get_profile($ref_string1) );
# The current value of $new_string is 'È UN LINGUAGGIO VELOCE'

$new_string = set_profile( $samples[1], get_profile($ref_string2) );
# Now it's 'È un linguaggio veloce'

# Alternative, using copy_profile
$new_string = copy_profile( from => $ref_string1, to => $samples[1] );
$new_string = copy_profile( from => $ref_string2, to => $samples[1] );


# EXAMPLE 3: Change a string using several custom profiles

my %profile1 = ( string_type  => 'all_uc' );
$new_string = set_profile( $samples[2], %profile1 );
# $new_string is 'LANGAGES DÉRIVÉS DU C'

my %profile2 = ( string_type => 'all_lc', force_change => 1 );
$new_string = set_profile( $samples[2], %profile2 );
# $new_string is 'langages dérivés du c'

my %profile3 = (
                custom  => {
                            default => 'all_lc',
                            index   => { '1'  => 'all_uc' }, # 2nd word
                           }
               );
$new_string = set_profile( $samples[2], %profile3 );
# $new_string is 'langages DÉRIVÉS du C'

my %profile4 = ( custom => { all_lc => '1st_uc' } );
$new_string = set_profile( $samples[2], %profile4 );
# $new_string is 'Langages Dérivés Du C'

EXPORT

None by default.

LIMITATIONS

Since String::CaseProfile is a multilanguage module and title case is a language-dependent feature, the functions provided don't handle title case capitalization (in the See Also section you will find further information on modules you can use for this task). Anyway, you can use the profile information provided by get_profile to implement a solution for your particular case.

For the German language, which has a peculiar letter case rule consisting in capitalizing every noun, these functions may have a limited utility, but you can still use the profile information to create and apply customs profiles.

SEE ALSO

Lingua::EN::Titlecase

Text::Capitalize

ACKNOWLEDGEMENTS

Many thanks to Xavier Noria for wise suggestions.

AUTHOR

Enrique Nell, <perl_nell@telefonica.net>

COPYRIGHT AND LICENSE

Copyright (C) 2007-2008 by Enrique Nell.

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

cpanm String::CaseProfile

perl -MCPAN -e shell
install String::CaseProfile