.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Text::Bidi 3pm"
.TH Text::Bidi 3pm 2024-01-10 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Text::Bidi \- Unicode bidi algorithm using libfribidi
.SH VERSION
.IX Header "VERSION"
version 2.18
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 5
\&    # Each displayed line is a "paragraph"
\&    use Text::Bidi qw(log2vis);
\&    ($par, $map, $visual) = log2vis($logical);
\&    # or just
\&    $visual = log2vis(...);
\&
\&    # For real paragraphs, need to specify the display width
\&    ($par, $map, $visual) = log2vis($logical, $width);
\&
\&    # object oriented approach allows one to display line by line
\&    $p = new Text::Bidi::Paragraph $logical;
\&    $visual = $p\->visual($off, $len);
.Ve
.SH EXPORT
.IX Header "EXPORT"
The following functions can be exported (nothing is exported by default):
.IP \(bu 4
"log2vis"
.IP \(bu 4
"is_bidi"
.IP \(bu 4
"get_mirror_char"
.IP \(bu 4
"get_bidi_type_name"
.IP \(bu 4
"fribidi_version"
.IP \(bu 4
"unicode_version"
.IP \(bu 4
"fribidi_version_num"
.PP
All of them can be exported together using the \f(CW\*(C`:all\*(C'\fR tag.
.SH DESCRIPTION
.IX Header "DESCRIPTION"
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 \fIswig\fR interface file to the \fIlibfribidi\fR library.
.PP
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.
.SS "Standard usage"
.IX Subsection "Standard usage"
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.
.PP
The full interface is provided by Text::Bidi::Paragraph, see there for 
details. This module provides an abbreviation, "log2vis", which combines 
creating a paragraph object with calling "visual" in Text::Bidi::Paragraph on 
it.  It is particularly useful in the case that the whole paragraph should be 
displayed at once, and the display width is known:
.PP
.Vb 1
\&    $visual = log2vis($logical, $width);
.Ve
.PP
There are more options (see "log2vis"), but this is essentially it. The 
rest of this documentation will probably be useful only to people who are 
familiar with \fIlibfribidi\fR and who wish to extend or modify the module.
.SS "The object-oriented approach"
.IX Subsection "The object-oriented approach"
All functions here can be called using either a procedural or an object 
oriented approach. For example, you may do either
.PP
.Vb 1
\&        $visual = log2vis($logical);
.Ve
.PP
or
.PP
.Vb 2
\&        $bidi = new Text::Bidi;
\&        $visual = $bidi\->log2vis($logical);
.Ve
.PP
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 are interested in deriving from this class, please see 
"SUBCLASSING".
.SH FUNCTIONS
.IX Header "FUNCTIONS"
.SS get_bidi_type_name
.IX Subsection "get_bidi_type_name"
.Vb 1
\&    say $tb\->get_bidi_type_name($Text::Bidi::Type::LTR); # says \*(AqLTR\*(Aq
.Ve
.PP
Return the string representation of a Bidi character type, as in 
\&\fBfribidi_get_bidi_type_name\fR\|(3). Note that for the above example, one needs to 
use Text::Bidi::Constants.
.SS log2vis
.IX Subsection "log2vis"
.Vb 1
\&    ($p, $visual) = log2vis($logical[,$width[,$dir[,$flags]]]);
.Ve
.PP
Convert the input paragraph \fR\f(CB$logical\fR\fB\fR to visual. This constructs a 
Text::Bidi::Paragraph object, and calls "visual" in Text::Bidi::Paragraph 
several times, as required. \fB\fR\f(CB$width\fR\fB\fR is the maximum width of a line, 
defaulting to the whole length of the paragraph.  \fB\fR\f(CB$dir\fR\fB\fR is the base 
direction of the paragraph, determined automatically if not provided.  
\&\fB\fR\f(CB$flags\fR\fB\fR is as in "visual" in Text::Bidi::Paragraph. The paragraph will be 
justified to the right if it is RTL.
.PP
The output consists of the Text::Bidi::Paragraph object \fR\f(CB$p\fR\fB\fR and the 
visual string \fB\fR\f(CB$visual\fR\fB\fR.
.SS \fBis_bidi()\fP
.IX Subsection "is_bidi()"
.Vb 1
\&    my $bidi = is_bidi($logical);
.Ve
.PP
Returns true if the input \fR\f(CB$logical\fR\fB\fR 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.
.SS \fBget_mirror_char()\fP
.IX Subsection "get_mirror_char()"
.Vb 1
\&    my $mir = get_mirror_char(\*(Aq[\*(Aq); # $mir == \*(Aq]\*(Aq
.Ve
.PP
Return the mirror character of the input, possibly itself.
.SS fribidi_version
.IX Subsection "fribidi_version"
.Vb 1
\&    say fribidi_version();
.Ve
.PP
Returns the version information for the fribidi library
.SS fribidi_version_num
.IX Subsection "fribidi_version_num"
.Vb 1
\&    say fribidi_version_num();
.Ve
.PP
Returns the version number for the fribidi library
.SS unicode_version
.IX Subsection "unicode_version"
.Vb 1
\&    say unicode_version();
.Ve
.PP
Returns the Unicode version used by the fribidi library
.SH SUBCLASSING
.IX Header "SUBCLASSING"
The rest of the documentation is only interesting if you would like to derive 
from this class. The methods listed under "METHODS" are wrappers around the 
similarly named functions in libfribidi, and may be useful for this purpose.
.PP
If you do sub-class this class, and would like the procedural interface to 
use your functions, put a line like
.PP
.Vb 1
\&        $Text::Bidi::GlobalClass = _\|_PACKAGE_\|_;
.Ve
.PP
in your module.
.SH METHODS
.IX Header "METHODS"
.SS new
.IX Subsection "new"
.Vb 1
\&    $tb = new Text::Bidi [tie_byte => ..., tie_long => ...];
.Ve
.PP
Create a new Text::Bidi object. If the \fItie_byte\fR or \fItie_long\fR options 
are given, they should be the names (strings) of the classes used as dual 
life arrays, most probably derived class of Text::Bidi::Array::Byte and 
Text::Bidi::Array::Long, respectively.
.PP
This method is probably of little interest for standard (procedural) use.
.SS utf8_to_internal
.IX Subsection "utf8_to_internal"
.Vb 1
\&    $la = $tb\->utf8_to_internal($str);
.Ve
.PP
Convert the Perl string \fR\f(CI$str\fR\fI\fR into the representation used by libfribidi.  
The result will be a Text::Bidi::Array::Long.
.SS internal_to_utf8
.IX Subsection "internal_to_utf8"
.Vb 1
\&    $str = $tb\->internal_to_utf8($la);
.Ve
.PP
Convert the long array \fR\f(CI$la\fR\fI\fR, representing a string encoded in to format 
used by libfribidi, into a Perl string. The array \fI\fR\f(CI$la\fR\fI\fR can be either a 
Text::Bidi::Array::Long, or anything that can be used to construct it.
.SS get_bidi_types
.IX Subsection "get_bidi_types"
.Vb 1
\&    $types = $tb\->get_bidi_types($internal);
.Ve
.PP
Returns a Text::Bidi::Array::Long with the list of Bidi types of the text 
given by \f(CW$internal\fR, a representation of the paragraph text, as returned by 
\&\fButf8_to_internal()\fR. Wraps \fBfribidi_get_bidi_types\fR\|(3).
.SS get_joining_types
.IX Subsection "get_joining_types"
.Vb 1
\&    $types = $tb\->get_joining_types($internal);
.Ve
.PP
Returns a Text::Bidi::Array::Byte with the list of joining types of the 
text given by \fR\f(CB$internal\fR\fB\fR, a representation of the paragraph text, as returned 
by "utf8_to_internal". Wraps \fBfribidi_get_joining_types\fR\|(3).
.SS get_joining_type_name
.IX Subsection "get_joining_type_name"
.Vb 1
\&    say $tb\->get_joining_type_name($Text::Bidi::Joining::U); # says \*(AqU\*(Aq
.Ve
.PP
Return the string representation of a joining character type, as in 
\&\fBfribidi_get_joining_type_name\fR\|(3). Note that for the above example, one needs 
to use Text::Bidi::Constants.
.SS get_par_embedding_levels
.IX Subsection "get_par_embedding_levels"
.Vb 1
\&   ($odir, $lvl) = $tb\->get_par_embedding_levels($types[, $dir]);
.Ve
.PP
Return the embedding levels of the characters, whose types are given by 
\&\fR\f(CI$types\fR\fI\fR. \fI\fR\f(CI$types\fR\fI\fR is a Text::Bidi::Array::Long of Bidi types, as 
returned by "get_bidi_types". \fI\fR\f(CI$dir\fR\fI\fR is the base paragraph direction. If 
not given, it defaults to \f(CW\*(C`FRIBIDI_PAR_ON\*(C'\fR (neutral).
.PP
The output is the resolved paragraph direction \fR\f(CI$odir\fR\fI\fR, and the 
Text::Bidi::Array::Byte array \fI\fR\f(CI$lvl\fR\fI\fR of embedding levels.
.SS join_arabic
.IX Subsection "join_arabic"
.Vb 1
\&    $props = $tb\->join_arabic($bidi_types, $lvl, $join_types);
.Ve
.PP
Returns a Text::Bidi::Array::Byte with \fR\f(CB$props\fR\fB\fR, as returned by 
\&\fBfribidi_join_arabic\fR\|(3). The inputs are \fB\fR\f(CB$bidi_types\fR\fB\fR, as returned by 
"get_bidi_types", \fB\fR\f(CB$lvl\fR\fB\fR, as returned by 
"get_par_embedding_levels", and \fB\fR\f(CB$join_types\fR\fB\fR as returned by
"get_joining_types".  Wraps \fBfribidi_join_arabic\fR\|(3).
.SS shaped
.IX Subsection "shaped"
.Vb 1
\&    ($newp, $shaped) = $tb\->shaped($flags, $lvl, $prop, $internal);
.Ve
.PP
Returns the internal representation of the paragraph, with shaping applied.  
The internal representation of the original paragraph (as returned by 
"utf8_to_internal") should be passed in \fR\f(CB$internal\fR\fB\fR, while the embedding 
levels (as returned by "get_par_embedding_levels") should be in \fB\fR\f(CB$lvl\fR\fB\fR. 
See the documentation of \fIfribidi\-arabic.h\fR for \fB\fR\f(CB$flags\fR\fB\fR, but as a special
case, a value of \f(CW\*(C`undef\*(C'\fR here skips shaping (returning \fB($prop, \fR\f(CB$internal\fR\fB)\fR),
while any other false value becomes the default. \fB\fR\f(CB$prop\fR\fB\fR is as 
returned by "join_arabic".  This method wraps \fBfribidi_shape_arabic\fR\|(3).
.SS mirrored
.IX Subsection "mirrored"
.Vb 1
\&    $mirrored = $tb\->mirrored($lvl, $internal);
.Ve
.PP
Returns the internal representation of the paragraph, with mirroring applied.  
The internal representation of the original paragraph (as returned by 
"utf8_to_internal") should be passed in \fR\f(CB$internal\fR\fB\fR, while the embedding 
levels (as returned by "get_par_embedding_levels") should be in \fB\fR\f(CB$lvl\fR\fB\fR.  
This method wraps \fBfribidi_shape_mirroring\fR\|(3).
.SS reorder
.IX Subsection "reorder"
.Vb 2
\&    $str = $tb\->reorder($in, $map[, $offset[, $len]]);
\&    say $tb\->reorder([qw(A B C)], [2, 0, 1]); # says CAB
.Ve
.PP
View the array ref \fR\f(CB$map\fR\fB\fR as a permutation, and permute the list (of 
characters) \fB\fR\f(CB$in\fR\fB\fR according to it. The result is joined, to obtain a string. 
If \fB\fR\f(CB$offset\fR\fB\fR and \fB\fR\f(CB$len\fR\fB\fR are given, returns only that part of the resulting 
string.
.SS reorder_map
.IX Subsection "reorder_map"
.Vb 2
\&    ($elout, $mout) = $tb\->reorder_map($types, $offset, $len, $par,
\&                                       $map, $el, $flags);
.Ve
.PP
Compute the reordering map for bidi types given by \fR\f(CB$types\fR\fB\fR, for the 
interval starting with \fB\fR\f(CB$offset\fR\fB\fR of length \fB\fR\f(CB$len\fR\fB\fR. Note that this part of 
the algorithm depends on the interval in an essential way. \fB\fR\f(CB$types\fR\fB\fR is an 
array of types, as computed by "get_bidi_types". The other arguments are 
optional:
.ie n .IP \fR\fB$par\fR\fB\fR 4
.el .IP \fR\f(CB$par\fR\fB\fR 4
.IX Item "$par"
The base paragraph direction. Computed via "get_par_embedding_levels" if 
not defined.
.ie n .IP \fR\fB$map\fR\fB\fR 4
.el .IP \fR\f(CB$map\fR\fB\fR 4
.IX Item "$map"
An array ref (or a Text::Bidi::Array::Long) from a previous call (with a 
different interval). The method is called repeatedly for the same paragraph, 
with different intervals, and the reordering map is updated for the given 
interval. If not defined, initialised to the identity map.
.ie n .IP \fR\fB$el\fR\fB\fR 4
.el .IP \fR\f(CB$el\fR\fB\fR 4
.IX Item "$el"
The embedding levels. If not given, computed by a call to 
"get_par_embedding_levels".
.ie n .IP \fR\fB$flags\fR\fB\fR 4
.el .IP \fR\f(CB$flags\fR\fB\fR 4
.IX Item "$flags"
A specification of flags, as described in \fBfribidi_reorder_line\fR\|(3). The flags 
can be given either as a number (using \f(CW\*(C`$Text::Bidi::Flags::..\*(C'\fR from 
Text::Bidi::Constants), or as a hashref of the form
\&\f(CW\*(C`{REORDER_NSM => 1}\*(C'\fR. Defaults to \f(CW\*(C`FRIBIDI_FLAGS_DEFAULT\*(C'\fR.
.PP
The output consists of the modified map \fR\f(CB$mout\fR\fB\fR (a 
Text::Bidi::Array::Long), and possibly modified embedding levels 
\&\fB\fR\f(CB$elout\fR\fB\fR.
.PP
method remove_bidi_marks
.PP
.Vb 2
\&    ($v, $to, $from, $levels) = 
\&        $tb\->remove_bidi_marks($v[, $to[, $from[, $levels]]])
.Ve
.PP
Remove the explicit bidi marks from \f(CW$v\fR. The optional arguments, if given, 
are the map from the logical to the visual string, the inverse map, and 
embedding levels, respectively, as returned by "reorder_map". The inverse 
map \f(CW$from\fR can be obtained from the direct one \f(CW$to\fR by a command like:
.PP
.Vb 1
\&    @$from[@$map] = 0..$#$map
.Ve
.PP
Each of the arguments can be \f(CW\*(C`undef\*(C'\fR, in which case it will be skipped. This 
implements step X9, see \fBfribidi_remove_bidi_marks\fR\|(3).
.SH BUGS
.IX Header "BUGS"
There are no real tests for any of this.
.PP
Shaping is not supported (probably), since I don't know what it is. Help 
welcome!
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Text::Bidi::Paragraph
.PP
Text::Bidi::Constants
.PP
Encode
.PP
The fribidi library <http://fribidi.org/>
.PP
Swig <http://www.swig.org>
.PP
The unicode bidi algorithm <http://www.unicode.org/unicode/reports/tr9/>
.SH AUTHOR
.IX Header "AUTHOR"
Moshe Kamensky <kamensky@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2015 by Moshe Kamensky.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.