NAME

Lingua::ES::Numeros - Convierte números a texto en Español (Castellano)

SYNOPSIS

use Lingua::ES::Numeros

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

REQUIERE

Perl 5.004, Exporter, Carp

DESCRIPTION

Lingua::ES::Numeros convierte números de precisión arbitraria en su representación textual en castellano. Tiene soporte para la representación de cardinales, ordinales y reales. Como los números manejados tienen mayor rango que el manejo númeríco nativo de Perl, estos se manejan como cadenas de caracteres, permitiendo así el crecimiento ilimitado del sistema de conversión.

MÉTODOS DE CLASE

parse_num($num, $dec, $sep)

Descompone el número en sus diferentes partes y retorna una lista con las mismas, por ejemplo:

use Linugua::ES::Numeros qw( :All );
($sgn, $ent, $frc, $exp) = parse_num('123.45e10', '.', '",');

Parámetros

$num

El número a traducir

$dec

El separador de decimales.

$sep

Los caracteres separadores de miles, millones, etc.

Valores de retorno

$sgn

Signo, puede ser -1 si está presente el signo negativo, 1 si está presente el signo negativo y 0 si no hay signo presente.

$ent

Parte entera del número, solo los dígitos más significativos (ver $exp)

$frc

Parte fraccional del número, solo los dígitos menos significativos (ver $exp)

$exp

Exponente del número, si es > 0, dicta el número de ceros que sigue a la parte entera, si es < 0, dicta el número de ceros que están entre el punto decimal y la parte fraccional.

Este método no se exporta implicitamente, asi que debe ser importado con cualquiera de las siguientes sintaxis:

use Lingua::ES::Numeros qw(parse_num);
use Lingua::ES::Numeros qw(:All);

CAMPOS

El objeto contiene los siguientes campos que alteran la conversión.

DECIMAL

Especifíca la cadena de caracteres que se utilizará para separar la parte entera de la parte fraccional del número a convertir. El valor por defecto de DECIMAL es '.'

SEPARADORES

Cadena de caracteres que contiene todos los caracteres de formato del número. Todos los caracteres de esta cadena serán ignorados por el parser que descompone el número. El valor por defecto de SEPARADORES es ',"_'

ACENTOS

Afecta la ortografía de los números traducidos, si es falso la representación textual de los números no tendrá acentos, el valor predeterminado de este campo es 1 (con acentos). Esté campo puede ser de mucha utilidad si el conjunto de caracteres utilizado no es el Latin1, ya que los acentos dependen de él en esta versión (ver PROBLEMAS).

MAYUSCULAS

Si es cierto, la representación textual del número será una cadena de caracteres en mayúsculas, el valor predeterminado de este campo es 0 (en minúsculas)

HTML

Si es cierto, la representación textual del número será una cadena de caracteres en HTML (los acentos estarán representados por las respectivas entidades HTML). El valor predeterminado es 0 (texto).

SEXO

El sexo de los números, puede ser: 'a', 'o' o '', para números en femenino, masculino o neutro respectivamente. El valor por defecto de este campo es 'o'.

+---+--------------------+-----------------------------+
|Nú |     CARDINALES     |          ORDINALES          |
|me +------+------+------+---------+---------+---------+
|ro | '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

Este campo solo afecta la traduccion de cardinales y cuando es cierto, el número 1000 se traduce como 'un mil', de otro modo se traduce simplemente 'mil'. El valor por defecto de UNMIL es 1.

NEGATIVO

La cadena de caracteres que contiene el nombre con el que se traducirá el signo negativo (-), por defecto vale 'menos'.

POSITIVO

La cadena de caracteres que contiene el nombre con el que se traducirá el signo positivo (+), por defecto vale ''. Esta cadena sólo es añadida al número en presencia del signo '+', de otro modo no se agrega aunque el número se asume positivo.

FORMATO

Una cadena de caracteres que especifíca como se deben traducir los decimales de un número real. Su valor por defecto es 'con %02d ctms.' (ver el método real).

CONSTRUCTOR

Para construir un objeto Lingua::ES::Numeros, se utiliza el método de clase new, este método puede recibir como parámetro cualesquiera de los campos mencionados en la sección anterior.

