NAME

Text::Bidi::Selection - Map visual selections to original logical text

VERSION

version 2.19

SYNOPSIS

use Text::Bidi qw(log2vis);
use Text::Bidi::Selection;

my $logical = "abc \x{5d0}\x{5d1}\x{5d2}\x{5d3} xyz";
my ($paragraph, $visual) = log2vis($logical);
my $selection = Text::Bidi::Selection->new(
    text              => $logical,
    visual_to_logical => $paragraph->map,
);

my $ranges = $selection->logical_ranges(6, 10);
# [[4, 6], [8, 10]]: two separate ranges in the original text
my $text = $selection->selected_text(6, 10);
# "\x{5d0}\x{5d1} x", without the unselected intervening letters

DESCRIPTION

This module translates a visual selection into ranges in the original logical text, and extracts those ranges in logical reading order. A visual selection can correspond to several separate logical ranges in mixed bidirectional text. Unselected characters between those ranges are omitted.

The module takes a snapshot of its text and map. Later changes to the input map, including a "map" in Text::Bidi::Paragraph updated by another call to visual, do not affect an existing selection object.

Logical offsets count characters in the original Perl string, not UTF-8 bytes. Visual offsets count entries in the supplied map. For a paragraph map these are character positions. A renderer may instead supply one entry per terminal cell, grapheme, or glyph. It is responsible for translating mouse coordinates into those visual offsets and defining word and line selection.

This module performs no rendering or shaping and has no dependency on urxvt or the native FriBidi wrapper.

METHODS

new

my $selection = Text::Bidi::Selection->new(
    text              => $logical,
    visual_to_logical => $map,
);

text is the original, unshaped logical string. visual_to_logical is an array reference (or an object that can be dereferenced as an array). Each entry is one of:

  • A non-negative character offset into text.

  • An array reference of character offsets. For example, [2, 3] can represent a ligature containing two original characters, or a base character and its combining mark.

  • undef or [] for a displayed position without a logical character, such as padding or an inserted formatting mark.

Several entries may refer to the same character, for example the cells of a wide character. Selecting any of those entries selects that character once. Offsets must be smaller than the length of text. Invalid arguments croak.

logical_ranges

my $ranges = $selection->logical_ranges($start, $end);

Return an array reference of [$start, $end] logical ranges. All ranges include their start and exclude their end. The input range uses visual offsets and must satisfy 0 <= $start <= $end <= map length. Invalid bounds croak; an empty selection returns [].

The returned ranges are sorted by logical offset, contain no duplicates, and merge adjacent selected characters. Characters in a gap between ranges are not selected. Each call returns new arrays that the caller may modify.

selected_text

my $text = $selection->selected_text($start, $end);

Extract the ranges returned by "logical_ranges" and concatenate them in logical reading order. The result contains the original characters, without shaping or mirroring. An empty or entirely unmapped selection returns ''. Line breaks between separately rendered rows remain the caller's policy.

SEE ALSO

Text::Bidi, Text::Bidi::Paragraph

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.