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