Ejemplos:

      use Lingua::ES::Numeros;
      
      # usa los valores predeterminados de los campos
      $obj = new Lingua::ES::Numeros; 
      
      # especifíca los valores de algunos campos
      $obj = Lingua::ES::Numeros::->new( 'ACENTOS'    => 0, 
                                         'MAYUSCULAS' => 1,
                                         'SEXO'       => 'a',
					 'DECIMAL'    => ',',
					 'SEPARADORES'=> '"_' );

MÉTODOS DEL OBJETO

$n = cardinal($n)

Convierte el número $n, como un número cardinal a castellano.

La conversión esta afectada por los campos: DECIMAL, SEPARADORES, SEXO, ACENTOS, MAYUSCULAS, POSITIVO y NEGATIVO.

Esta conversión ignora la parte fraccional del número, si la tiene.

$n = real($n [, $fsexo])

Convierte el número $n, como un número real a castellano.

El parámetro opcional $fsexo se utiliza para especificas un sexo diferente para la parte decimal, recibe los mismos valores que se le pueden asignar al campo SESO, pero el sexo neutro equivale a masculino en la parte fraccional, si es omitido se usará el valor del campo SEXO.

La conversión esta afectada por los campos: DECIMAL, SEPARADORES, SEXO, ACENTOS, MAYUSCULAS, POSITIVO y NEGATIVO.

Formato de la parte fraccional (FORMATO)

Además esta conversión utiliza el campo FORMATO para dirigir la conversión de la parte fraccional del número real. Este campo es un formato estilo sprintf que solo tiene una especificación de formato precedida por '%'. Además las dos únicas especificaciones válidas por ahora son:

%s

Incluye la representación textual de la parte fraccional dentro del formato. Por ejemplo, convertir '123.345' con formato 'más %s.' resultará en el número: CIENTO VEINTITRÉS Y TRECIENTOS CUARENTA MÁS CINCO MILÉSIMAS.

%Nd

Incluye la representación numérica de la parte fraccional, donde N es una especificación del formato '%d' de sprintf. Por ejemplo, convertir '123.345' con formato ' con %02d ctms.' producirá: CIENTO VEINTITRÉS Y TRECIENTOS CUARENTA CON 34 CTMS.

$n = ordinal($n)

Convierte el número $n, como un número ordinal a castellano.

La conversión esta afectada por los campos: DECIMAL, SEPARADORES, SEXO, ACENTOS y MAYUSCULAS.

Presenta advertencias si el número es negativo y/o si no es un natural > 0.

DIAGNÓSTICOS

Número ilegal.

El número tiene un error sintáctico.

Número fuera de rango.

La parte entera del número es demasiado grande. Por el momento solo se aceptan números de hasta 10**126 - 1, pues no se cual es la representación textual de números >= 10**126. Cualquier ayuda o corrección será bien recibida.

Número fuera de precisión.

La parte fraccional del número es menor que 10**-126 y no se puede traducir por los motivos antes mencionados.

Ordinal negativo

El número a convertir en ordinal es negativo.

Ordinal con decimales

El número a convertir en ordinal tiene decimales.

AUTOR

José Luis Rey Barreira <jrey@mercared.com>

PROBLEMAS

La conversión a mayúsculas se está haciendo actualmente mediante una transliteración para poder convertir los caracteres acentuados. El problema es que esto no funcionará si el conjunto de caracteres en uso es distinto al ISO 8859-1 (Latin1) o al ISO 8859-15.

Las alternativas a este problema serían: la utilización de Perl 5.6 o superior con 'utf8', pero restringo el uso del módulo a una gran cantidad de usuarios que todavía usan Perl 5.00x, por otra parte podría utilizar locales, pero no se si estos funcionan exactamente igual en Unix, Windows, BeOS, etc. así que creo que la transliteración es adecuada por ahora.

LICENCIA

Este código es propiedad intelectual de José Rey y se distribuye según los términos de la Licencia Pública General del proyecto GNU, cuya letra y explicación se pueden encontrar en inglés en la página http://www.gnu.org/licenses/licenses.html y de la que cual hay una traducción al castellano en http://lucas.hispalinux.es/Otros/gples/gples.html

cpanm Lingua::ES::Numeros

perl -MCPAN -e shell
install Lingua::ES::Numeros