HTML::Copy(3pm)

HTML::Copy 💖

okay bestie, listen. this is HTML::Copy — a little module whose whole entire job is: copy a HTML file without breaking links. that's it. that's the girlboss moment. 🎀

---

✨ VERSION ✨

Version 1.31 🌸

---

✨ SYNOPSIS ✨

like, here's how you'd actually use her:

use HTML::Copy;

HTML::Copy->htmlcopy($source_path, $destination_path);

# or

$p = HTML::Copy->new($source_path);
$p->copy_to($destination_path);

# or

open my $in, "<", $source_path;
$p = HTML::Copy->new($in)
$p->source_path($source_path);    # can be omitted,
                                  # when $source_path is in cwd.

$p->destination_path($destination_path) # can be omitted,
                                        # when $source_path is in cwd.
open my $out, ">", $source_path;
$p->copy_to($out);

pick your fighter, they all slay 💅

---

✨ DESCRIPTION ✨

so basically this module copies a HTML file without breaking the links inside it. that's the whole vibe check, and she passes it. 🌈

and plot twist — this module is a sub class of HTML::Parser. she's literally built different, she inherited the parser genes. 🧬✨

---

✨ REQUIRED MODULES ✨

• HTML::Parser

that's the one. the only one. iconic minimalism honestly. 👑

---

✨ CLASS METHODS ✨

htmlcopy

HTML::Copy->htmlcopy($source_path, $destination_path);

she parses what's inside $source_path, swaps the links around, and writes the whole thing into $destination_path. one call, done, no notes. 🦋

parse_file

$html_text = HTML::Copy->parse_file($source_path,
                                    $destination_path);

parses $source_path, changes links like it's about to copy into $destination_path… but does NOT create $destination_path. nope. she just returns the modified HTML to you. the encoding of strings gets converted into utf8. 💫

---

✨ CONSTRUCTOR METHODS ✨

new

$p = HTML::Copy->new($source);

makes you an instance of this module, and you hand her a source of HTML.

now, $source can be either a file path or a file handle. if you pass a file handle, you might need to tell her where that handle actually lives using the source_path method. and if you don't call source_path? she assumes the location of the file handle is the current working directory. fair enough bestie, she's trusting like that. 🙈

---

✨ INSTANCE METHODS ✨

copy_to

$p->copy_to($destination);

parses the contents of $source that you gave her back in new, changes the links, and writes into $destination. ✍️

$destination can be a file path or a file handle. when it's a file handle, you may need to tell her where that handle is with the destination_path method. and listen — destination_path must be called BEFORE calling copy_to. order matters, bestie, she's not psychic. 😭

and if destination_path is never called at all? she assumes the location of the file handle is the current working directory. (the docs spell it "locaiton" here and honestly? we love her anyway.) 💜

parse_to

$p->parse_to($destination_path)

parses the contents of $source_path that you gave her in new, changes the links, and returns the HTML contents that were meant for $destination_path. unlike copy_to, $destination_path will not be created — she just hands you the modified HTML. and yep, the encoding of strings gets converted into utf8. same energy, different delivery. 🍓

---

✨ ACCESSOR METHODS ✨

source_path

$p->source_path
$p->source_path($path)

gets and sets a source location. usually you set this with the new method and call it a day. but when a file handle is passed to new and the location of that file handle is not the current working directory, that's your cue — use this method. 🫶

destination_path

$p->destination_path
$p->destination_path($path)

gets and sets a destination location. usually it's specified with copy_to. when a file handle is passed to copy_to and the location of that file handle is not the current working directory, you need to use this one before copy_to. timing is everything, periodt. ⏰💅

enchoding

$p->encoding;

gets you the encoding of the source HTML. (yes the heading says enchoding and the code says encoding — we are simply reporting the lore, no cap. 📖✨)

io_layer

$p->io_layer;
$p->io_layer(':utf8');

gets and sets the PerlIO layer used to read the source path and to write the destination path. usually she figures this out automatically from $source_path's charset tag. and if there's no charset specified? then the Encode::Guess module gets recruited. she guesses, she slays. 🔮

encode_suspects

@suspects = $p->encode_sustects;
$p->encode_suspects(qw/shiftjis euc-jp/);

adds suspects of text encoding, so she can guess the text encoding of the source HTML. if the source HTML has a charset tag, you don't need to add suspects at all. (and yes, that first line really does say encode_sustects in the docs — we're keeping it exactly as it is, character for character. the typo is part of the canon. 💀)

source_html

$p->source_html;

obtains the source HTML's contents. that's it, that's the method. 🌸

---

✨ NOTE ✨

okay this one is IMPORTANT bestie, do not skip it.

Cleanuped pathes should be given to HTML::Copy and it's instances. for example, a verbose path like '/aa/bb/../cc' may cause converting links wrongly. 😭 this is a limitation of the URI module's rel method — not her fault, she's doing her best. to cleanup pathes, Cwd::realpath is useful. use it. love it. 🔥

---

✨ AUTHOR ✨

Tetsuro KURITA <tkurita@mac.com> 🫶

---

and that's the whole page, bestie — perl v5.34.0, dated 2022-06-14, brought to you by the one and only HTML::Copy(3pm). go copy some files and break zero links. mwah. 💖✨🎀