HTML::...thLinks(3pm)

📦
version 0.15 · 10 versions
, in opensuse-leap 16.0

✨ HTML::FormatText::WithLinks — the perl (3pm) page but make it cute ✨

okay so bestie, this is the manual for HTML::FormatText::WithLinks and it's literally the moment HTML gets turned into plain text but like... with the links saved as footnotes so nothing gets lost. iconic behavior honestly 💅

✨ NAME ✨

HTML::FormatText::WithLinks — turning HTML into text and keeping the links as footnotes 🎀

🌸 SYNOPSIS 🌸

use HTML::FormatText::WithLinks;

my $f = HTML::FormatText::WithLinks->new();

my $html = qq(
<html>
<body>
<p>
    Some html with a <a href="http://example.com/">link</a>
</p>
</body>
</html>
);

my $text = $f->parse($html);

print $text;

# results in something like

Some html with a [1]link

1. http://example.com/

my $f2 = HTML::FormatText::WithLinks->new(
    before_link => '',
    after_link => ' [%l]',
    footnote => ''
);

$text = $f2->parse($html);
print $text;

# results in something like

Some html with a link [http://example.com/]

my $f3 = HTML::FormatText::WithLinks->new(
    link_num_generator => sub {
        return "*" x (shift() + 1);
    },
    footnote => '[%n] %l'
);

$text = $f3->parse($html);
print $text;

# results in something like

Some html with a [*]link

[*] http://example.com/

🦋 DESCRIPTION 🦋

HTML::FormatText::WithLinks takes your HTML and turns it into plain text, but the way it handles links is chef's kiss — it prints them all out as footnotes instead of just yeeting the URLs into the void. By default it's lowkey trying to mimic how the lynx text browser does its --dump thing. no cap, that's the vibe 🌈

🎀 METHODS 🎀

💖 new

my $f = HTML::FormatText::WithLinks->new( %options );

Returns a shiny new instance bestie ✨ It takes every single option that HTML::FormatText accepts PLUS these extra ones:

  • base — a base option. Set this to a URI and it'll turn any relative URIs in the HTML into absolute ones. super useful fr fr.
  • doc_overrides_base — if there's a base element in the doc and it has an href attribute, setting this to true makes the document's own base win. defaults to false (so like, the base option is the main character by default).
  • before_link (default: '[%n]') — a string printed before a link, like when the <a> tag shows up.
  • after_link (default: '') — printed after the link ends (when </a> shows up).
  • footnote (default: '[%n] %l') — printed when the footnotes are being printed out.

For all three of these: "%n" gets replaced by the link number and "%l" gets replaced by the link itself. and if you set footnote to ''? no footnotes get printed at all bestie. gone. 💀

  • link_num_generator (default: sub { return shift() + 1 }) — a sub that returns the value printed for a given link number. the internal store starts numbering at 0 (so it's zero-indexed, iykyk).
  • with_emphasis — set to 1 and italicised text gets wrapped in / and bolded text gets wrapped in _. you can change those markers with the "italic_marker" and "bold_marker" options 🎀
  • unique_links — set to 1 and you only get 1 footnote per unique URI instead of the default (which is a footnote per URI, no dedupe, periodt).
  • anchor_links — set to 0 and links pointing to local anchors get skipped. default is to include all links (iconic inclusivity behavior).
  • skip_linked_urls — set to 1 and links where the text equals the href value get skipped. default is to include all links.

🌟 parse

my $text = $f->parse($html);

Takes some HTML and hands you back text. Returns undef on error. also returns undef if you pass it undef (fair enough bestie). returns an empty string if you pass it an empty string 🫶

🌸 parse_file

my $text = $f->parse_file($filename);

Takes a filename and returns the contents as plain text. returns undef on error.

🦋 error

$f->error();

Returns the last error that happened. in practice it's probs gonna be either a warning that parse_file couldn't find the file, or that HTML::TreeBuilder failed 😭

💀 CAVEATS 💀

okay so real talk — when you pass HTML fragments, the results can be a little unpredictable ngl. I've tried to work around the most egregious of the issues, but unexpected results are welcome (fr, send them my way).

Also note: if for some reason there's an <a> tag in the document that does NOT have an href attribute, it will be quietly ignored 🫥 If that's genuinely a problem for anyone, let me know and I'll see if I can think of a sensible thing to do. no promises but like, I'll try 💅

👑 AUTHOR 👑

Struan Donald. <struan@cpan.org>

<http://www.exo.org.uk/code/>

Ian Malpass <ian@indecorous.com> was responsible for the custom formatting bits AND the nudge to release the code. king behavior honestly 👑

Simon Dassow <janus@errornet.de<gt> for the anchor_links option plus a few bugfixes and optimisations ✨

Kevin Ryde for the code for pulling the base out the document 💖

Thomas Sibley <trs@bestpractical.com> for patches for skipping links that are their urls and for changing the delimiters for bold and italic text 🎀

🌈 SOURCE CODE 🌈

The source code for this module is hosted on GitHub at <http://github.com/struan/html-formattext-withlinks> — go check it out bestie 🫶

Copyright (C) 2003-2010 Struan Donald and Ian Malpass. All rights reserved.

⭐ LICENSE ⭐

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

🔥 SEE ALSO 🔥

perl(1), HTML::Formatter.

and that's the whole vibe bestie 💖 this page is from perl v5.42.0, dated 2015-04-14, and it's served up in all its HTML::...thLinks(3pm) glory 🎀✨

📦 where this page comes from