/ 
Lingua-ES-Numeros-0.03
River stage one • 1 direct dependent • 2 total dependents
/ Lingua::ES::Numeros

NAME

Lingua::ES::Numeros - Translates numbers to spanish text

SYNOPSIS

use Lingua::ES::Numeros

$obj = new Lingua::ES::Numeros ('MAYUSCULAS' => 1)
print $obj->Cardinal(124856), "\n";
print $obj->Real(124856.531), "\n";
$obj->{GENERO} = 'a';
print $obj->Ordinal(124856), "\n";

DESCRIPTION

Lingua::ES::Numeros converts arbitrary numbers into human-oriented Spanish text.

This module supports the translation of cardinal, ordinal and, real numbers, the module handles integer numbers up to vigintillions (that's 1e120), since Perl does not handle such numbers natively, numbers are kept as text strings because processing does not justify using bigint.

METHODS

$obj = Lingua::ES::Numeros->new(%options)

Creates a new translation object. Options mey be a list of the following KEY => VALUE pairs:

DECIMAL

Decimal point delimiter, a single character used to delimit integer and fraction parts of the number. Default value is ".".

SEPARADORES

Delimiters ignored while parsing numbers. Characters in this set are deleted before number parsing, by default SEPARADORES is the following string: '_'

ACENTOS

If ACENTOS is true then number names will be ortographically correct with accent characters included, otherwise accented letters will be translated to USACII characters. This is true by default.

MAYUSCULAS

Numbers are translated to all uppercase if this is true, otherwise the text will be all lowercase which is the default.

HTML

Returns HTML text (normal text with HTML entities) if true, defaults to false.

GENERO

Sets the gender of the numbers, it may have the folowing values: 'a' female gender 'o' male gender '' no gender (neutral gender)

The following table shows the efect of gender on Cardinal and Ordinal numbers:

+---+--------------------+-----------------------------+
|N  |     CARDINAL       |          ORDINAL            |
|u  +------+------+------+---------+---------+---------+
|m  | 'o'  | 'a'  |  ''  |   'o'   |   'a'   |   ''    |
+---+------+------+------+---------+---------+---------+
| 1 | uno  | una  | un   | primero | primera | primer  |
| 2 | dos  | dos  | dos  | segundo | segunda | segundo |
| 3 | tres | tres | tres | tercero | tercera | tercer  |
+---+------+------+------+---------+---------+---------+
UNMIL

If true (the defaut), 1000 will be translated "un mil", otherwise it will be translated to the more informal "mil".

NEGATIVO

Label for negative numbers, this is prepended to negative numbers, default value is "menos". For example: translation of -5 will yield "menos cinco".

POSITIVO

Label for positive numbers, this is prepended to positive numbers, default value is "" (blank). For example: translation of 5 will yield "cinco".

FORMATO

String for formatting of real numbers, default value is: 'con %2d ctms.' (see real).

$text = $obj->cardinal($num)

Translates a cardinal number ($num) to spanish text, translation is performed according to the following object ($obj) settings: DECIMAL, SEPARADORES, SEXO, ACENTOS, MAYUSCULAS, POSITIVO and NEGATIVO.

This method ignores any fraction part of the number ($num).

$text = real($n; $genf, $genm)

Translates the real number ($n) to spanish text.

The optional $genf and $genm parameters are used to specify gender of the fraction part and fraction part magnitude in that order. If $genf is missing it will default to the GENDER option, and $genm will default to the $genf's value.

This translation is affected by the options: DECIMAL, SEPARADORES, GENDER, ACENTOS, MAYUSCULAS, POSITIVO, NEGATIVO and FORMATO.

Fraction format (FORMATO)

FORMAT option is a formatting string like printf, it is used to format the fractional part before appending it to the integer part. It has the following format specifiers:

%Ns

Formats the fractional part as text with precisión of N digits, for example: number '124.345' formated with string 'CON %s.' will yield the text 'ciento veinticuatro CON trescientas cuarenta y cinco milésimas', and formatted with string 'CON %2s.' will yield 'ciento veinticuatro CON treinta y cuatro centésimas'.

%Nd

Formats the fractional part as a number (no translation), with precision of N digits, veri similar to sprintf's %d format, for example: number '124.045' formated with 'CON %2d ctms.' will yield: 'ciento veinticuatro CON 04 ctms.'

$text = $obj->ordinal($num)

Translates an ordinal number ($num) to spanish text, translation is performed according to the following object ($obj) settings: DECIMAL, SEPARADORES, GENERO, ACENTOS, MAYUSCULAS, POSITIVO and NEGATIVO.

This method croacks if $num <= 0 and carps if $num has a fractional part.

INTERNALS

Functions in this seccition are generally not used, but are docummented here for completeness.

This is not part of the module's API and is subject to change.

CARDINAL SUPPORT

Construction of cardinal numbers

cardinal_e2($n, $nn)

This procedure takes $n (an integer in the range [0 .. 99], not verified) and adds the numbers text translation to $nn (a word stack), on a word by word basis. If $n == 0 nothing is pushed into $nn.

Returns nothing.

cardinal_e3($n, $nn)

This procedure takes $n (an integer in the range [0 .. 99], not verified) and adds the numbers text translation to $nn (a word stack), on a word by word basis. If $n == 0 nothing is pushed into $nn.

Returns nothing.

cardinal_e6($n, $nn, $mag, $un_mil, $postfix)

Parameters: $n the number between 0 and 999999 (not verified). $nn: word stack. $mag: magnitude of the number 1 for millions, 2 for billions, etc. $un_mil: if true 1000 is translated as "un mil" otherwise "mil" $postfix: array representing plural & singular magnitude of the number, in this order.

This procedure takes $n, and pushes the numbers text translation into $nn, on a word by word basis, with the proper translated magnitude. If $n == 0 nothing is pushed into $nn.

Returns nothing.

cardinal_generic($n, $exp, $fmag, $gen)

Parameters: $n the number. $exp: exponent. $fmag: closure to format the 6 digits groups. $gen: gender of the number: 'a' for female gender (1 -> una). 'o' for male gender (1 -> uno). '' for neutral gender (1 -> un).

This function translate the natural number $n to spanish words, adding gender where needed.

Returns the translation of $n to spanish text as a list of words.

cardinal_simple($n, $exp, $un_mil; $gen)

Parameters: $n the number. $exp: exponent. $un_mil: if true 1000 is translated as "un mil" otherwise "mil" $gen: gender of the number (optional with default value ''): 'a' for female gender (1 -> una). 'o' for male gender (1 -> uno). '' for neutral gender (1 -> un).

This function translate the natural number $n to spanish words, adding gender where needed.

This procedure just builds a closure with format information, to call cardinal_e6, and then calls cardinal_generic to do the work.

Returns the translation of $n to spanish text as a list of words.

fraccion_mag_prefix($mag, $gp)

Parameters: $mag: magnitude of the number 1 for millionths, 2 for billionths, etc. $gp: gender and plural of the number ('as' is female plural, 'o' is male singular), $gp=$gender . $plural

This function returns the name of the magnitude of a fraction, $mag is the number of decimal digits. For example 0.001 has $mag == 3 and translates to "milesimos" if $gp is 'os'.

Returns the translation of $n to spanish text as a string.

fraccion_simple($n, $exp, $un_mil, $gen; $ngen)

Parameters: $n the number. $exp: exponent. $un_mil: if true 1000 is translated as "un mil" otherwise "mil" $gen: gender of the magnitude: 'a' for female gender (1 -> una). 'o' for male gender (1 -> uno). '' for neutral gender (1 -> un). $ngen: gender of the number (same values as $gen).

This function translate the fraction $n to spanish words, adding gender where needed.

This procedure just builds a closure with format information, to call cardinal_e6, and then calls cardinal_generic to do the work.

Returns the translation of $n to spanish text as a list of words.

ORDINAL SUPPORT

Construction of ordinal numbers

ordinal_e2($n, $nn)

This procedure takes $n (an integer in the range [0 .. 99], not verified) and adds the numbers text translation to $nn (a word stack), on a word by word basis. If $n == 0 nothing is pushed into $nn.

Returns nothing.

ordinal_e3($n, $nn)

This procedure takes $n (an integer in the range [0 .. 999], not verified) and adds the numbers text translation to $nn (a word stack), on a word by word basis. If $n == 0 nothing is pushed into $nn.

Returns nothing.

ordinal_e6($n, $nn, $mag, $un_mil, $postfix)

Parameters: $n the number between 0 and 999999 (not verified). $nn: word stack. $mag: magnitude of the number 1 for millions, 2 for billions, etc.

This procedure takes $n, and pushes the numbers text translation into $nn, on a word by word basis, with the proper translated magnitude. If $n == 0 nothing is pushed into $nn.

Returns nothing.

ordinal_simple($n, $exp; $gen)

Parameters: $n the number. $exp: exponent. $un_mil: if true 1000 is translated as "un mil" otherwise "mil" $gen: gender of the magnitude (optional defaults to ''): 'a' for female gender (1 -> primera). 'o' for male gender (1 -> primero). '' for neutral gender (1 -> primer).

This function translate the fraction $n to spanish words, adding gender where needed.

This procedure just builds a closure with format information, to call ordinal_e6, and then calls ordinal_generic to do the work.

Returns the translation of $n to spanish text as a list of words.

MISCELANEOUS

Everithing not fitting elsewere

parse_num($num, $dec, $sep)

Parameters: $num: the number. $dec: decimal separator (tipically ',' or '.'). $sep: separator characters ignored by the parser.

This function parses a general number and returns a list of 4 elements: $sgn: sign of the number: -1 if negative, 1 otherwise $int: integer part of the number $frc: decimal (fraction) part of the number $exp: exponent of the number

Croaks if there is a syntax error.

$obj->retval($value)

Utility method to adjust return values, transforms text following the options: ACENTOS, MAYUSCULAS y HTML.

Returns the adjusted $value.

DEPENDENCIES

Perl 5.006, Exporter, Carp

SEE ALSO

http://roble.pntic.mec.es/~msanto1/ortografia/numeros.htm

AUTHOR

Jose Rey, <jrey@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2001-2007 by Jose Rey

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 207:

Non-ASCII character seen before =encoding in 'precisión'. Assuming UTF-8