This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
From: Todd Rinaldo <toddr@cpanel.net>
[perl5.git] / dist / Locale-Maketext / lib / Locale / Maketext / Cookbook.pod
1 # This document contains text in Perl "POD" format.
2 # Use a POD viewer like perldoc or perlman to render it.
3
4 =encoding utf-8
5
6 =head1 NAME
7
8 Locale::Maketext::Cookbook - recipes for using Locale::Maketext
9
10 =head1 INTRODUCTION
11
12 This is a work in progress. Not much progress by now :-)
13
14 =head1 ONESIDED LEXICONS
15
16 I<Adapted from a suggestion by Dan Muey>
17
18 It may be common (for example at your main lexicon) that
19 the hash keys and values coincide. Like that
20
21     q{Hello, tell me your name} 
22       => q{Hello, tell me your name}
23
24 It would be nice to just write:
25
26     q{Hello, tell me your name} => ''
27
28 and have this magically inflated to the first form.
29 Among the advantages of such representation, that would
30 lead to  
31 smaller files, less prone to mistyping or mispasting, 
32 and handy to someone translating it which can simply 
33 copy the main lexicon and enter the translation 
34 instead of having to remove the value first.
35
36 That can be achieved by overriding C<init>
37 in your class and working on the main lexicon
38 with code like that:
39
40     package My::I18N;
41     ...
42
43     sub init {
44         my $lh = shift; # a newborn handle
45         $lh->SUPER::init();
46         inflate_lexicon(\%My::I18N::en::Lexicon);
47         return;
48     }
49
50     sub inflate_lexicon {
51         my $lex = shift;
52         while (my ($k, $v) = each %$lex) {
53             $v = $k if !defined $v || $v eq '';
54         }
55     }
56
57 Here we are assuming C<My::I18N::en> to own the
58 main lexicon.
59
60 There are some downsides here: the size economy
61 will not stand at runtime after this C<init()>
62 runs. But it should not be that critical, since
63 if you don't have space for that, you won't have
64 space for any other language besides the main one
65 as well. You could do that too with ties,
66 expanding the value at lookup time which
67 should be more time expensive as an option.
68
69 =head1 DECIMAL PLACES IN NUMBER FORMATTING
70
71 I<After CPAN RT #36136 (https://rt.cpan.org/Ticket/Display.html?id=36136)>
72
73 The documentation of L<Locale::Maketext> advises that 
74 the standard bracket method C<numf> is limited and that
75 you must override that for better results. It even
76 suggests the use of L<Number::Format>.
77
78 One such defect of standard C<numf> is to not be
79 able to use a certain decimal precision.
80 For example, 
81
82     $lh->maketext('pi is [numf,_1]', 355/113);
83
84 outputs
85
86     pi is 3.14159292035398 
87
88 Since pi ≈ 355/116 is only accurate 
89 to 6 decimal places, you would want to say:
90
91     $lh->maketext('pi is [numf,_1,6]', 355/113); 
92
93 and get "pi is 3.141592".
94
95 One solution for that could use C<Number::Format>
96 like that:
97
98     package Wuu;
99
100     use base qw(Locale::Maketext);
101
102     use Number::Format;
103
104     # can be overriden according to language conventions
105     sub _numf_params {
106         return (
107             -thousands_sep  => '.',
108             -decimal_point  => ',',
109             -decimal_digits => 2,
110         );
111     }
112
113     # builds a Number::Format
114     sub _numf_formatter {
115         my ($lh, $scale) = @_;
116         my @params = $lh->_numf_params;
117         if ($scale) { # use explicit scale rather than default
118             push @params, (-decimal_digits => $scale);
119         }
120         return Number::Format->new(@params);
121     }
122
123     sub numf {
124         my ($lh, $n, $scale) = @_;
125         # get the (cached) formatter
126         my $nf = $lh->{__nf}{$scale} ||= $lh->_numf_formatter($scale);
127         # format the number itself
128         return $nf->format_number($n);
129     }
130
131     package Wuu::pt;
132
133     use base qw(Wuu);
134
135 and then 
136
137     my $lh = Wuu->get_handle('pt');
138     $lh->maketext('A [numf,_1,3] km de distância', 1550.2222);
139
140 would return "A 1.550,222 km de distância".
141
142 Notice that the standard utility methods of 
143 C<Locale::Maketext> are irremediably limited
144 because they could not aim to do everything
145 that could be expected from them in different languages,
146 cultures and applications. So extending C<numf>,
147 C<quant>, and C<sprintf> is natural as soon
148 as your needs exceed what the standard ones do.
149
150