NAME

       Text::Roman - Allows conversion between Roman and Arabic algarisms.

VERSION

       version 3.5

SYNOPSIS

           #!/usr/bin/env perl
           use strict;
           use warnings;
           use Text::Roman qw(:all);

           print int2roman(123), "\n";

           my $roman = "XXXV";
           print roman2int($roman), "\n" if isroman($roman);

           my $milhar = 'L_X_XXIII'; # = 60,023
           print milhar2int($milhar), "\n" if ismilhar($milhar);

DESCRIPTION

       This package supports both conventional Roman algarisms (which range from 1 to 3999) and
       Milhar Romans, a variation which uses a bar across the algarism to indicate multiplication
       by 1_000.  For the purposes of this module, acceptable syntax consists of an underscore
       suffixed to the algarism e.g. IV_V = 4_005.  The term Milhar apparently derives from the
       Portuguese word for "thousands" and the range of this notation extends the range of Roman
       numbers to 3999 * 1000 + 3999 = 4_002_999.

       Note: the functions in this package treat Roman algarisms in a case-insensitive manner
       such that "VI" == "vI" == "Vi" == "vi".

       The following functions may be imported into the caller package by name:

FUNCTIONS

   isroman
       Tests a string to be a valid Roman algarism.  Returns a boolean value.

   int2roman
       Converts an integer expressed in Arabic numerals, to its corresponding Roman algarism.  If
       the integer provided is out of the range expressible in Roman notation, an undef is
       returned.

   roman2int
       Does the converse of "int2roman", converting a Roman algarism to its integer value.

   ismilhar
       Determines whether a string qualifies as a Milhar Roman algarism.

   milhar2int
       Converts a Milhar Roman algarism to an integer.

   ismroman/mroman2int/roman
       These functions belong to the module's old interface and are considered deprecated.  Do
       not use them in new code and they will eventually be discontinued; they map as follows:

       •   ismroman      => ismilhar

       •   mroman2int    => milhar2int

       •   roman         => int2roman

CHANGES

       Some changes worth noting from this module's previous incarnation:

       namespace imports
           The call to use must now explicitly request function names imported into it's
           namespace.

       argument defaults/void context
           All functions now will operate on $_ when no arguments are passed, and will set $_
           when called in a void context.  This allows for writing code like:

               @x = qw/V III XI IV/;
               roman2int() for @x;
               print join("-", @x);

           instead of the uglier:

               @x = qw/V III XI IV/;
               $_ = roman2int($_) for @x;
               print join("-", @x);

SPECIFICATION

       Roman algarisms may be described using the following BNF-like formula:

           a   = I{1,3}
           b   = V\a?|IV|\a
           e   = X{1,3}\b?|X{0,3}IX|\b
           ee  = IX|\b
           f   = L\e?|XL\ee?|\e
           g   = C{1,3}\f?|C{0,3}XC\ee?|\f
           gg  = XC\ee?|\f
           h   = D\g?|CD\gg?|\g
           j   = M{1,3}\h?|M{0,3}CM\gg?|\h

REFERENCES

       For a description of the Roman numeral system see:
       <http://www.novaroma.org/via_romana/numbers.html>.  A reference to Milhar Roman alagarisms
       (in Portuguese) may be found at:
       <http://web.archive.org/web/20020819094718/http://www.estado.com.br/redac/norn-nro.html>.

ACKNOWLEDGEMENTS

       This module was originally written by Peter de Padua Krauss and submitted to CPAN by
       Stanislaw Pusep <https://metacpan.org/author/SYP> who has relinquished control to Erick
       Calder <https://metacpan.org/author/ECALDER> since the original author has never
       maintained it and can no longer be reached.

       Erick have completely rewritten the module, implementing simpler algorithms to perform the
       same functionality, adding a test suite, a Changes file, etc. and providing more
       comprehensive documentation.

       Ten years later, Stanislaw returned as a maintainer.

AUTHOR

       Stanislaw Pusep <stas@sysd.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2003 by Erick Calder <ecalder@cpan.org>.

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