Debian Codegraph @

upstream/debian-unstable/man3/Locale::Maketext::Cookbook.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "Locale::Maketext::Cookbook 3perl"
58 .TH Locale::Maketext::Cookbook 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Locale::Maketext::Cookbook \- recipes for using Locale::Maketext
65 .SH INTRODUCTION
66 .IX Header "INTRODUCTION"
67 This is a work in progress. Not much progress by now :\-)
68 .SH "ONESIDED LEXICONS"
69 .IX Header "ONESIDED LEXICONS"
70 \&\fIAdapted from a suggestion by Dan Muey\fR
71 .PP
72 It may be common (for example at your main lexicon) that
73 the hash keys and values coincide. Like that
74 .PP
75 .Vb 2
76 \& q{Hello, tell me your name}
77 \& => q{Hello, tell me your name}
78 .Ve
79 .PP
80 It would be nice to just write:
81 .PP
82 .Vb 1
83 \& q{Hello, tell me your name} => \*(Aq\*(Aq
84 .Ve
85 .PP
86 and have this magically inflated to the first form.
87 Among the advantages of such representation, that would
88 lead to
89 smaller files, less prone to mistyping or mispasting,
90 and handy to someone translating it which can simply
91 copy the main lexicon and enter the translation
92 instead of having to remove the value first.
93 .PP
94 That can be achieved by overriding \f(CW\*(C`init\*(C'\fR
95 in your class and working on the main lexicon
96 with code like that:
97 .PP
98 .Vb 2
99 \& package My::I18N;
100 \& ...
101 \&
102 \& sub init {
103 \& my $lh = shift; # a newborn handle
104 \& $lh\->SUPER::init();
105 \& inflate_lexicon(\e%My::I18N::en::Lexicon);
106 \& return;
107 \& }
108 \&
109 \& sub inflate_lexicon {
110 \& my $lex = shift;
111 \& while (my ($k, $v) = each %$lex) {
112 \& $v = $k if !defined $v || $v eq \*(Aq\*(Aq;
113 \& }
114 \& }
115 .Ve
116 .PP
117 Here we are assuming \f(CW\*(C`My::I18N::en\*(C'\fR to own the
118 main lexicon.
119 .PP
120 There are some downsides here: the size economy
121 will not stand at runtime after this \f(CWinit()\fR
122 runs. But it should not be that critical, since
123 if you don't have space for that, you won't have
124 space for any other language besides the main one
125 as well. You could do that too with ties,
126 expanding the value at lookup time which
127 should be more time expensive as an option.
128 .SH "DECIMAL PLACES IN NUMBER FORMATTING"
129 .IX Header "DECIMAL PLACES IN NUMBER FORMATTING"
130 \&\fIAfter CPAN RT #36136 (<https://rt.cpan.org/Ticket/Display.html?id=36136>)\fR
131 .PP
132 The documentation of Locale::Maketext advises that
133 the standard bracket method \f(CW\*(C`numf\*(C'\fR is limited and that
134 you must override that for better results. It even
135 suggests the use of Number::Format.
136 .PP
137 One such defect of standard \f(CW\*(C`numf\*(C'\fR is to not be
138 able to use a certain decimal precision.
139 For example,
140 .PP
141 .Vb 1
142 \& $lh\->maketext(\*(Aqpi is [numf,_1]\*(Aq, 355/113);
143 .Ve
144 .PP
145 outputs
146 .PP
147 .Vb 1
148 \& pi is 3.14159292035398
149 .Ve
150 .PP
151 Since pi ≈ 355/116 is only accurate
152 to 6 decimal places, you would want to say:
153 .PP
154 .Vb 1
155 \& $lh\->maketext(\*(Aqpi is [numf,_1,6]\*(Aq, 355/113);
156 .Ve
157 .PP
158 and get "pi is 3.141592".
159 .PP
160 One solution for that could use \f(CW\*(C`Number::Format\*(C'\fR
161 like that:
162 .PP
163 .Vb 1
164 \& package Wuu;
165 \&
166 \& use base qw(Locale::Maketext);
167 \&
168 \& use Number::Format;
169 \&
170 \& # can be overridden according to language conventions
171 \& sub _numf_params {
172 \& return (
173 \& \-thousands_sep => \*(Aq.\*(Aq,
174 \& \-decimal_point => \*(Aq,\*(Aq,
175 \& \-decimal_digits => 2,
176 \& );
177 \& }
178 \&
179 \& # builds a Number::Format
180 \& sub _numf_formatter {
181 \& my ($lh, $scale) = @_;
182 \& my @params = $lh\->_numf_params;
183 \& if ($scale) { # use explicit scale rather than default
184 \& push @params, (\-decimal_digits => $scale);
185 \& }
186 \& return Number::Format\->new(@params);
187 \& }
188 \&
189 \& sub numf {
190 \& my ($lh, $n, $scale) = @_;
191 \& # get the (cached) formatter
192 \& my $nf = $lh\->{_\|_nf}{$scale} ||= $lh\->_numf_formatter($scale);
193 \& # format the number itself
194 \& return $nf\->format_number($n);
195 \& }
196 \&
197 \& package Wuu::pt;
198 \&
199 \& use base qw(Wuu);
200 .Ve
201 .PP
202 and then
203 .PP
204 .Vb 2
205 \& my $lh = Wuu\->get_handle(\*(Aqpt\*(Aq);
206 \& $lh\->maketext(\*(AqA [numf,_1,3] km de distância\*(Aq, 1550.2222);
207 .Ve
208 .PP
209 would return "A 1.550,222 km de distância".
210 .PP
211 Notice that the standard utility methods of
212 \&\f(CW\*(C`Locale::Maketext\*(C'\fR are irremediably limited
213 because they could not aim to do everything
214 that could be expected from them in different languages,
215 cultures and applications. So extending \f(CW\*(C`numf\*(C'\fR,
216 \&\f(CW\*(C`quant\*(C'\fR, and \f(CW\*(C`sprintf\*(C'\fR is natural as soon
217 as your needs exceed what the standard ones do.