Debian Codegraph @

README

raw
1 NAME
2
3 Text::Bidi - Unicode bidi algorithm using libfribidi
4
5 VERSION
6
7 version 2.18
8
9 SYNOPSIS
10
11 # Each displayed line is a "paragraph"
12 use Text::Bidi qw(log2vis);
13 ($par, $map, $visual) = log2vis($logical);
14 # or just
15 $visual = log2vis(...);
16
17 # For real paragraphs, need to specify the display width
18 ($par, $map, $visual) = log2vis($logical, $width);
19
20 # object oriented approach allows one to display line by line
21 $p = new Text::Bidi::Paragraph $logical;
22 $visual = $p->visual($off, $len);
23
24 EXPORT
25
26 The following functions can be exported (nothing is exported by
27 default):
28
29 * "log2vis"
30
31 * "is_bidi"
32
33 * "get_mirror_char"
34
35 * "get_bidi_type_name"
36
37 * "fribidi_version"
38
39 * "unicode_version"
40
41 * "fribidi_version_num"
42
43 All of them can be exported together using the :all tag.
44
45 DESCRIPTION
46
47 This module provides basic support for the Unicode bidirectional (Bidi)
48 text algorithm, for displaying text consisting of both left-to-right
49 and right-to-left written languages (such as Hebrew and Arabic.) It
50 does so via a swig interface file to the libfribidi library.
51
52 The fundamental purpose of the bidi algorithm is to reorder text given
53 in logical order into text in visually correct order, suitable for
54 display using standard printing commands. ``Logical order'' means that
55 the characters are given in the order in which they would be read if
56 printed correctly. The direction of the text is determined by
57 properties of the Unicode characters, usually without additional hints.
58 See http://www.unicode.org/unicode/reports/tr9/ for more details on the
59 problem and the algorithm.
60
61 Standard usage
62
63 The bidi algorithm works in two stages. The first is on the level of a
64 paragraph, where the direction of each character is computed. The
65 second is on the level of the lines to be displayed. The main practical
66 difference is that the first stage requires only the text of the
67 paragraph, while the second requires knowledge of the width of the
68 displayed lines. The module (or the library) does not determine how the
69 text is broken into paragraphs.
70
71 The full interface is provided by Text::Bidi::Paragraph, see there for
72 details. This module provides an abbreviation, "log2vis", which
73 combines creating a paragraph object with calling "visual" in
74 Text::Bidi::Paragraph on it. It is particularly useful in the case that
75 the whole paragraph should be displayed at once, and the display width
76 is known:
77
78 $visual = log2vis($logical, $width);
79
80 There are more options (see "log2vis"), but this is essentially it. The
81 rest of this documentation will probably be useful only to people who
82 are familiar with libfribidi and who wish to extend or modify the
83 module.
84
85 The object-oriented approach
86
87 All functions here can be called using either a procedural or an object
88 oriented approach. For example, you may do either
89
90 $visual = log2vis($logical);
91
92 or
93
94 $bidi = new Text::Bidi;
95 $visual = $bidi->log2vis($logical);
96
97 The advantages of the second form is that it is easier to move to a
98 sub-class, and that two or more objects with different parameters can
99 be used simultaneously. If you are interested in deriving from this
100 class, please see "SUBCLASSING".
101
102 FUNCTIONS
103
104 get_bidi_type_name
105
106 say $tb->get_bidi_type_name($Text::Bidi::Type::LTR); # says 'LTR'
107
108 Return the string representation of a Bidi character type, as in
109 fribidi_get_bidi_type_name(3). Note that for the above example, one
110 needs to use Text::Bidi::Constants.
111
112 log2vis
113
114 ($p, $visual) = log2vis($logical[,$width[,$dir[,$flags]]]);
115
116 Convert the input paragraph $logical to visual. This constructs a
117 Text::Bidi::Paragraph object, and calls "visual" in
118 Text::Bidi::Paragraph several times, as required. $width is the maximum
119 width of a line, defaulting to the whole length of the paragraph. $dir
120 is the base direction of the paragraph, determined automatically if not
121 provided. $flags is as in "visual" in Text::Bidi::Paragraph. The
122 paragraph will be justified to the right if it is RTL.
123
124 The output consists of the Text::Bidi::Paragraph object $p and the
125 visual string $visual.
126
127 is_bidi()
128
129 my $bidi = is_bidi($logical);
130
131 Returns true if the input $logical contains bidi characters. Otherwise,
132 the output of the bidi algorithm will be identical to the input, hence
133 this helps if we want to short-circuit.
134
135 get_mirror_char()
136
137 my $mir = get_mirror_char('['); # $mir == ']'
138
139 Return the mirror character of the input, possibly itself.
140
141 fribidi_version
142
143 say fribidi_version();
144
145 Returns the version information for the fribidi library
146
147 fribidi_version_num
148
149 say fribidi_version_num();
150
151 Returns the version number for the fribidi library
152
153 unicode_version
154
155 say unicode_version();
156
157 Returns the Unicode version used by the fribidi library
158
159 SUBCLASSING
160
161 The rest of the documentation is only interesting if you would like to
162 derive from this class. The methods listed under "METHODS" are wrappers
163 around the similarly named functions in libfribidi, and may be useful
164 for this purpose.
165
166 If you do sub-class this class, and would like the procedural interface
167 to use your functions, put a line like
168
169 $Text::Bidi::GlobalClass = __PACKAGE__;
170
171 in your module.
172
173 METHODS
174
175 new
176
177 $tb = new Text::Bidi [tie_byte => ..., tie_long => ...];
178
179 Create a new Text::Bidi object. If the tie_byte or tie_long options are
180 given, they should be the names (strings) of the classes used as dual
181 life arrays, most probably derived class of Text::Bidi::Array::Byte and
182 Text::Bidi::Array::Long, respectively.
183
184 This method is probably of little interest for standard (procedural)
185 use.
186
187 utf8_to_internal
188
189 $la = $tb->utf8_to_internal($str);
190
191 Convert the Perl string $str into the representation used by
192 libfribidi. The result will be a Text::Bidi::Array::Long.
193
194 internal_to_utf8
195
196 $str = $tb->internal_to_utf8($la);
197
198 Convert the long array $la, representing a string encoded in to format
199 used by libfribidi, into a Perl string. The array $la can be either a
200 Text::Bidi::Array::Long, or anything that can be used to construct it.
201
202 get_bidi_types
203
204 $types = $tb->get_bidi_types($internal);
205
206 Returns a Text::Bidi::Array::Long with the list of Bidi types of the
207 text given by $internal, a representation of the paragraph text, as
208 returned by utf8_to_internal(). Wraps fribidi_get_bidi_types(3).
209
210 get_joining_types
211
212 $types = $tb->get_joining_types($internal);
213
214 Returns a Text::Bidi::Array::Byte with the list of joining types of the
215 text given by $internal, a representation of the paragraph text, as
216 returned by "utf8_to_internal". Wraps fribidi_get_joining_types(3).
217
218 get_joining_type_name
219
220 say $tb->get_joining_type_name($Text::Bidi::Joining::U); # says 'U'
221
222 Return the string representation of a joining character type, as in
223 fribidi_get_joining_type_name(3). Note that for the above example, one
224 needs to use Text::Bidi::Constants.
225
226 get_par_embedding_levels
227
228 ($odir, $lvl) = $tb->get_par_embedding_levels($types[, $dir]);
229
230 Return the embedding levels of the characters, whose types are given by
231 $types. $types is a Text::Bidi::Array::Long of Bidi types, as returned
232 by "get_bidi_types". $dir is the base paragraph direction. If not
233 given, it defaults to FRIBIDI_PAR_ON (neutral).
234
235 The output is the resolved paragraph direction $odir, and the
236 Text::Bidi::Array::Byte array $lvl of embedding levels.
237
238 join_arabic
239
240 $props = $tb->join_arabic($bidi_types, $lvl, $join_types);
241
242 Returns a Text::Bidi::Array::Byte with $props, as returned by
243 fribidi_join_arabic(3). The inputs are $bidi_types, as returned by
244 "get_bidi_types", $lvl, as returned by "get_par_embedding_levels", and
245 $join_types as returned by "get_joining_types". Wraps
246 fribidi_join_arabic(3).
247
248 shaped
249
250 ($newp, $shaped) = $tb->shaped($flags, $lvl, $prop, $internal);
251
252 Returns the internal representation of the paragraph, with shaping
253 applied. The internal representation of the original paragraph (as
254 returned by "utf8_to_internal") should be passed in $internal, while
255 the embedding levels (as returned by "get_par_embedding_levels") should
256 be in $lvl. See the documentation of fribidi-arabic.h for $flags, but
257 as a special case, a value of undef here skips shaping (returning
258 ($prop, $internal)), while any other false value becomes the default.
259 $prop is as returned by "join_arabic". This method wraps
260 fribidi_shape_arabic(3).
261
262 mirrored
263
264 $mirrored = $tb->mirrored($lvl, $internal);
265
266 Returns the internal representation of the paragraph, with mirroring
267 applied. The internal representation of the original paragraph (as
268 returned by "utf8_to_internal") should be passed in $internal, while
269 the embedding levels (as returned by "get_par_embedding_levels") should
270 be in $lvl. This method wraps fribidi_shape_mirroring(3).
271
272 reorder
273
274 $str = $tb->reorder($in, $map[, $offset[, $len]]);
275 say $tb->reorder([qw(A B C)], [2, 0, 1]); # says CAB
276
277 View the array ref $map as a permutation, and permute the list (of
278 characters) $in according to it. The result is joined, to obtain a
279 string. If $offset and $len are given, returns only that part of the
280 resulting string.
281
282 reorder_map
283
284 ($elout, $mout) = $tb->reorder_map($types, $offset, $len, $par,
285 $map, $el, $flags);
286
287 Compute the reordering map for bidi types given by $types, for the
288 interval starting with $offset of length $len. Note that this part of
289 the algorithm depends on the interval in an essential way. $types is an
290 array of types, as computed by "get_bidi_types". The other arguments
291 are optional:
292
293 $par
294
295 The base paragraph direction. Computed via "get_par_embedding_levels"
296 if not defined.
297
298 $map
299
300 An array ref (or a Text::Bidi::Array::Long) from a previous call
301 (with a different interval). The method is called repeatedly for the
302 same paragraph, with different intervals, and the reordering map is
303 updated for the given interval. If not defined, initialised to the
304 identity map.
305
306 $el
307
308 The embedding levels. If not given, computed by a call to
309 "get_par_embedding_levels".
310
311 $flags
312
313 A specification of flags, as described in fribidi_reorder_line(3).
314 The flags can be given either as a number (using
315 $Text::Bidi::Flags::.. from Text::Bidi::Constants), or as a hashref
316 of the form {REORDER_NSM => 1}. Defaults to FRIBIDI_FLAGS_DEFAULT.
317
318 The output consists of the modified map $mout (a
319 Text::Bidi::Array::Long), and possibly modified embedding levels
320 $elout.
321
322 method remove_bidi_marks
323
324 ($v, $to, $from, $levels) =
325 $tb->remove_bidi_marks($v[, $to[, $from[, $levels]]])
326
327 Remove the explicit bidi marks from $v. The optional arguments, if
328 given, are the map from the logical to the visual string, the inverse
329 map, and embedding levels, respectively, as returned by "reorder_map".
330 The inverse map $from can be obtained from the direct one $to by a
331 command like:
332
333 @$from[@$map] = 0..$#$map
334
335 Each of the arguments can be undef, in which case it will be skipped.
336 This implements step X9, see fribidi_remove_bidi_marks(3).
337
338 BUGS
339
340 There are no real tests for any of this.
341
342 Shaping is not supported (probably), since I don't know what it is.
343 Help welcome!
344
345 SEE ALSO
346
347 Text::Bidi::Paragraph
348
349 Text::Bidi::Constants
350
351 Encode
352
353 The fribidi library <http://fribidi.org/>
354
355 Swig <http://www.swig.org>
356
357 The unicode bidi algorithm
358 <http://www.unicode.org/unicode/reports/tr9/>
359
360 AUTHOR
361
362 Moshe Kamensky <[email protected]>
363
364 COPYRIGHT AND LICENSE
365
366 This software is copyright (c) 2015 by Moshe Kamensky.
367
368 This is free software; you can redistribute it and/or modify it under
369 the same terms as the Perl 5 programming language system itself.
370