NAME

    Text::Bidi - Unicode bidi algorithm using libfribidi

VERSION

    version 2.19

SYNOPSIS

        # 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);

EXPORT

    The following functions can be exported (nothing is exported by
    default):

      * "log2vis"

      * "is_bidi"

      * "get_mirror_char"

      * "get_bidi_type_name"

      * "fribidi_version"

      * "unicode_version"

      * "fribidi_version_num"

    All of them can be exported together using the :all tag.

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 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.

 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.

    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:

        $visual = log2vis($logical, $width);

    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 libfribidi and who wish to extend or modify the
    module.

 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

            $visual = log2vis($logical);

    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 are interested in deriving from this
    class, please see "SUBCLASSING".

FUNCTIONS

 get_bidi_type_name

        say $tb->get_bidi_type_name($Text::Bidi::Type::LTR); # says 'LTR'

    Return the string representation of a Bidi character type, as in
    fribidi_get_bidi_type_name(3). Note that for the above example, one
    needs to use Text::Bidi::Constants.

 log2vis

        ($p, $visual) = log2vis($logical[,$width[,$dir[,$flags]]]);

    Convert the input paragraph $logical to visual. This constructs a
    Text::Bidi::Paragraph object, and calls "visual" in
    Text::Bidi::Paragraph several times, as required. $width is the maximum
    width of a line, defaulting to the whole length of the paragraph. $dir
    is the base direction of the paragraph, determined automatically if not
    provided. $flags is as in "visual" in Text::Bidi::Paragraph. The
    paragraph will be justified to the right if it is RTL.

    The output consists of the Text::Bidi::Paragraph object $p and the
    visual string $visual.

 is_bidi()

        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.

 get_mirror_char()

        my $mir = get_mirror_char('['); # $mir == ']'

    Return the mirror character of the input, possibly itself.

 fribidi_version

        say fribidi_version();

    Returns the version information for the fribidi library

 fribidi_version_num

        say fribidi_version_num();

    Returns the version number for the fribidi library

 unicode_version

        say unicode_version();

    Returns the Unicode version used by the fribidi library

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.

    If you do sub-class this class, and would like the procedural interface
    to use your functions, put a line like

            $Text::Bidi::GlobalClass = __PACKAGE__;

    in your module.

METHODS

 new

        $tb = new Text::Bidi [tie_byte => ..., tie_long => ...];

    Create a new Text::Bidi object. If the tie_byte or tie_long 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.

    This method is probably of little interest for standard (procedural)
    use.

 utf8_to_internal

        $la = $tb->utf8_to_internal($str);

    Convert the Perl string $str into the representation used by
    libfribidi. The result will be a Text::Bidi::Array::Long.

 internal_to_utf8

        $str = $tb->internal_to_utf8($la);

    Convert the long array $la, representing a string encoded in to format
    used by libfribidi, into a Perl string. The array $la can be either a
    Text::Bidi::Array::Long, or anything that can be used to construct it.

 get_bidi_types

        $types = $tb->get_bidi_types($internal);

    Returns a Text::Bidi::Array::Long with the list of Bidi types of the
    text given by $internal, a representation of the paragraph text, as
    returned by utf8_to_internal(). Wraps fribidi_get_bidi_types(3).

 get_bracket_types

        $brackets = $tb->get_bracket_types($internal[, $types]);

    Return a Text::Bidi::Array::Long of paired-bracket properties for the
    internal string. $types defaults to "get_bidi_types". Wraps
    fribidi_get_bracket_types(3).

 get_joining_types

        $types = $tb->get_joining_types($internal);

    Returns a Text::Bidi::Array::Byte with the list of joining types of the
    text given by $internal, a representation of the paragraph text, as
    returned by "utf8_to_internal". Wraps fribidi_get_joining_types(3).

 get_joining_type_name

        say $tb->get_joining_type_name($Text::Bidi::Joining::U); # says 'U'

    Return the string representation of a joining character type, as in
    fribidi_get_joining_type_name(3). Note that for the above example, one
    needs to use Text::Bidi::Constants.

 get_par_embedding_levels

       ($odir, $lvl) = $tb->get_par_embedding_levels($types[, $dir[, $brackets]]);

    Return the embedding levels of the characters, whose types are given by
    $types. $types is a Text::Bidi::Array::Long of Bidi types, as returned
    by "get_bidi_types". $dir is the base paragraph direction. If not
    given, it defaults to FRIBIDI_PAR_ON (neutral). $brackets is the array
    returned by "get_bracket_types". Supply it to enable Unicode paired
    bracket resolution (rule N0). Without it, all characters are treated as
    non-brackets, preserving the original two-argument interface.

    This method uses fribidi_get_par_embedding_levels_ex(3).

    The output is the resolved paragraph direction $odir, and the
    Text::Bidi::Array::Byte array $lvl of embedding levels.

 join_arabic

        $props = $tb->join_arabic($bidi_types, $lvl, $join_types);

    Returns a Text::Bidi::Array::Byte with $props, as returned by
    fribidi_join_arabic(3). The inputs are $bidi_types, as returned by
    "get_bidi_types", $lvl, as returned by "get_par_embedding_levels", and
    $join_types as returned by "get_joining_types". Wraps
    fribidi_join_arabic(3).

 shaped

        ($newp, $shaped) = $tb->shaped($flags, $lvl, $prop, $internal);

    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 $internal, while
    the embedding levels (as returned by "get_par_embedding_levels") should
    be in $lvl. See the documentation of fribidi-arabic.h for $flags, but
    as a special case, a value of undef here skips shaping (returning
    ($prop, $internal)), while any other false value becomes the default.
    $prop is as returned by "join_arabic". This method wraps
    fribidi_shape_arabic(3).

 mirrored

        $mirrored = $tb->mirrored($lvl, $internal);

    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 $internal, while
    the embedding levels (as returned by "get_par_embedding_levels") should
    be in $lvl. This method wraps fribidi_shape_mirroring(3).

 reorder

        $str = $tb->reorder($in, $map[, $offset[, $len]]);
        say $tb->reorder([qw(A B C)], [2, 0, 1]); # says CAB

    View the array ref $map as a permutation, and permute the list (of
    characters) $in according to it. The result is joined, to obtain a
    string. If $offset and $len are given, returns only that part of the
    resulting string.

 reorder_map

        ($elout, $mout) = $tb->reorder_map($types, $offset, $len, $par,
                                           $map, $el, $flags);

    Compute the reordering map for bidi types given by $types, for the
    interval starting with $offset of length $len. Note that this part of
    the algorithm depends on the interval in an essential way. $types is an
    array of types, as computed by "get_bidi_types". The other arguments
    are optional:

    $par

      The base paragraph direction. Computed via "get_par_embedding_levels"
      if not defined.

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

    $el

      The embedding levels. If not given, computed by a call to
      "get_par_embedding_levels".

    $flags

      A specification of flags, as described in fribidi_reorder_line(3).
      The flags can be given either as a number (using
      $Text::Bidi::Flags::.. from Text::Bidi::Constants), or as a hashref
      of the form {REORDER_NSM => 1}. Defaults to FRIBIDI_FLAGS_DEFAULT.

    The output consists of the modified map $mout (a
    Text::Bidi::Array::Long), and possibly modified embedding levels
    $elout.

