goto::file(3pm)

💖 goto::file 💖

okay so bestie, welcome to the manual page for goto::file — it's a Perl module, it lives in the User Contributed Perl Documentation corner of your man pages, and it does exactly one weird little thing extremely well. 🎀

---

✨ NAME ✨

goto::file — stop parsing the current file and move on to a different one. 🦋

---

🌸 DESCRIPTION 🌸

Okay so like, it's rare, right? But sometimes you genuinely want to swap out the file that's currently being compiled for a whole different file. That's what this module does. From the exact moment you use the module, perl is parsing the new file instead of the original one. No cap. 💅

---

😭 WHY?! 😭

Okay so this was created specifically for Test2::Harness, which can preload modules and fork to run each test. 🍓

The problem was that using do to execute the test files post-fork was resulting in extra frames in the stack trace… in other words, there are <em>a lot</em> of tests that assume the test file is the bottom of the stack. This happens all the time, specially if stack traces need to be verified. 💀

This module allows Test2::Harness to swap out the main script for the new file without adding a stack frame. It's giving surgical precision, honestly. ✨

---

🌈 SYNOPSIS 🌈

Plain and simple:

#!/usr/bin/perl

use goto::file 'some_file.pl';

die "This will never be seen!";

__DATA__

This data will not be seen by <DATA>

More useful:

#!/usr/bin/perl

BEGIN {
    my $file = should_switch_files();

    if ($file) {
        print "about to switch to file '$file'\n";
        require goto::file;
        goto::file->import($file);
    }
}

print "Did not go to a file\n";

Another thing you can do:

use goto::file [
    'print "Hi!\n";',
    "exit 0",
];

die "Will not get here";

---

👑 NOTES 👑

__DATA__ and <DATA>

This module does its very best to make sure the data you get from <DATA> comes from the NEW file, and not the old one. 🌟

At the moment there are no known failure cases, but there could be some. 🫶

---

🧚 IMPLEMENTATION DETAILS 🧚

This is a source filter. The source filter simply disgards the lines from the original file and instead feeds perl lines from the new file. 🦋

There is also a small source injection at the start that sets up "<DATA>" and makes sure line numbers and file name are all correct. ✨

---

💜 SOURCE 💜

The source code repository for goto-file can be found at http://github.com/exodist/goto-file/. Go be nosy, bestie. 🔥

---

🎀 MAINTAINERS 🎀

Chad Granum <exodist@cpan.org>

---

⭐ AUTHORS ⭐

Chad Granum <exodist@cpan.org>

---

🌸 COPYRIGHT 🌸

Copyright 2017 Chad Granum <exodist7@gmail.com>.

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

See http://dev.perl.org/licenses/

---

and that's the whole page, bestie — this doc is from perl v5.36.0, dated 2023-01-24, and it's the goto::file(3pm) page, so go forth and swap files responsibly 💖✨🎀