Text::Bidi - Unicode bidi algorithm using libfribidi
# Each displayed line is a "paragraph" use Text::Bidi qw(log2vis); ($par, $map, $visual) = log2vis($logical); # or just $visual = log2vis(...); # with real paragraphs: $p = new Text::Bidi::Paragraph $logical; $visual = $p->visual($off, $len);
The following functions can be exported (nothing is exported by default):
"log2vis()"
"is_bidi()"
"get_mirror_char()"
All of them can be exported together using the :all tag.
:all
This module provides basic support for the Unicode bidirectional (Bidi) text algorithm, for displaying text consisting of both left-to-right and right-to-left written languages (such as Hebrew and Arabic.) It does so via a swig interface file to the libfribidi library.
The fundamental purpose of the bidi algorithm is to reorder text given in logical order into text in visually correct order, suitable for display using standard printing commands. ``Logical order'' means that the characters are given in the order in which they would be read if printed correctly. The direction of the text is determined by properties of the unicode characters, usually without additional hints. See http://www.unicode.org/unicode/reports/tr9/ for more details on the problem and the algorithm.
The bidi algorithm works in two stages. The first is on the level of a paragraph, where the direction of each character is computed. The second is on the level of the lines to be displayed. The main practical difference is that the first stage requires only the text of the paragraph, while the second requires knowledge of the width of the displayed lines. The module (or the library) does not determine how the text is broken into paragraphs.
The main interface is provided by Text::Bidi::Paragraph, see there for details. This module provides an abreviation, "log2vis()", which combines creating a paragraph object with calling "visual" in Text::Bidi::Paragraph on it. It is particularly useful in the case that every line is a paragraph on its own:
$visual = log2vis($logical);
There are more options (see the corresponding section), but this is essentially it. The rest of this documentation will probably be useful only to people who are familiar with libfribidi and who wish to extend or modify the module.
All functions here can be called using either a procedural or an object oriented approach. For example, you may do either
or
$bidi = new Text::Bidi; $visual = $bidi->log2vis($logical);
The advantages of the second form is that it is easier to move to a sub-class, and that two or more objects with different parameters can be used simultaneously.
If you do sub-class this class, and want the procedural interface to use your functions, put a line like
$Text::Bidi::GlobalClass = __PACKAGE__;
in your module.
The following constants are imported from the fribidi library:
Constants of the form FRIBIDI_TYPE_FOO are available as $Text::Bidi::Type::FOO (note that, though these are variables, they are read-only)
$Text::Bidi::Type::FOO
Constants of the form FRIBIDI_MASK_FOO are converted to $Text::Bidi::Mask::FOO.
$Text::Bidi::Mask::FOO
Constants of the form FRIBIDI_PAR_FOO are converted to $Text::Bidi::Par::FOO.
$Text::Bidi::Par::FOO
Constants of the form FRIBIDI_FLAG_FOO are converted to $Text::Bidi::Flag::FOO.
$Text::Bidi::Flag::FOO
Constants of the form FRIBIDI_CHAR_FOO are converted to the character they represent, and assigned to $Text::Bidi::Char::FOO.
$Text::Bidi::Char::FOO
my $visual = log2vis($logical,...);
Treat the input $logical as a one line paragraph, and apply all stages of the algorithm to it. This works well if the paragraph does indeed span only one visual line. The other arguments are passed to "visual" in Text::Bidi::Paragraph, but this is probably worthless.
my $bidi = is_bidi($logical);
Returns true if the input $logical contains bidi characters. Otherwise, the output of the bidi algorithm will be identical to the input, hence this helps if we want to short-circuit.
my $mir = get_mirror_char('['); # $mir == ']'
Return the mirror character of the input, possibly itself.
There are no tests for any of this.
Shaping is not supported (probably), since I don't know what it is. Help welcome!
Text::Bidi::Paragraph
Encode
The fribidi library: http://fribidi.org/, http://imagic.weizmann.ac.il/~dov/freesw/FriBidi/
Swig: http://www.swig.org
The unicode bidi algorithm: http://www.unicode.org/unicode/reports/tr9/
Moshe Kamensky, mailto:kamensky@cpan.org
Copyright 2006-2013 Moshe Kamensky, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Text::Bidi, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Text::Bidi
CPAN shell
perl -MCPAN -e shell install Text::Bidi
For more information on module installation, please visit the detailed CPAN module installation guide.