Lirama/Loc2/Auto.pm

   1 package Lirama::Loc2::Auto;
   2
   3 use strict;
   4 use warnings;
   5 use utf8;
   6
   7 use Lirama::Loc2;
   8
   9 our $VERSION = '2.00';
  10
  11 sub optimize {
  12         my $self = shift;
  13         $self->[1]{optimize} = $_[0] if @_;
  14         return $self->[1]{optimize};
  15 } # optimize
  16
  17 sub TIEHASH {
  18         my ($class, $path, @langpref) = @_;
  19
  20         my $langs = @langpref>0;  # languages specified
  21         langpref(@langpref) if $langs;  # set default language preference
  22
  23         my $node = [  # array for faster access to common [0]
  24                 {},  # files
  25                 {    # configuration
  26                         path     => $path,
  27                         optimize => $langs,  # assume langpref won't change if specified
  28                 }
  29         ];
  30         return bless $node, $class;
  31 } # new
  32
  33 sub FETCH {
  34         my ($self, $file) = @_;
  35
  36         unless (exists $self->[0]{$file}) {
  37                 my $filename = $self->[1]{path}.'/'.$file;  # perl file returning l10n hash
  38                 my $extlang  = '.'.langpref();  # file tag for the preferred language
  39                 my $ext      = ".pl";  # extension for $filename
  40
  41                 $filename .= $extlang  # get language-optimized file
  42                         if $self->[1]{optimize} and -r $filename.$extlang.$ext;
  43
  44                 tie %{$self->[0]{$file}}, "Lirama::Loc2", do $filename.$ext;
  45         } # initialize Loc for this file
  46
  47         return $self->[0]{$file}
  48 } # FETCH
  49
  50 # Basically same as Tie::StdHash
  51
  52 sub EXISTS   { exists $_[0]->[0]{$_[1]} }
  53 sub FIRSTKEY { my $a = scalar keys %{$_[0]->[0]}; each %{$_[0]->[0]} }
  54 sub NEXTKEY  { each %{$_[0]->[0]} }
  55
  56 1;
  57
  58 __END__
  59
  60
  61 =head1 NAME
  62
  63 Lirama::Loc::Auto - Localize strings, initialize automatically
  64
  65 =head1 SYNOPSIS
  66
  67         use Lirama::Loc::Auto;
  68
  69         tie my %L, "Lirama::Loc::Auto", "path/to/translation/files", "en";
  70
  71         print $L{numbers}{7};  # "seven"
  72
  73 =head1 DESCRIPTION
  74
  75 Setup a hash containing multiple L<Lirama::Loc|Lirama::Loc> objects, which
  76 open automatically on demand.
  77
  78 =over 4
  79
  80 =item C<tie %tie, "Lirama::Loc::Auto", $path, @languages>
  81
  82 Will setup a hash to automatically load data files from P<$path/*.pl>.
  83 These files should only return an anonimous translation hash.
  84
  85 If @languages is set, it will be taken as the default language preference.
  86 [todo:optimize]
  87
  88 =item C<$tie{$file}{$string}>
  89
  90 The first time a translation is accessed from C<$tie{$file}{$string}>, it will
  91 create a Lirama::Loc object from P<$path/$file.pl>.
  92
  93 =item C<optimize>
  94
  95 =item C<exists>
  96
  97 bla
  98
  99 =back
 100
 101 =head1 EXAMPLE
 102
 103 We'll create P<./includes/loc/index.pl> with the following contents:
 104
 105         {
 106                 welcome => {
 107                         en => "welcome",
 108                         eo => "bonvenon",
 109                         nl => "welkom",
 110                 },
 111                 "%d visits" => {
 112                         en => sub { "%d user".($_[0]!=1 && "s")." have visited this site." },
 113                 },
 114         }
 115
 116 Setup a hash with user defined language preferences, and a fallback to English.
 117
 118         my @langpref = split(',', $ENV{HTTP_ACCEPT_LANGUAGE});
 119         tie my %loc, "Lirama::Loc::Auto", "includes/loc", @langpref, "en";
 120
 121 And display the I<welcome> string:
 122
 123         print $loc{index}{welcome};
 124
 125 If the user wanted Dutch texts, it will show I<welkom>. In case the user wanted
 126 French for example, it will fallback to English.
 127
 128         print $loc{index}{["%d visits", ++$counter]};
 129
 130 =head1 SEE ALSO
 131
 132 L<Lirama::Loc|Lirama::Loc>
 133
 134 =head1 AUTHOR
 135
 136 Mischa POSLAWSKY <shiar@shiar.org>
 137
 138 Copyright 2005 Mischa POSLAWSKY. All rights reserved.
 139
 140 =cut