Inline...irtual(3pm)

💖 NAME 💖

Inline::Files::Virtual — okay so picture this: multiple virtual files, all chillin' inside one single file. That's the whole vibe. It's a User Contributed Perl Documentation page, section 3pm, and she's iconic but also kind of feral. 🫶

---

🌸 VERSION 🌸

This doc describes version 0.53 of Inline::Files::Virtual, released May 25, 2001. Yeah bestie, she's vintage. Vintage = retro = slay. ✨

---

✨ SYNOPSIS ✨

use Inline::Files::Virtual;

# Load actual file, extracting virtual files that start with "^<VF>\n"
@virtual_filenames = vf_load($actual_file, "^<VF>\n");

# Open one of the virtual files for reading
open(FILE, $virtual_filenames[0]) or die;

print while <FILE>;

close(FILE);

# Open one of the virtual files for appending
open(FILE, ">> $virtual_filenames[1]") or die;

print FILE "extra text";
printf FILE "%6.2", $number;

close(FILE);

# Actual file will be updated at this point

Like, you literally just open a filename and the module goes "oh bet, that's a virtual file" and handles it. Main character energy fr fr. 👑

---

💀 WARNING 💀

This module is still experimental. And not in a cute "oops teehee" way. Careless use of it will almost certainly cause the source code in files that use it to be overwritten. 😭 Like, your actual literal code. Gone. Poof.

You are strongly advised to use the Inline::Files module instead. That's the glow-up. That's the upgrade.

And if you choose to use this module anyway — you thereby 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. Bestie they are NOT playing. 🙈

---

🦋 DESCRIPTION 🦋

So here's the tea: this module lets you treat a single disk file as a whole collection of virtual files, and then you can individually open each one for reading or writing. Whenever a virtual file gets modified, it gets written back to its actual disk at the end of the program's execution — or earlier, if you explicitly call the vf_save subroutine. ✨

Every virtual file gets introduced by a start-of-virtual-file marker (SOVFM). That marker can be any sequence (or pattern) of characters that marks the beginning of the content of a virtual file. For example, you could use the string "--":

--
Contents of virtual
file number 1
--
Contents of virtual
file number 2
--
Contents of virtual
file number 3

or you could use the pattern /##### \w+ #####/:

##### VF1 #####
Contents of virtual
file number 1
##### VF2 #####
Contents of virtual
file number 2
##### VF3 #####
Contents of virtual
file number 3

Important detail, don't skip it: the SOVFM is not considered to be part of the file contents. It's the label on the box, not the gift inside. 🎀

---

🎀 Interface 🎀

The module exports these methods:

• vf_load $file, $SOVFM_pattern — you call this to load an actual disk file that contains one or more virtual files. The first argument is the name of the file to load, as a string. The second argument is a pattern (either a string or a qr regex) that matches each start-of-virtual-file marker inside the file.

For example, if the file /usr/local/details.dat contains:

=info names

Damian
Nathan
Mephistopheles

=info numbers

555-1212
555-6874
555-3452

=info comment

Mad
Bad
Dangerous to know

then you could load it as three virtual files with:

@virtual_filenames =
        vf_load("/usr/local/details.dat", qr/^=info\s+\S+\s*?\n/);

Heads up bestie: because the actual file is decomposed into virtual files using a split, it is vital that the pattern does not contain any capturing parentheses. No capturing groups. None. Periodt. 💅

On success, vf_load returns a list of virtual filenames for the virtual files. Each virtual filename is the actual name of the file containing the virtual file, concatenated with the offset of the virtual file's SOVFM within the actual file. So that call above would return three virtual filenames:

/usr/local/details.dat(00000000000000000000)
/usr/local/details.dat(00000000000000000048)
/usr/local/details.dat(00000000000000000097)

And whenever you later use any of those virtual filenames in an open, the corresponding virtual file gets opened. 🫶

• vf_save @actual_filenames
• vf_save — this subroutine causes the virtual files belonging to the nominated actual file (or files) to be written back to disk. If vf_save is called without arguments, then all currently loaded virtual files are saved to their respective actual files right at that point.

vf_save is automatically called in an END block at the termination of any program using the module. So she saves your stuff on the way out. 💖

• vf_marker $virtual_filename — this subroutine returns the SOVFM that preceded the nominated virtual file. 🕵️‍♀️

The module also modifies the open, close, print, printf, read, getline, getc, seek, tell, and truncate built-in functions so that they operate correctly on virtual files. Yeah. She edited the builtins. Iconic behaviour. 👑

As a special case, it is also possible to use the raw SOVFM as a virtual file name:

use Inline::Files::Virtual;

vf_load $filename, qr/__[A-Z]+__/;

open FILE, "__MARKER__";

# and in the file that was vf_load-ed

__MARKER__
file contents here

⚠️ But listen: this always opens the very first virtual file with that SOVFM, no matter how often it's called, or how many such markers appear in the file. So like... it's giving "first come first served" and the rest are just standing outside the club. 💀

---

🌈 Handling "implicit" virtual start-of-virtual-file markers 🌈

Sometimes an SOVFM is "implicit". Meaning: instead of being a separate marker for the start of a virtual file, it's actually the first part of the actual data of the virtual file. Sneaky. 🙈

For example, consider this XML file:

<DATA>
        <DESC>This is data set 1</DESC>
        <DATUM/>datum 1
        <DATUM/>datum 2
        <DATUM/>datum 3
</DATA>
<DATA>
        <DESC>This is data set 2</DESC>
        <DATUM/>datum 4
        <DATUM/>datum 5
        <DATUM/>datum 6
</DATA>

Each of the <DATA>...</DATA> blocks could be treated as a separate virtual file by specifying:

@datasets = vf_load("data.xml", '<DATA>');

But plot twist: this would cause the individual virtual files to contain invalid XML, like:

        <DESC>This is data set 1</DESC>
        <DATUM/>datum 1
        <DATUM/>datum 2
        <DATUM/>datum 3
</DATA>

See how the opening <DATA> got eaten and the closing </DATA> is just hanging there like an orphan? Not cute. 😭

You can indicate that the nominated SOVFMs are also part of the virtual files' contents by specifying the markers as a look-ahead pattern:

@datasets = vf_load("data.xml", '(?=<DATA>)');

This causes vf_load to identify the sequence <DATA> as a start-of-virtual-file marker but not consume it, thereby leaving it as the initial sequence of the virtual file's content. Look-ahead = "I see you but I'm not taking you". Respectful. Gorgeous. 💅✨

---

🩺 DIAGNOSTICS 🩺

• Could not vf_load '%s' — the module could not open the specified disk file and read it in as a set of virtual files. 😔
• Unable to complete vf_save — the module could not open the specified disk file and write it out as a set of virtual files. A preceding warning may indicate which virtual file caused the problem. 🔍
• Virtual file not open for input — someone tried to getline, getc, or read a virtual file that was opened for output only. (Warning only) 🙃
• Virtual file not open for output — someone tried to print or printf a virtual file that was opened for input only. (Warning only) 🙃

---

👑 AUTHOR 👑

Damian Conway (damian@conway.org)

😈 EVIL GENIUS WHO MADE HIM DO IT 😈

Brian Ingerson (INGY@cpan.org)

---

📜 COPYRIGHT 📜

Copyright (c) 2001. 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

---

Okay that's the whole page bestie, you're fully caught up. This one shipped with perl v5.36.0, dated 2022-12-06 — mwah, bye, go use Inline::Files instead, ily 💖✨🦋