SELECTING DISPLAYED TEXT

    Text::Bidi::Selection maps visual selections back to the original
    logical text. For a single unwrapped paragraph:

        use Text::Bidi::Selection;
    
        my ($paragraph, $visual) = log2vis($logical);
        my $selection = Text::Bidi::Selection->new(
            text              => $logical,
            visual_to_logical => $paragraph->map,
        );
        my $copy = $selection->selected_text($start, $end);

    The start offset is included and the end offset is excluded. The result
    is in logical reading order and omits unselected gaps between logical
    ranges. For terminal cells or shaped glyphs, supply the renderer's map
    of displayed positions to original character offsets; grouped entries
    can represent combining characters or ligatures.

BUILDING

    FriBidi is an external library; its source is not bundled with this
    module. Install its development headers and library before building.
    FriBidi 1.0.0 or newer is required. This interface has been tested with
    FriBidi 1.0.18 (Unicode 18.0.0), SWIG 4.5.1, and Perl 5.44.0.

    To build a source checkout:

        perl Makefile.PL
        make
        make test

    SWIG is needed to generate the wrapper in a source checkout. Release
    distributions include the generated C and Perl wrappers, so SWIG is
    only needed when regenerating them with make swig. Select another
    executable with make swig SWIG=/path/to/swig. Compilation flags are
    obtained through ExtUtils::PkgConfig or the pkg-config command;
    PKG_CONFIG can select another pkg-config executable. The checkout uses
    development version 0.00; Dist::Zilla supplies the version when
    preparing a release.

    An additional author test accepts the official BidiCharacterTest.txt
    from https://www.unicode.org/Public/. Use data matching the Unicode
    version reported by "unicode_version":

        TEXT_BIDI_CHARACTER_TEST=/path/to/BidiCharacterTest.txt \
            prove -b xt/author/ucd-characters.t

    method remove_bidi_marks

        ($v, $to, $from, $levels) = 
            $tb->remove_bidi_marks($v[, $to[, $from[, $levels]]])

    Remove the explicit bidi marks from $v. 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 $from can be obtained from the direct one $to by a
    command like:

        @$from[@$map] = 0..$#$map

    Each of the arguments can be undef, in which case it will be skipped.
    This implements step X9, see fribidi_remove_bidi_marks(3).

BUGS

    There are no real tests for any of this.

    Shaping is not supported (probably), since I don't know what it is.
    Help welcome!

SEE ALSO

    Text::Bidi::Paragraph

    Text::Bidi::Constants

    Text::Bidi::Selection

    Encode

    The fribidi library <http://fribidi.org/>

    Swig <http://www.swig.org>

    The unicode bidi algorithm
    <http://www.unicode.org/unicode/reports/tr9/>

AUTHOR

    Moshe Kamensky <kamensky@cpan.org>

COPYRIGHT AND LICENSE

    This software is copyright (c) 2015 by Moshe Kamensky.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.

