/ 
Locale-Maketext-Utils-v0.0.3
River stage one • 3 direct dependents • 4 total dependents
/ Locale::Maketext::Utils

NAME

Locale::Maketext::Utils - Adds some utility functionality and failure handling to Local::Maketext handles

SYNOPSIS

In MyApp/Localize.pm:

  package MyApp::Localize;
  use Locale::Maketext::Utils; 
  use base 'Locale::Maketext::Utils'; 

  our $Encoding = 'utf8'; # see below
  
  # no _AUTO
  our %Lexicon = (...

Make all the language Lexicons you want. (no _AUTO)

Then in your script:

my $lang = MyApp::Localize->get_handle('fr');

Now $lang is a normal Locale::Maketext handle object but now there are some new methods and failure handling which are described below.

our $Encoding

If you set your class's $Encoding variable the object's encoding will be set to that.

my $enc = $lh->encoding();

$enc is $MyApp::Localize::fr::Encoding || $MyApp::Localize::Encoding || encoding()'s default

METHODS

$lh->print($key, @args);

Shortcut for

print $lh->maketext($key, @args);

$lh->fetch($key, @args);

Alias for

$lh->maketext($key, @args);

$lh->get_base_class()

Returns the base class of the object. So if $lh is a MyApp::Localize::fr object then it returns MyApp::Localize

$lh->get_language_tag()

Returns the real language name space being used, not language_tag()'s "cleaned up" one

$lh->langtag_is_loadable($lang_tag)

Returns 0 if the argument is not a language that can be used to get a handle.

Returns the language handle if it is a language that can be used to get a handle.

$lh->lang_names_hashref()

This returns a hashref whose keys are the language tags and the values are the name of language tag in $lh's native langauge.

It can be called several ways:

  • Give it a list of tags to lookup

    $lh->lang_names_hashref(@lang_tags)

  • Have it search @INC for Base/Class/*.pm's

    $lh->lang_names_hashref() # IE no args

  • Have it search specific places for Base/Class/*.pm's

    local $lh->{'_lang_pm_search_paths'} = \@lang_paths; # array ref of directories
$lh->lang_names_hashref() # IE no args

The module it uses for lookup (Locales::Language) is only required when this method is called.

The module it uses for lookup (Locales::Language) is currently limited to two character codes but we try to handle it gracefully here.

Does not ensure that the tags are loadable, to do that see below.

$lh->loadable_lang_names_hashref()

Exactly the same as $lh->lang_names_hashref() (because it calls that method...) except it only contains tags that are loadable.

Has additional overhead of calling $lh->langtag_is_loadable() on each key. So most likely you'd use this on a single specific place (a page to choose their language setting for instance) instead of calling it on every instance your script is run.

$lh->append_to_lexicons( $lexicons_hashref );

This method allows modules or script to append to the object's Lexicons

Each key is the language tag whose Lexicon you will prepend its value, a hashref, to.

So assuming the key is 'fr', then this is the lexicon that gets appended to:

__PACKAGE__::fr::Lexicon

The only exception is if the key is '_'. In that case the main package's Lexicon is appended to:

__PACKAGE__::Lexicon

$lh->append_to_lexicons({
    '_' => {
        'Hello World' => 'Hello World',
    },
    'fr' => {
        'Hello World' => 'Bonjour Monde',
    }, 
});

$lh->remove_key_from_lexicons($key)

Removes $key from every lexicon. What is removed is stored in $lh->{'_removed_from_lexicons'}

If defined, $lh->{'_removed_from_lexicons'} is a hashref whose keys are the index number of the $lh->_lex_refs() arrayref.

The value is the key and the value that that lexicon had.

This is used internally to remove _AUTO keys so that the failure handler below will get used

Automatically _AUTO'd Failure Handling with hooks

This module sets fail_with() so that failure is handled for every Lexicon you define as if _AUTO was set and in addition you can use the hooks below.

This functionality is turned off if:

  • _AUTO is set on the Lexicon (and it was not removed internally for some strange reason)

  • you've changed the failure function with $lh->fail_with() (If you do change it be sure to restore your _AUTO's inside $lh->{'_removed_from_lexicons'})

The result is that a key is looked for in the handle's Lexicon, then the default Lexicon, then the handlers below, and finally the key itself (Again, as if _AUTO had been set on the Lexicon). I find this extremely useful and hope you do as well :)

$lh->{'_get_key_from_lookup'}

If lookup fails this code reference will be called with the arguments ($lh, $key, @args)

It can do whatever you want to try and find the $key and return the desired string.

return $string_from_db;

If it fails it should simply:

return;

That way it will continue on to the part below:

$lh->{'_log_phantom_key'}

If $lh->{'_get_key_from_lookup'} is not a code ref, or $lh->{'_get_key_from_lookup'} returned undef then this method is called with the arguments ($lh, $key, @args) right before the failure handler does its _AUTO wonderfulness.

SEE ALSO

Locale::Maketext, Locales::Language

SUGGESTIONS

If you have an idea for a method that would fit into this module just let me know and we'll see what can be done

AUTHOR

Daniel Muey, http://drmuey.com/cpan_contact.pl

COPYRIGHT AND LICENSE

Copyright (C) 2006 by Daniel Muey

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.