/ 
Astro-App-Satpass2-0.030
River stage zero No dependents
/ Astro::App::Satpass2::Locale

NAME

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

SYNOPSIS

use Astro::App::Satpass2::Locale qw{ __localize };

# The best localization
say scalar __localize(
    text    => [ 'foo', 'bar' ],
    default => 'default text',
);

# All localizations, in decreasing order of goodness
for ( __localize(
    text    => [ 'foo', 'bar' ],
    default => '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(
    text    => [ 'foo', 'bar' ],
    default => 'default text',
);

# All localizations, in decreasing order of goodness
for ( __localize(
    text    => [ 'foo', 'bar' ],
    default => 'default text',
) ) {
    say;
}

This subroutine is the interface used to localize values.

The arguments are name/value pairs, with the following names being the only ones supported.

text

This argument is required, and passes the text to be localized. This can be either a scalar, or a reference to an array of keys (or indices) used to traverse the locale data structure.

default

This argument specifies the default value to be returned if no localization is available. If it is not specified, undef is returned if no localization is available.

locale

This argument specifies either a hash reference that is consulted for locale information if all other available locales provide no localization, or a reference to an array of such hashes. The default is [].

argument

This argument specifies the value of the second argument passed to a code reference which is being used for localization. See Astro::App::Satpass2::Locale::C for an example of how this can be used.

All other keys are unsupported in the sense that the author makes no representation what will happen if you specify them, and makes no commitment that whatever you observe to happen will not change without notice.

If this subroutine is called in scalar context, the best available localization is returned. If it is 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(
     text    => [ foo => 'bar' ],
     default => 'Greeble',
     locale  => {
         C => {
	     foo => {
	         bar => 'Gronk!',
	     },
         },
         fr => {
	     foo => {
	         bar => 'Gronkez!',
	     },
         },
     },
 );

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-2016 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.