Inline::Files(3pm)

📦
version 0.71 · 5 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 Inline::Files 💖

okay so bestie, welcome to Inline::Files(3pm) — the manual page for Inline::Files, aka Multiple virtual files at the end of your code. yes you read that right. files. at the end. of your code. it's giving unhinged and i'm obsessed 🫶

✨ VERSION ✨

This doc is describing version 0.69 of Inline::Files, which dropped on June 24, 2015. vintage. iconic. still slaying 💅

🌸 SYNOPSIS 🌸

    use Inline::Files;

    my Code $here;

    # etc.
    # etc.
    # etc.

    __FOO__
    This is a virtual file at the end
    of the data

    __BAR__
    This is another
    virtual

    file
    __FOO__
    This is yet another
    such file

look at that. three whole virtual files just vibing at the bottom of your script 🌈

⚠️ WARNING ⚠️

ngl, this is the part where you sit up straight, bestie.

It is possible that this module may overwrite the source code in files that use it. 💀

to protect yourself from that whole situation, you are strongly advised to use the -backup option, which we'll get to in "Safety first" (yes that's a real section, the module is self-aware).

also: this module is still experimental. so whether or not you use -backup, by using this module you agree that the authors will be under no circumstances responsible for any loss of data, code, time, money, or limbs, or for any other disadvantage incurred as a result of using Inline::Files.

(limbs. they said limbs. the original literally has a stray b<> pod tag right there too — we stan a typo with range 😭)

🦋 DESCRIPTION 🦋

So here's the tea 🍵: Inline::Files takes the whole __DATA__ marker + <DATA> filehandle concept and generalizes it to an arbitrary number of markers and their associated filehandles. no cap.

The moment you add this line:

    use Inline::Files;

to a source file, you can then specify an arbitrary number of distinct virtual files at the end of the code. each such virtual file is marked by a line that looks like this:

    __SOME_SYMBOL_NAME_IN_UPPER_CASE__

The text that follows it — up until the next such marker — is treated as a file. its (pseudo-)name is available as an element of the package array @SOME_SYMBOL_NAME_IN_UPPER_CASE. and the name of the first virtual file with that marker is also available as the package scalar $SOME_SYMBOL_NAME_IN_UPPER_CASE.

Now the filehandle of the same name is magical ✨ — just like ARGV — in that it automatically opens itself the first time you read from it. and furthermore, also just like ARGV, the filehandle re-opens itself to the next appropriate virtual file (by shift-ing the first element of @SOME_SYMBOL_NAME_IN_UPPER_CASE into $SOME_SYMBOL_NAME_IN_UPPER_CASE) whenever it hits EOF.

so, just as with ARGV, you can treat all the virtual files attached to a single symbol either as one single, multi-part file:

    use Inline::Files;

    while (<FILE>) {
        print "$FILE: $_";
    }

    __FILE__
    File 1
    here

    __FILE__
    File 2
    here

    __OTHER_FILE__
    Other file 1

    __FILE__
    File 3
    here

or as a series of individual files:

    use Inline::Files;

    foreach $filename (@FILE) {
        open HANDLE, $filename;
        print "<<$filename>>\n";
        while (<HANDLE>) {
            print;
        }
    }

    __FILE__
    File 1
    here

    __FILE__
    File 2
    here

    __OTHER_FILE__
    Other file 1

    __FILE__
    File 3
    here

btw heads up: both of these examples completely ignore these lines:

    __OTHER_FILE__
    Other file 1

...which would be accessed via the OTHER_FILE filehandle. they're just sitting there, unbothered, moisturized, in their lane 💅

Unlike <ARGV>/@ARGV/$ARGV, Inline::Files also makes use of the hash associated with an inline file's symbol. so when you create an inline file with a marker __WHATEVER__, the hash %WHATEVER will contain info about that file. and that info is:

  • $WHATEVER{file} — the name of the disk file in which the inlined __WHATEVER__ files were defined;
  • $WHATEVER{line} — the line (starting from 1) at which the current inline __WHATEVER__ file being accessed by <WHATEVER> started;
  • $WHATEVER{offset} — the byte offset (starting from 0) at which the current inline __WHATEVER__ file being accessed by <WHATEVER> started;
  • $WHATEVER{writable} — whether the the current inline file being accessed by <WHATEVER> is opened for output.
(yes, "the the". that's canon. don't come for me, come for the source 🍓)

The hash and its elements are read-only, and the entry values are only meaningful when the corresponding filehandle is open.

📝 Writable virtual files 📝

If the source file that uses Inline::Files is itself writable, then the virtual files it contains may also be opened for write access. periodt.

for example, here's a very simple persistence mechanism:

    use Inline::Files;
    use Data::Dumper;

    open CACHE or die $!;   # read access (uses $CACHE to locate file)
    eval join "", <CACHE>;
    close CACHE or die $!;

    print "\$var was '$var'\n";
    while (<>) {
        chomp;
        $var = $_;
        print "\$var now '$var'\n";
    }

    open CACHE, ">$CACHE" or die $!;    # write access
    print CACHE Data::Dumper->Dump([$var],['var']);
    close CACHE or die $!;

    __CACHE__
    $var = 'Original value';

Unlike ARGV, if a virtual file is part of a writable file and gets automagically opened, it's opened for full read/write access. so the example above could be even simpler:

    use Inline::Files;
    use Data::Dumper;

    eval join "", <CACHE>;      # Automagically opened

    print "\$var was '$var'\n";
    while (<>) {
        chomp;
        $var = $_;
        print "\$var now '$var'\n";
    }

    seek CACHE, 0, 0;
    print CACHE Data::Dumper->Dump([$var],['var']);

    __CACHE__
    $var = 'Original value';

In either case, the original file is updated only at the end of execution, on an explicit close of the virtual file's handle, or when Inline::Files::Virtual::vf_save is explicitly called. no early saves, bestie. the file waits for the finale 🎀

🎀 Creating new Inline files on the fly. 🎀

You can also open up new Inline output files at run time. simply use the open function with a valid new Inline file handle name and no file name. like this:

    use Inline::Files;

    open IFILE, '>';

    print IFILE "This line will be placed into a new Inline file\n";
    print IFILE "which is marked by '__IFILE__'\n";

manifesting new virtual files out of thin air. main character energy fr fr 🔥

🛟 Safety first 🛟

Because Inline::Files handles are often read-write, it's possible to accidentally nuke your hard-won data 💀. but Inline::Files can save you from yourself. iconic of it.

If Inline::Files is loaded with the -backup option:

    use Inline::Files -backup;

then the source file that uses it is backed up before the inline files are extracted. the backup file is the name of the source file with the suffix .bak appended.

You can also specify a different name for the backup file, by associating that name with the -backup flag:

    use Inline::Files -backup => '/tmp/sauve_qui_peut';

protect your files, protect your peace 🌸

👀 SEE ALSO 👀

  • The Inline::Files::Virtual module
  • The Filter::Util::Call module

🐛 BUGS ADDED BY 🐛

Alberto Simoes (ambs@cpan.org)

🙈 UNWITTING PAWN OF AN AUTHOR 🙈

Damian Conway (damian@conway.org)

👑 EVIL MASTERMIND BEHIND IT ALL 👑

Brian Ingerson (INGY@cpan.org)

Copyright (c) 2001-2009. Damian Conway. All rights reserved.

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

See http://www.perl.com/perl/misc/Artistic.html

and that's the whole page, bestie 🫶 this documentation came to you courtesy of perl v5.36.0, dated 2022-12-06 — go forth, make virtual files, and please use -backup. mwah 💖✨

📦 where this page comes from