.\" -*- 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::Paragraph 3pm"
.TH Text::Bidi::Paragraph 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::Paragraph \- Run the bidi algorithm on one paragraph
.SH VERSION
.IX Header "VERSION"
version 2.18
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&    use Text::Bidi::Paragraph;
\&
\&    my $par = new Text::Bidi::Paragraph $logical;
\&    my $offset = 0;
\&    my $width = 80;
\&    while ( $offset < $p\->len ) {
\&        my $v = $p\->visual($offset, $width);
\&        say $v;
\&        $offset += $width;
\&    }
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This class provides the main interface for applying the bidi algorithm in 
full generality. In the case where the paragraph can be formatted at once, 
"log2vis" in Text::Bidi can be used as a shortcut.
.PP
A paragraph is processed by creating a Text::Bidi::Paragraph object:
.PP
.Vb 1
\&    $par = new Text::Bidi::Paragraph $logical;
.Ve
.PP
Here \f(CW$logical\fR is the text of the paragraph. This applies the first stages 
of the bidi algorithm: computation of the embedding levels. Once this is 
done, the text can be displayed using the "visual" method, which does the 
reordering.
.SH METHODS
.IX Header "METHODS"
.SS new
.IX Subsection "new"
.Vb 1
\&    my $par = new Text::Bidi::Paragraph $logical, ...;
.Ve
.PP
Create a new object corresponding to a text \fR\f(CB$logical\fR\fB\fR in logical order. The 
other arguments are key-value pairs. The only ones that have a meaning at the 
moment are \fIbd\fR, which supplies the Text::Bidi object to use, 
\&\fIdir\fR, which prescribes the direction of the paragraph, and \fIshape\fR,
which determines shaping flags. The value of \fIdir\fR 
is a constant in \f(CW\*(C`Text::Bidi::Par::\*(C'\fR (e.g., \f(CW$Text::Bidi::Par::RTL\fR; see 
Text::Bidi::Constants). The value of \fIshape\fR is a constant from
\&\fBfribidi_shape_arabic\fR\|(3). If it is \f(CW\*(C`undef\*(C'\fR, no shaping is done. If it is 
missing, default shaping will be performed if the paragraph contains Arabic 
text.
.PP
Note that the mere creation of \fR\f(CB$par\fR\fB\fR runs the bidi algorithm on the given 
text \fB\fR\f(CB$logical\fR\fB\fR up to the point of reordering (which is dealt with in 
"visual").
.SS par
.IX Subsection "par"
.Vb 1
\&    my $logical = $par\->par;
.Ve
.PP
Returns the logical (input) text corresponding to this paragraph.
.SS dir
.IX Subsection "dir"
.Vb 1
\&    my $dir = $par\->dir;
.Ve
.PP
Returns the direction of this paragraph, a constant in the 
\&\f(CW$Text::Bidi::Par::\fR namespace.
.SS len
.IX Subsection "len"
.Vb 1
\&    my $len = $par\->len;
.Ve
.PP
The length of this paragraph.
.SS types
.IX Subsection "types"
.Vb 1
\&    my $types = $par\->types;
.Ve
.PP
The Bidi types of the characters in this paragraph. Each element of 
\&\f(CW@$types\fR is a constant in the \f(CW$Text::Bidi::Type::\fR namespace.
.SS levels
.IX Subsection "levels"
.Vb 1
\&    my $levels = $par\->levels;
.Ve
.PP
The embedding levels for this paragraph. Each element of \f(CW@$levels\fR is an 
integer.
.SS bd
.IX Subsection "bd"
.Vb 1
\&    my $bd = $par\->bd;
.Ve
.PP
The Text::Bidi object used to interface with libfribidi.
.SS map
.IX Subsection "map"
.Vb 1
\&    my $map = $par\->map;
.Ve
.PP
The map from the logical text to the visual, i.e., the values in \f(CW$map\fR are 
indices in the logical string, so that the \f(CW$i\fR\-th character of the visual 
string is the character that occurs at \f(CW\*(C`$map\->[$i]\*(C'\fR in the logical 
string.
.PP
This is updated on each call to "visual", so that the map for the full 
paragraph is correct only after calling "visual" for the whole text.
.SS type_names
.IX Subsection "type_names"
.Vb 1
\&    @types = $par\->type_names;
.Ve
.PP
Returns the list of bidi types as strings
.SS is_rtl
.IX Subsection "is_rtl"
.Vb 1
\&    my $rtl = $par\->is_rtl;
.Ve
.PP
Returns true if the direction of the paragraph is \f(CW\*(C`RTL\*(C'\fR (right to left).
.SS ar_props
.IX Subsection "ar_props"
.Vb 1
\&    $props = $self\->ar_props
.Ve
.PP
Return the shaping properties (TODO)
.SS shaped
.IX Subsection "shaped"
.Vb 1
\&    $shaped = $self\->shaped(flags)
.Ve
.PP
Return the shaped paragraph, and fix ar_props (TODO)
.SS visual
.IX Subsection "visual"
.Vb 1
\&    my $visual = $par\->visual($offset, $length, $flags);
.Ve
.PP
Return the visual representation of the part of the paragraph \fR\f(CB$par\fR\fB\fR 
starting at \fB\fR\f(CB$offset\fR\fB\fR and of length \fB\fR\f(CB$length\fR\fB\fR. \fB\fR\f(CB$par\fR\fB\fR is a 
Text::Bidi::Paragraph object. All arguments are optional, with \fB\fR\f(CB$offset\fR\fB\fR 
defaulting to \f(CW0\fR and \fB\fR\f(CB$length\fR\fB\fR to the length till the end of the paragraph 
(see below from \fB\fR\f(CB$flags\fR\fB\fR).
.PP
Note that this method does not take care of right-justifying the text if the 
paragraph direction is \f(CW\*(C`RTL\*(C'\fR. Hence a typical application might look as 
follows:
.PP
.Vb 3
\&    my $visual = $par\->visual($offset, $width, $flags);
\&    my $len = length($visual);
\&    $visual = (\*(Aq \*(Aq x ($width \- $len)) . $visual if $par\->is_rtl;
.Ve
.PP
Note also that the length of the result might be strictly less than 
\&\fR\f(CB$length\fR\fB\fR.
.PP
The \fR\f(CB$flags\fR\fB\fR argument, if defined, should be either a hashref or an integer.  
If it is a number, its meaning is the same as in \f(CWfribidi_reorder_line(3)\fR.  
A hashref is converted to the corresponding values for keys whose value is 
true. The keys should be the same as the constants in \fIfribidi\-types.h\fR, 
with the prefix \f(CW\*(C`FRIBIDI_FLAGS_\*(C'\fR removed.
.PP
In addition, the \fR\f(CB$flags\fR\fB\fR hashref may contain lower-case keys. The only one 
recognised at the moment is \fIbreak\fR. Its value, if given, should be a string 
at which the line should be broken. Hence, if this key is given, the actual 
length is potentially reduced, so that the line breaks at the given string 
(if possible). A typical value for \fIbreak\fR is \f(CW\*(Aq \*(Aq\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Text::Bidi
.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.