NAME

Astro::App::Satpass2::Locale - Handle locale-dependant data.

SYNOPSIS

 use Astro::App::Satpass2::Locale qw{ __localize };
 
 # The best localization
 say scalar __localize( 'foo', 'bar', 'default text' );
 
 # All localizations, in decreasing order of goodness
 for ( __localize( 'foo', 'bar', 'default text' ) ) {
     say;
 }

DESCRIPTION

This Perl module implements the locale system for Astro::App::Satpass2.

The locale data can be thought of as a two-level hash, with the first level corresponding to the section of a Microsoft-style configuration file and the second level to the items in the section.

The locale data are stored in .pm files, which return the required hash when they are loaded. These are named after the locale, in the form lc_CC.pm or lc.pm, where the lc is the language code (lower case) and the CC is a country code (upper case).

The files are considered in the following order:

The user's lc_CC.pm

The global lc_CC.pm

The user's lc.pm

The global lc.pm

The user's C.pm

The global C.pm.

The global files are installed as Perl modules, named Astro::App::Satpass2::Locale::whatever, and are loaded via require(). The user's files are stored in the locale/ directory of the user's configuration, and are loaded via do().

SUBROUTINES

This class supports the following exportable public subroutines:

__localize

 # The best localization
 say scalar __localize( 'foo', 'bar', 'default text' );
 
 # All localizations, in decreasing order of goodness
 for ( __localize( 'foo', 'bar', 'default text' ) ) {
     say;
 }

This subroutine is the interface used to localize values. The last (rightmost) argument is the default, to be returned if no localization can be found. All leading (leftmost) arguments that are defined and are not references are keys (or indices) used to traverse the locale data structure. Any remaining arguments are either hash references (which represent last-chance locale definitions) or ignored.

If called in scalar context, the best available localization is returned. If called in list context, all available localizations will be returned, with the best first and the worst (which will be the default) last.

To extend the above example, assuming neither the system-wide or locale-specific locale information defines the keys {fu}{bar},

 say scalar __localize( foo => 'bar', {
     C => {
         foo => {
             bar => 'Gronk!',
         },
     },
     fr => {
         foo => {
             bar => 'Gronkez!',
         },
     },
 }, 'Greeble' );

will print 'Gronkez!' in a French locale, and 'Gronk!' in any other locale (since the 'C' locale is always consulted). If 'Greeble' is printed, it indicates that the locale system is buggy.

__message

 say __message( 'Fee fi foe foo!' ); # Fee fi foe foo
 say __message( 'A', 'B', 'C' );     # A B C
 say __message( 'Hello [% arg.0 %]!', 'sailor' );
                                     # Hello sailor!

This subroutine is a wrapper for __localize() designed to make message localization easier.

The first argument is localized by looking it up under the {'+message'} key in the localization data. If no localization is found, the first argument is its own localization. In other words, if the first argument is $message, its localization is __localize( '+message', $message, $message ).

If the localization contains Template-Toolkit interpolations (specifically, '[%') it and the arguments are fed to that system, with the arguments being available to the template as variable arg. The result is returned.

If the localization of the first argument does not contain any Template-Toolkit interpolations, it is simply joined to the arguments, with single space characters in between, and the result of the join is returned.

__preferred

 say __preferred()

This subroutine returns the user's preferred locale in scalar mode, or all acceptable locales in descending order of preference in list mode.

SEE ALSO

Astro::App::Satpass2::FormatValue

SUPPORT

Support is by the author. Please file bug reports at http://rt.cpan.org, or in electronic mail to the author.

AUTHOR

Thomas R. Wyant, III wyant at cpan dot org

COPYRIGHT AND LICENSE

Copyright (C) 2014-2015 by Thomas R. Wyant, III

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0. For more details, see the full text of the licenses in the directory LICENSES.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

cpanm Astro::App::Satpass2

perl -MCPAN -e shell
install Astro::App::Satpass2