Lirama::Loc2

[perl/loc/.git] / Lirama / Loc2 / Auto.pm

diff --git a/Lirama/Loc2/Auto.pm b/Lirama/Loc2/Auto.pm
new file mode 100644 (file)
index 0000000..f5a5340
--- /dev/null
+++ b/Lirama/Loc2/Auto.pm
@@ -0,0 +1,140 @@
+package Lirama::Loc2::Auto;
+
+use strict;
+use warnings;
+use utf8;
+
+use Lirama::Loc2;
+
+our $VERSION = '2.00';
+
+sub optimize {
+       my $self = shift;
+       $self->[1]{optimize} = $_[0] if @_;
+       return $self->[1]{optimize};
+} # optimize
+
+sub TIEHASH {
+       my ($class, $path, @langpref) = @_;
+
+       my $langs = @langpref>0;  # languages specified
+       langpref(@langpref) if $langs;  # set default language preference
+
+       my $node = [  # array for faster access to common [0]
+               {},  # files
+               {    # configuration
+                       path     => $path,
+                       optimize => $langs,  # assume langpref won't change if specified
+               }
+       ];
+       return bless $node, $class;
+} # new
+
+sub FETCH {
+       my ($self, $file) = @_;
+
+       unless (exists $self->[0]{$file}) {
+               my $filename = $self->[1]{path}.'/'.$file;  # perl file returning l10n hash
+               my $extlang  = '.'.langpref();  # file tag for the preferred language
+               my $ext      = ".pl";  # extension for $filename
+
+               $filename .= $extlang  # get language-optimized file
+                       if $self->[1]{optimize} and -r $filename.$extlang.$ext;
+
+               tie %{$self->[0]{$file}}, "Lirama::Loc2", do $filename.$ext;
+       } # initialize Loc for this file
+
+       return $self->[0]{$file}
+} # FETCH
+
+# Basically same as Tie::StdHash
+
+sub EXISTS   { exists $_[0]->[0]{$_[1]} }
+sub FIRSTKEY { my $a = scalar keys %{$_[0]->[0]}; each %{$_[0]->[0]} }
+sub NEXTKEY  { each %{$_[0]->[0]} }
+
+1;
+
+__END__
+
+
+=head1 NAME
+
+Lirama::Loc::Auto - Localize strings, initialize automatically
+
+=head1 SYNOPSIS
+
+       use Lirama::Loc::Auto;
+
+       tie my %L, "Lirama::Loc::Auto", "path/to/translation/files", "en";
+
+       print $L{numbers}{7};  # "seven"
+
+=head1 DESCRIPTION
+
+Setup a hash containing multiple L<Lirama::Loc|Lirama::Loc> objects, which
+open automatically on demand.
+
+=over 4
+
+=item C<tie %tie, "Lirama::Loc::Auto", $path, @languages>
+
+Will setup a hash to automatically load data files from P<$path/*.pl>.
+These files should only return an anonimous translation hash.
+
+If @languages is set, it will be taken as the default language preference.
+[todo:optimize]
+
+=item C<$tie{$file}{$string}>
+
+The first time a translation is accessed from C<$tie{$file}{$string}>, it will
+create a Lirama::Loc object from P<$path/$file.pl>.
+
+=item C<optimize>
+
+=item C<exists>
+
+bla
+
+=back
+
+=head1 EXAMPLE
+
+We'll create P<./includes/loc/index.pl> with the following contents:
+
+       {
+               welcome => {
+                       en => "welcome",
+                       eo => "bonvenon",
+                       nl => "welkom",
+               },
+               "%d visits" => {
+                       en => sub { "%d user".($_[0]!=1 && "s")." have visited this site." },
+               },
+       }
+
+Setup a hash with user defined language preferences, and a fallback to English.
+
+       my @langpref = split(',', $ENV{HTTP_ACCEPT_LANGUAGE});
+       tie my %loc, "Lirama::Loc::Auto", "includes/loc", @langpref, "en";
+
+And display the I<welcome> string:
+
+       print $loc{index}{welcome};
+
+If the user wanted Dutch texts, it will show I<welkom>. In case the user wanted
+French for example, it will fallback to English.
+
+       print $loc{index}{["%d visits", ++$counter]};
+
+=head1 SEE ALSO
+
+L<Lirama::Loc|Lirama::Loc>
+
+=head1 AUTHOR
+
+Mischa POSLAWSKY <shiar@shiar.org>
+
+Copyright 2005 Mischa POSLAWSKY. All rights reserved.
+
+=cut