NAME

Text::Bidi::Paragraph - Run the bidi algorithm on one paragraph

SYNOPSIS

    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;
    }

DESCRIPTION

This class provides the main interface for applying the bidi algorithm in full generality. In the case where the paragraph spans only one visual line, "log2vis" in Text::Bidi can be used as a shortcut.

A paragraph is processed by creating a Text::Bidi::Paragraph object:

    $par = new Text::Bidi::Paragraph $logical;

Here $logical 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.

METHODS

new()

    my $par = new Text::Bidi::Paragraph $logical, ...;

Create a new object corresponding to a text $logical in logical order. The other arguments are key-value pairs. The only ones that have a meaning at the moment are bd, which supplies the Text::Bidi object to use, and dir, which prescribes the direction of the paragraph. The value of dir is a constant in Text::Bidi::Par:: (e.g., $Text::Bidi::Par::RTL).

Note that the mere creation of $par runs the bidi algorithm on the given text $logical up to the point of reordering (which is dealt with in "visual()").

par()

    my $logical = $par->par;

Returns the logical (input) text corresponding to this paragraph.

dir()

    my $dir = $par->dir;

Returns the direction of this paragraph, a constant in the $Text::Bidi::Par:: package.

len()

    my $len = $par->len;

The length of this paragraph.

types()

    my $types = $par->types;

The Bidi types of the characters in this paragraph. Each element of @$types is a constant in the $Text::Bidi::Type:: package.

levels()

    my $levels = $par->levels;

The embedding levels for this paragraph. Each element of @$levels is an integer.

is_rtl()

    my $rtl = $par->is_rtl;

Returns true if the direction of the paragraph is RTL (right to left).

visual()

    my $visual = $par->visual($offset, $length, $flags);

Return the visual representation of the part of the paragraph $par starting at $offset and of length $length. $par is a Text::Bidi::Paragraph object. All arguments are optional, with $offset defaulting to 0 and $length to the length till the end of the paragraph (see below from $flags).

Note that this method does not take care of right-justifying the text if the paragraph direction is RTL. Hence a typical application might look as follows:

    my $visual = $par->visual($offset, $width, $flags);
    my $len = length($visual);
    $visual = (' ' x ($width - $len)) . $visual if $par->is_rtl;

Note also that the length of the result might be strictly less than $length.

The $flags argument, if defined, should be either a hashref or an integer. If it is a number, its meaning is the same as in fribidi_reorder_line(3). A hashref is converted to the corresponding values for keys whose value is true. The keys should be the same as the constants in fribidi-types.h, with the prefix FRIBIDI_FLAGS_ removed.

In addition, the $flags hashref may contain lower-case keys. The only one recognised at the moment is break. 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 break is ' '.

SEE ALSO

Text::Bidi

AUTHOR

Moshe Kamensky (<kamensky@cpan.org>) - Copyright (c) 2013

LICENSE

This program is free software. You may copy or redistribute it under the same terms as Perl itself.

cpanm Text::Bidi

perl -MCPAN -e shell
install Text::Bidi