Text::Flow(3pm)

💖 Text::Flow 💖

okay bestie, so this is the manual page for Text::Flow, which is a perl module (a 3pm one, if we're being specific) 🫶 — flexible text flowing and word wrapping, and NOT just for ASCII output, which is the whole point, iykyk.

---

✨ SYNOPSIS ✨

  use Text::Flow;

  # use it on ASCII text ...
  my $flow = Text::Flow->new(
      check_height => sub {
          my $paras = shift;
          sum(map { scalar @$_ } @$paras) <= 10;
      },
      wrapper => Text::Flow::Wrap->new(
          check_width  => sub { length($_[0]) < 70 }
      ),
  );

  my @sections = $flow->flow($text);

  # @sections will now be an array of strings, each string
  # will contain no more than 10 lines of text each of which
  # will be no longer then 70 characters long

  # or use it on text in a PDF file ...
  my $flow = Text::Flow->new(
      check_height => sub {
          my $paras = shift;
          (sum(map { scalar @$_ } @$paras) * $pdf->get_font_height) < 200;
      },
      wrapper => Text::Flow::Wrap->new(
          check_width => sub {
              my $string = shift;
              $pdf->get_string_width($string) < 100
          },
      )
  );

  my @sections = $flow->flow($text);

  # @sections will now be an array of strings, each string
  # will contain text which will fit within 200 pts and
  # each line will be no longer then 100 pts wide

---

🌸 DESCRIPTION 🌸

so like, this module gives you a flexible way to wrap AND flow text, and it works for ASCII output and non-ASCII output. best of both worlds, no cap 💅

🎀 Another Text Wrap module!!?!?!

okay hear me out before you roll your eyes 🙈 — the whole point of this module is to do text wrapping and flowing without being tied down to ASCII-based output and fixed-width fonts. the author's actual needs were for more sophisticated text control in PDF and GIF output formats in particular. it's giving very specific queen energy, and honestly? slay.

---

💜 METHODS 💜

• new (%params) — constructs the new Text::Flow instance. it accepts parameters for the "wrapper" and "check_height" variables. that's it, that's the constructor 🫶
• wrapper (?$wrapper) — the accessor for the internally help Text::Flow::Wrapper instance (yes, "help", we're keeping it, it's iconic) which Text::Flow uses to wrap the individual lines.
• check_height — the accessor for the CODE ref used to check the height of the current paragraph. it gets, as its argument, an array-ref of paragraphs, and each of those is also an array-ref of text lines. the most common usage is right up there in the SYNOPSIS, but fr fr you can do literally anything you want with them. it's expected to return a Boolean value: true if the height is still okay ✅, false if the max height has been reached 🛑.
• flow ($text) — this method preforms the text flowing (preforms, bestie, that's the vibe). it returns an array of strings which you can treat as complete blocks of text. it will handle paragraph breaks and line breaks for you, so you don't have to. king behaviour 👑

🔍 Introspection

• meta — returns the Moose meta object associated with this class. very meta of it. 🦋

---

⭐ TODO ⭐

the author wanted to write some tests for using this with GD modules as well. I guess we will have to wait until 0.02 for that 🫠 (manifesting).

---

🌈 SIMILAR MODULES 🌈

there are a bunch of other text wrapping and flowing modules out there, but they are all meant for use in ASCII outout only (yes, "outout", we're keeping the typo, it's part of the lore). that just didn't work for the author's needs, so this one got written instead. if you need to wrap ASCII text and you wanna do it in a much simpler manner than this module provides, then pls go check out those other modules. this module is specifically made for when those other modules are no longer powerful and flexible enough. it's giving "built different" ✨

---

💀 BUGS 💀

all complex software has bugs lurking in it, and this module is no exception 😭. if you find a bug please either email the author, or add the bug to cpan-RT. do it for the girlies.

---

👑 AUTHOR 👑

Stevan Little <stevan@iinteractive.com>

---

📜 COPYRIGHT AND LICENSE 📜

Copyright 2007 by Infinity Interactive, Inc.

<http://www.iinteractive.com>

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

---

and that's the whole page, bestie — written for perl v5.34.0, dated 2022-06-28, under the Text::Flow(3pm) banner in the User Contributed Perl Documentation section. periodt 💅✨