Text::...ragraph(3pm)

💖 Text::Bidi::Paragraph 💖

okay bestie, pull up a chair, we're reading a Perl manpage together and honestly? it's giving main character energy. this is the page for Text::Bidi::Paragraph, part of the User Contributed Perl Documentation, and yes it has a VERSION because it's a whole real module. 🦋

---

✨ NAME ✨

Text::Bidi::Paragraph — run the bidi algorithm on one paragraph. that's it, that's the job. no cap. 💅

🎀 VERSION 🎀

version 2.18 ✨ (yes queen, versioned)

🌸 SYNOPSIS 🌸

look at this little routine, it's so cute:

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

periodt. 💖

🦋 DESCRIPTION 🦋

so like. this class is the main interface for applying the bidi algorithm in full generality. if your paragraph can just be formatted all at once, though, you're lowkey fine using log2vis in Text::Bidi as a shortcut — it's iconic, it's easy, it slays. 👍

you process a paragraph by making a Text::Bidi::Paragraph object:

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

okay so $logical here is the text of the paragraph. making the object runs the first stages of the bidi algorithm — namely computing the embedding levels. once that's done, you display the text with the visual method, which is the one doing the reordering. it's a whole two-step reveal, honestly. ✨

👑 METHODS 👑

💜 new

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

creates a new object for a text $logical that's in logical order. the other arguments are key-value pairs, and like, only these ones mean anything rn:

• bd — hands over the Text::Bidi object you want it to use 💫
• dir — prescribes the direction of the paragraph. its value is a constant in Text::Bidi::Par:: (for example $Text::Bidi::Par::RTL — go look at Text::Bidi::Constants) 🧭
• shape — decides the shaping flags. its value is a constant from fribidi_shape_arabic(3). if it's undef, no shaping happens at all. if it's just missing, default shaping gets performed when the paragraph contains Arabic text 🌙

not me reminding you that just creating $par runs the bidi algorithm on $logical all the way up to the point where reordering happens — and reordering is handled by visual. so yeah, construction is not a vibes-only operation, it does work. 💀

💜 par

my $logical = $par->par;

returns the logical (input) text for this paragraph. the og. 🫶

💜 dir

my $dir = $par->dir;

returns the direction of this paragraph — a constant in the $Text::Bidi::Par:: namespace.

💜 len

my $len = $par->len;

the length of this paragraph. short and sweet. 🍓

💜 types

my $types = $par->types;

the bidi types of the characters in this paragraph. every element of @$types is a constant in the $Text::Bidi::Type:: namespace. 💅

💜 levels

my $levels = $par->levels;

the embedding levels for this paragraph. every element of @$levels is an integer. ✨

💜 bd

my $bd = $par->bd;

the Text::Bidi object that's used to interface with libfribidi. the plug. 🔌

💜 map

my $map = $par->map;

the map from the logical text to the visual — meaning the values in $map are indices into the logical string, so the $i-th character of the visual string is the character that shows up at $map->[$i] in the logical string. it's giving ✨coordinates✨.

heads up bestie: this gets updated on each call to visual, so the map for the full paragraph is only correct after you've called visual for the whole text. don't come for me if you read it early. 🙈

💜 type_names

@types = $par->type_names;

returns the list of bidi types as strings. 🌈

💜 is_rtl

my $rtl = $par->is_rtl;

returns true if the direction of the paragraph is "RTL" (right to left). that's the vibe check. 🧿

💜 ar_props

$props = $self->ar_props

returns the shaping properties. (TODO — yeah it literally says TODO, we love an unfinished subplot 😭)

💜 shaped

$shaped = $self->shaped(flags)

returns the shaped paragraph, and fixes ar_props. (also TODO. the girlies are still cooking 🔥)

💜 visual

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

returns the visual representation of the part of the paragraph $par starting at $offset and of length $length. $par is a Text::Bidi::Paragraph object. every argument is optional — $offset defaults to 0 and $length defaults to the length till the end of the paragraph (see below from $flags). 💫

ok real talk: this method does not take care of right-justifying the text when the paragraph direction is "RTL". so a typical application might look like this, and yes you should copy it: 👇

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

also note that the length of the result might be strictly less than $length. it's not lying to you, it's just built different. 😌

the $flags argument, if it's defined, should be either a hashref or an integer:

• if it's a number, its meaning is the same as in fribidi_reorder_line(3) 🔢
• if it's a hashref, it gets converted to the corresponding values for the keys whose value is true. the keys should match the constants in fribidi-types.h but with the prefix FRIBIDI_FLAGS_ removed ✂️

plus — and this is the fun part — the $flags hashref can also contain lower-case keys. the only one recognised right now is break. its value, if you give one, should be a string where the line should be broken. so if you pass this key, the actual length is potentially reduced, so the line breaks at that given string (if possible). a typical value for break is ' '. 🎀

💖 SEE ALSO 💖

Text::Bidi — go read it, it's right there, it's the moment. ✨

🌟 AUTHOR 🌟

Moshe Kamensky <kamensky@cpan.org> — thank you for your service, king 👑

📜 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. so like, go off, but respectfully. 🫶

---

and that's the page, bestie!! 🌈 all of it, no skips, we read the whole thing together like the icons we are. this was perl v5.42.3, dated 2026-08-19 — mwah, love that for us. now go reorder some text. 💅💖✨