| Subject: | Documentation only available in Spanish |
Although this module is intended mostly for Spanish speakers, it can
also come in very handy for people having to _generate_ Spanish, even if
not speakers of the language themselves.
I translated your documentation to English, and added it as another
manpage. In Debian, both manpages are installed, and the system will
present you the right one depending on your locales - I don't know how
to integrate this functionality from within the ExtUtils::MakeMaker
framework, so I leave the task up to you.
| Subject: | Numeros.pod |
=head1 NAME
Lingua::ES::Numeros - Converts numbers to Spanish text
=head1 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";
=head1 REQUIRES
Perl 5.004, Exporter, Carp
=head1 NOTE
Both this module's interface and documentation were originally written
completely in Spanish. The English documentation was written by Gunnar Wolf
E<lt>gwolf@debian.orgE<gt> for its inclusion in the Debian packaging.
Obviously, in the documentation, I will still reflect the Spanish method and
attribute names - it might sound strange, but it's the only way. If you need
something more natural, it'd be almost trivial to call a wrapper for this
module using English method and attribute names.
=head1 DESCRIPTION
Lingua::ES::Numeros converts arbitrary precision numbers to their textual
representation in Spanish. It can produce the representation of cardinal,
ordinal and real numbers. As the handled numbers have a greater range than the
Perl native numeric type, they are handled as character strings, which allows
for the unlimited growth of the conversion system.
=head1 CLASS METHODS
=over 4
=item parse_num($num, $dec, $sep)
Decomposes the number in its constitutive parts, and returns them in a list:
use Lingua::ES::Numeros qw( :All );
($sgn, $ent, $frc, $exp) = parse_num('123.45e10', '.', '",');
=head2 Parameters
=over 4
=item $num
The number to decompose
=item $dec
The decimal separator
=item $sep
The separator for thousands, millions, etc.
=back
=head2 Return values
=over 4
=item $sgn
Sign, it can be -1 if the negative sign is present, 1 if the positive sign is
present, and 0 if there is no explicit sign.
=item $ent
Integer part of the number, only the most significant digits (see $exp)
=item $frc
Fractional part of the number, only the least significant digits (see $exp)
=item $exp
Number's exponent, if it is > 0, it means the number of zeros that follow the
integer part, if it is <0, it means the number of zeros that are between the
decimal point and the fractional part.
This method is not implicitly exported, so it must be imported by either of:
use Lingua::ES::Numeros qw(parse_num);
use Lingua::ES::Numeros qw(:All);
=back
=head1 FIELDS
The object has the following fields, which alter the way in which the
conversion is carried out:
=over 4
=item DECIMAL
Specifies the character string that will be used to separate the integer from
the fractional part of the number to convert. The default value for DECIMAL
is '.'
=item SEPARADORES
Character string including all of the format characters used when representing
a number. All of the characters in this string will be ignored by the parser
when analyzing the number. The default value for SEPARADORES is ',"_'
=item ACENTOS
Affects the way in which the generated string for the translated numbers is
given; if it is false, the textual representation will not have any accented
characters. The default value for this field is 1 (with accents). This field
can be very useful if the character set used in your locale is not Latin1, as
this module's output will be given in this encoding (see BUGS).
=item MAYUSCULAS
If this is a true value, the textual representation of the number will be an
uppercase character string. The default value for this field is 0 (lowercase).
=item HTML
If this is a true value, the textual representation of the number will be a
HTML-valid string character (accents will be represented by their respective
HTML entities). The default value is 0 (text).
=item SEXO
The sex of the numbers can be 'a', 'o' or '', respectively for femenine,
masculine or neutral numbers. The default value is 'o'.
+---+--------------------+-----------------------------+
|NU | CARDINAL | ORDINAL |
|MB +------+------+------+---------+---------+---------+
|ER | '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 |
+---+------+------+------+---------+---------+---------+
=item UNMIL
This field affects only the translation of cardinal numbers. When it is a true
value, the number 1000 is translated to 'un mil' (one thousand), otherwise it
is translated to the more colloquial 'mil' (thousand). The default value is 1.
=item NEGATIVO
Contains the character string with the text to which the negative sign (-) will
be translated with. Defaults to 'menos'.
=item POSITIVO
Contains the character string with the text to which the positive sign will be
translated with. Defaults to ''. This string is only added when the sign '+' is
explicitly received, otherwise it is not added even if the number is assumed as
positive.
=item FORMAT
A character string specifying how the decimals of a real number are to be
translated. Its default value is 'con %02d ctms.' (see the B<real> method)
=back
=head1 CONSTRUCTOR
To create a new Lingua::ES::Numeros, use the B<new> class method. This method can
receive as parameters any of the above mentioned fields.
Examples:
use Lingua::ES::Numeros;
# Use the fields' default values
$obj = new Lingua::ES::Numeros;
# Specifies the values of some of them
$obj = Lingua::ES::Numeros::->new( 'ACENTOS' => 0,
'MAYUSCULAS' => 1,
'SEXO' => 'a',
'DECIMAL' => ',',
'SEPARADORES'=> '"_' );
=head1 OBJECT METHODS
=over 4
=item $n = cardinal($n)
Converts the $n number to its Spanish cardinal representation.
This conversion is affected by the DECIMAL, SEPARADORES, SEXO, ACENTOS,
MAYUSCULAS, POSITIVO and NEGATIVO fields.
This conversion ignores the fractional part of the number, if present.
=item $n = real($n [, $fsexo])
Converts the $n number, as a real number, to its Spanish representation.
The optional parameter $fsexo is used to specify a different sex for the
decimal part. It accepts the same values that the SEXO field, but the neutral
sex becomes masculine for the fractional part. If it is not specified, the
value of the SEXO field will be used.
This conversion is affected by the DECIMAL, SEPARADORES, SEXO, ACENTOS,
MAYUSCULAS, POSITIVO and NEGATIVO fields.
=head2 Format for the fractional part (FORMATO)
This conversion also uses the FORMATO field to guide the fractional part's
conversion. This field is a sprintf-like format field, which has only a single
format specification preceded by '%'. It currently handles only two valid
specifications:
=over 4
=item %s
Includes the textual representation of the fractional part of the format.
For example, converting '123.345' with a 'mE<aacute>s %s.' format will
result in: 'CIENTO VEINTITRE<Eacute>S Y TRECIENTOS CUARENTA ME<Aacute>S CINCO
MILE<Eacute>SIMAS'.
=item %Nd
Includes the numeric representation of the fractional part, with N as a valid
number for the '%d' format of sprintf. For example, converting '123.345' with a
'con %02d ctms.' results in: 'CIENTO VEINTITRE<Eacute>S Y TRECIENTOS CUARENTA
CON 34 CTMS.'
=back
=item $n = ordinal($n)
Converts the $n number, as an ordinal number, to Spanish.
The conversion is affected by the DECIMAL, SEPARADORES, SEXO, ACENTOS and
MAYUSCULAS fields.
It will issue a warning if the number is negative and/or if it is not a
positive nonzero natural.
=back
=head1 DIAGNOSTICS
=over 4
=item NE<uacute>mero ilegal.
The number has a syntax error
=item NE<uacute>mero fuera de rango.
The integer part of the number is too large. Currently, only numbers up to
10**126 - 1 are handled, as I don't know what is the textual representation of
numbers >= 10**126. Any help or correction will be most welcome.
=item NE<uacute>mero fuera de precisiE<oacute>n
the fractional part of the number is smaller than 10**-126 and can not be
translated for the above mentioned reasons.
=item Ordinal negativo
The number requested to be converted into an ordinal is negative.
=item Ordinal con decimales
The number requested to be converted into an ordinal has decimals.
=back
=head1 AUTOR
JosE<eacute> Luis Rey Barreira <jrey@mercared.com>
=head1 BUGS
The uppercase conversion is carried out by a transliteration, in order to be
able to convert accented characters. The problem is this will not work if the
character set is not ISO 8859-1 (Latin1) or ISO 8859-15.
The alternatives for this problem would be: Using Perl 5.6 or higher with
'utf8'. This would however restrict the module's usage to a large amount of
users who still prefer Perl 5.00x. On the other hand it would allow it to use
locales, although I'm not sure if they work the same way in Unix, Windows,
BeOS, etc., so I think the transliteration is adequate for now.
=head1 LICENSE
This code is intellectual property of JosE<eacute> Rey and is distributed
according to the terms of the GNU General Public License, whose letter and
explanation can be found in English in the
http://www.gnu.org/licenses/licenses.html web page, and for which a
Spanish translation is available at
http://lucas.hispalinux.es/Otros/gples/gples.html
=cut