view release on metacpan or  search on metacpan

lib/Lingua/Deva.pm  view on Meta::CPAN

package Lingua::Deva;

use v5.12.1;
use strict;
use warnings;
use utf8;
use charnames          qw( :full );
use open               qw( :encoding(UTF-8) :std );
use Unicode::Normalize qw( NFD NFC );
use Carp               qw( croak carp );

use Lingua::Deva::Aksara;
use Lingua::Deva::Maps qw( %Consonants %Vowels %Diacritics %Finals
                           $Inherent $Virama $Avagraha );

=encoding UTF-8

=head1 NAME

Lingua::Deva - Convert between Latin and Devanagari Sanskrit text

=cut

our $VERSION = '1.20';

=head1 SYNOPSIS

    use v5.12.1;
    use strict;
    use utf8;
    use charnames ':full';
    use Lingua::Deva;

    # Basic usage
    my $d = Lingua::Deva->new();
    say $d->to_latin('आसीद्राजा'); # prints 'āsīdrājā'
    say $d->to_deva('Nalo nāma'); # prints 'नलो नाम'

    # With configuration: strict, allow Danda, 'w' for 'v'
    my %c = %Lingua::Deva::Maps::Consonants;
    $d = Lingua::Deva->new(
        strict => 1,
        allow  => [ "\N{DEVANAGARI DANDA}" ],
        C      => do { $c{'w'} = delete $c{'v'}; \%c },
    );
    say $d->to_deva('ziwāya'); # 'zइवाय', warning for 'z'
    say $d->to_latin('सर्वम्।'); # 'sarwam।', no warnings

=head1 DESCRIPTION

The C<Lingua::Deva> module provides facilities for converting Sanskrit in
various Latin transliterations to Devanagari and vice-versa.  "Deva" is the
name for the Devanagari (I<devanāgarī>) script according to ISO 15924.

The facilities of this module are exposed through a simple interface in the
form of instances of the L<Lingua::Deva> class.  A number of configuration
options can be passed to it during initialization.

Using the module is as simple as creating a C<Lingua::Deva> instance and
calling its methods L<to_deva()> or L<to_latin()> with appropriate string
arguments.

    my $d = Lingua::Deva->new();
    say $d->to_latin('कामसूत्र');
    say $d->to_deva('Kāmasūtra');

By default, transliteration follows the widely used IAST conventions.  Three
other ready-made transliteration schemes are also included with this module,
ISO 15919 (C<ISO15919>), Harvard-Kyoto (C<HK>), and ITRANS.

    my $d = Lingua::Deva->new(map => 'HK');
    say $d->to_latin('कामसूत्र'); # prints 'kAmasUtra'

For additional flexibility all mappings can be completely customized; users
can also provide their own.

    use Lingua::Deva::Maps::ISO15919;
    my %f = %Lingua::Deva::Maps::ISO15919::Finals;
    my $d = Lingua::Deva->new(
        map           => 'IAST', # use IAST transliteration
        casesensitive => 1,      # do not case fold
        F             => \%f,    # ISO 15919 mappings for finals
    );
    say $d->to_deva('Vṛtraṁ'); # prints 'Vऋत्रं'

For more information on customization see L<Lingua::Deva::Maps>.

Behind the scenes, all translation is done via an intermediate object
representation called "Aksara" (Sanskrit I<aká¹£ara>).  These objects are
instances of L<Lingua::Deva::Aksara>, which provides an interface to inspect
and manipulate individual Aksaras.

    # Create an array of Aksaras
    my $a = $d->l_to_aksaras('Kāmasūtra');

    # Print vowel in the fourth Aksara
    say $a->[3]->vowel();

The methods and options of C<Lingua::Deva> are described below.

=head2 Methods

=over 4

=item new()

Constructor.  Takes the following optional arguments.

=over 4

=item C<< map => 'IAST'|'ISO15919'|'HK'|'ITRANS' >>