1Text::Bidi(3)         User Contributed Perl Documentation        Text::Bidi(3)
2
3
4

NAME

6       Text::Bidi - Unicode bidi algorithm using libfribidi
7

VERSION

9       version 2.18
10

SYNOPSIS

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
18           # For real paragraphs, need to specify the display width
19           ($par, $map, $visual) = log2vis($logical, $width);
20
21           # object oriented approach allows one to display line by line
22           $p = new Text::Bidi::Paragraph $logical;
23           $visual = $p->visual($off, $len);
24

EXPORT

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

DESCRIPTION

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
51       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
60   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
69       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
76           $visual = log2vis($logical, $width);
77
78       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
83   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
87               $visual = log2vis($logical);
88
89       or
90
91               $bidi = new Text::Bidi;
92               $visual = $bidi->log2vis($logical);
93
94       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

FUNCTIONS

100   get_bidi_type_name
101           say $tb->get_bidi_type_name($Text::Bidi::Type::LTR); # says 'LTR'
102
103       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
107   log2vis
108           ($p, $visual) = log2vis($logical[,$width[,$dir[,$flags]]]);
109
110       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
118       The output consists of the Text::Bidi::Paragraph object $p and the
119       visual string $visual.
120
121   is_bidi()
122           my $bidi = is_bidi($logical);
123
124       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
128   get_mirror_char()
129           my $mir = get_mirror_char('['); # $mir == ']'
130
131       Return the mirror character of the input, possibly itself.
132
133   fribidi_version
134           say fribidi_version();
135
136       Returns the version information for the fribidi library
137
138   fribidi_version_num
139           say fribidi_version_num();
140
141       Returns the version number for the fribidi library
142
143   unicode_version
144           say unicode_version();
145
146       Returns the Unicode version used by the fribidi library
147

SUBCLASSING

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
154       If you do sub-class this class, and would like the procedural interface
155       to use your functions, put a line like
156
157               $Text::Bidi::GlobalClass = __PACKAGE__;
158
159       in your module.
160

METHODS

162   new
163           $tb = new Text::Bidi [tie_byte => ..., tie_long => ...];
164
165       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
170       This method is probably of little interest for standard (procedural)
171       use.
172
173   utf8_to_internal
174           $la = $tb->utf8_to_internal($str);
175
176       Convert the Perl string $str into the representation used by
177       libfribidi.  The result will be a Text::Bidi::Array::Long.
178
179   internal_to_utf8
180           $str = $tb->internal_to_utf8($la);
181
182       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
186   get_bidi_types
187           $types = $tb->get_bidi_types($internal);
188
189       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
193   get_joining_types
194           $types = $tb->get_joining_types($internal);
195
196       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
200   get_joining_type_name
201           say $tb->get_joining_type_name($Text::Bidi::Joining::U); # says 'U'
202
203       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
207   get_par_embedding_levels
208          ($odir, $lvl) = $tb->get_par_embedding_levels($types[, $dir]);
209
210       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
215       The output is the resolved paragraph direction $odir, and the
216       Text::Bidi::Array::Byte array $lvl of embedding levels.
217
218   join_arabic
219           $props = $tb->join_arabic($bidi_types, $lvl, $join_types);
220
221       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
227   shaped
228           ($newp, $shaped) = $tb->shaped($flags, $lvl, $prop, $internal);
229
230       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
240   mirrored
241           $mirrored = $tb->mirrored($lvl, $internal);
242
243       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
249   reorder
250           $str = $tb->reorder($in, $map[, $offset[, $len]]);
251           say $tb->reorder([qw(A B C)], [2, 0, 1]); # says CAB
252
253       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
258   reorder_map
259           ($elout, $mout) = $tb->reorder_map($types, $offset, $len, $par,
260                                              $map, $el, $flags);
261
262       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
268       $par
269           The base paragraph direction. Computed via
270           "get_par_embedding_levels" if not defined.
271
272       $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
279       $el The embedding levels. If not given, computed by a call to
280           "get_par_embedding_levels".
281
282       $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
289       The output consists of the modified map $mout (a
290       Text::Bidi::Array::Long), and possibly modified embedding levels
291       $elout.
292
293       method remove_bidi_marks
294
295           ($v, $to, $from, $levels) =
296               $tb->remove_bidi_marks($v[, $to[, $from[, $levels]]])
297
298       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
304           @$from[@$map] = 0..$#$map
305
306       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

BUGS

310       There are no real tests for any of this.
311
312       Shaping is not supported (probably), since I don't know what it is.
313       Help welcome!
314

SEE ALSO

316       Text::Bidi::Paragraph
317
318       Text::Bidi::Constants
319
320       Encode
321
322       The fribidi library <http://fribidi.org/>
323
324       Swig <http://www.swig.org>
325
326       The unicode bidi algorithm
327       <http://www.unicode.org/unicode/reports/tr9/>
328

AUTHOR

330       Moshe Kamensky <kamensky@cpan.org>
331
333       This software is copyright (c) 2015 by Moshe Kamensky.
334
335       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.
337
338
339
340perl v5.36.0                      2022-07-28                     Text::Bidi(3)
Impressum