.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Inline::Files 3pm"
.TH Inline::Files 3pm "2022-12-06" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Inline::Files \- Multiple virtual files at the end of your code
.SH "VERSION"
.IX Header "VERSION"
This document describes version 0.69 of Inline::Files,
released June 24, 2015.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    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
.Ve
.SH "WARNING"
.IX Header "WARNING"
It is possible that this module may overwrite the source code in files
that use it. To protect yourself against this possibility, you are
\&\fIstrongly\fR advised to use the \f(CW\*(C`\-backup\*(C'\fR option described in
\&\*(L"Safety first\*(R".
.PP
This module is still experimental. Regardless of whether you use
\&\f(CW\*(C`\-backup\*(C'\fR or not, by using this module you agree that the authors will
b<under no circumstances> be responsible for any loss of data, code,
time, money, or limbs, or for any other disadvantage incurred as a
result of using Inline::Files.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Inline::Files generalizes the notion of the \f(CW\*(C`_\|_DATA_\|_\*(C'\fR marker and the
associated \f(CW\*(C`<DATA>\*(C'\fR filehandle, to an arbitrary number of markers
and associated filehandles.
.PP
When you add the line:
.PP
.Vb 1
\&    use Inline::Files;
.Ve
.PP
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 of the form:
.PP
.Vb 1
\&    _\|_SOME_SYMBOL_NAME_IN_UPPER_CASE_\|_
.Ve
.PP
The following text \*(-- up to the next such marker \*(-- is treated as a
file, whose (pseudo\-)name is available as an element of the package
array \f(CW@SOME_SYMBOL_NAME_IN_UPPER_CASE\fR. The name of the first virtual
file with this marker is also available as the package scalar
\&\f(CW$SOME_SYMBOL_NAME_IN_UPPER_CASE\fR.
.PP
The filehandle of the same name is magical \*(-- just like \f(CW\*(C`ARGV\*(C'\fR \*(-- in
that it automatically opens itself when first read. Furthermore \*(-- just
like \f(CW\*(C`ARGV\*(C'\fR \*(-- the filehandle re-opens itself to the next appropriate
virtual file (by \f(CW\*(C`shift\*(C'\fR\-ing the first element of
\&\f(CW@SOME_SYMBOL_NAME_IN_UPPER_CASE\fR into
\&\f(CW$SOME_SYMBOL_NAME_IN_UPPER_CASE\fR) whenever it reaches \s-1EOF.\s0
.PP
So, just as with \f(CW\*(C`ARGV\*(C'\fR, you can treat all the virtual files associated
with a single symbol either as a single, multi-part file:
.PP
.Vb 1
\&    use Inline::Files;
\&
\&    while (<FILE>) {
\&        print "$FILE: $_";
\&    }
\&
\&    _\|_FILE_\|_
\&    File 1
\&    here
\&
\&    _\|_FILE_\|_
\&    File 2
\&    here
\&
\&    _\|_OTHER_FILE_\|_
\&    Other file 1
\&
\&    _\|_FILE_\|_
\&    File 3
\&    here
.Ve
.PP
or as a series of individual files:
.PP
.Vb 1
\&    use Inline::Files;
\&
\&    foreach $filename (@FILE) {
\&        open HANDLE, $filename;
\&        print "<<$filename>>\en";
\&        while (<HANDLE>) {
\&            print;
\&        }
\&    }
\&
\&    _\|_FILE_\|_
\&    File 1
\&    here
\&
\&    _\|_FILE_\|_
\&    File 2
\&    here
\&
\&    _\|_OTHER_FILE_\|_
\&    Other file 1
\&
\&    _\|_FILE_\|_
\&    File 3
\&    here
.Ve
.PP
Note that these two examples completely ignore the lines:
.PP
.Vb 2
\&    _\|_OTHER_FILE_\|_
\&    Other file 1
.Ve
.PP
which would be accessed via the \f(CW\*(C`OTHER_FILE\*(C'\fR filehandle.
.PP
Unlike \f(CW\*(C`<ARGV>\*(C'\fR/\f(CW@ARGV\fR/\f(CW$ARGV\fR, Inline::Files also makes use of
the hash associated with an inline file's symbol. That is, when you create
an inline file with a marker \f(CW\*(C`_\|_WHATEVER_\|_\*(C'\fR, the hash \f(CW%WHATEVER\fR will
contain information about that file. That information is:
.ie n .IP "$WHATEVER{file}" 4
.el .IP "\f(CW$WHATEVER{file}\fR" 4
.IX Item "$WHATEVER{file}"
The name of the disk file in which the inlined \f(CW\*(C`_\|_WHATEVER_\|_\*(C'\fR files
were defined;
.ie n .IP "$WHATEVER{line}" 4
.el .IP "\f(CW$WHATEVER{line}\fR" 4
.IX Item "$WHATEVER{line}"
The line (starting from 1) at which the current inline \f(CW\*(C`_\|_WHATEVER_\|_\*(C'\fR
file being accessed by \f(CW\*(C`<WHATEVER>\*(C'\fR started.
.ie n .IP "$WHATEVER{offset}" 4
.el .IP "\f(CW$WHATEVER{offset}\fR" 4
.IX Item "$WHATEVER{offset}"
The byte offset (starting from 0) at which the current inline
\&\f(CW\*(C`_\|_WHATEVER_\|_\*(C'\fR file being accessed by \f(CW\*(C`<WHATEVER>\*(C'\fR started.
.ie n .IP "$WHATEVER{writable}" 4
.el .IP "\f(CW$WHATEVER{writable}\fR" 4
.IX Item "$WHATEVER{writable}"
Whether the the current inline file being accessed by
\&\f(CW\*(C`<WHATEVER>\*(C'\fR is opened for output.
.PP
The hash and its elements are read-only and the entry values are only
meaningful when the corresponding filehandle is open.
.SS "Writable virtual files"
.IX Subsection "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. For
example, here is a very simple persistence mechanism:
.PP
.Vb 2
\&    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 "\e$var was \*(Aq$var\*(Aq\en";
\&    while (<>) {
\&        chomp;
\&        $var = $_;
\&        print "\e$var now \*(Aq$var\*(Aq\en";
\&    }
\&
\&    open CACHE, ">$CACHE" or die $!;    # write access
\&    print CACHE Data::Dumper\->Dump([$var],[\*(Aqvar\*(Aq]);
\&    close CACHE or die $!;
\&
\&    _\|_CACHE_\|_
\&    $var = \*(AqOriginal value\*(Aq;
.Ve
.PP
\&\fIUnlike\fR \f(CW\*(C`ARGV\*(C'\fR, if a virtual file is part of a writable file and is
automagically opened, it is opened for full read/write access. So the
above example, could be even simpler:
.PP
.Vb 2
\&    use Inline::Files;
\&    use Data::Dumper;
\&
\&    eval join "", <CACHE>;      # Automagically opened
\&
\&    print "\e$var was \*(Aq$var\*(Aq\en";
\&    while (<>) {
\&        chomp;
\&        $var = $_;
\&        print "\e$var now \*(Aq$var\*(Aq\en";
\&    }
\&
\&    seek CACHE, 0, 0;
\&    print CACHE Data::Dumper\->Dump([$var],[\*(Aqvar\*(Aq]);
\&
\&    _\|_CACHE_\|_
\&    $var = \*(AqOriginal value\*(Aq;
.Ve
.PP
In either case, the original file is updated only at the end of
execution, on an explicit \f(CW\*(C`close\*(C'\fR of the virtual file's handle, or when
\&\f(CW\*(C`Inline::Files::Virtual::vf_save\*(C'\fR is explicitly called.
.SS "Creating new Inline files on the fly."
.IX Subsection "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 \fBno\fR file name. Like this:
.PP
.Vb 1
\&    use Inline::Files;
\&
\&    open IFILE, \*(Aq>\*(Aq;
\&
\&    print IFILE "This line will be placed into a new Inline file\en";
\&    print IFILE "which is marked by \*(Aq_\|_IFILE_\|_\*(Aq\en";
.Ve
.SS "Safety first"
.IX Subsection "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.
.PP
If Inline::Files is loaded with the \f(CW\*(C`\-backup\*(C'\fR option:
.PP
.Vb 1
\&    use Inline::Files \-backup;
.Ve
.PP
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
\&\*(L".bak\*(R" appended.
.PP
You can also specify a different name for the backup file, by associating that
name with the \f(CW\*(C`\-backup\*(C'\fR flag:
.PP
.Vb 1
\&    use Inline::Files \-backup => \*(Aq/tmp/sauve_qui_peut\*(Aq;
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
The Inline::Files::Virtual module
.PP
The Filter::Util::Call module
.SS "\s-1BUGS ADDED BY\s0"
.IX Subsection "BUGS ADDED BY"
Alberto Simoes  (ambs@cpan.org)
.SH "UNWITTING PAWN OF AN AUTHOR"
.IX Header "UNWITTING PAWN OF AN AUTHOR"
Damian Conway  (damian@conway.org)
.SH "EVIL MASTERMIND BEHIND IT ALL"
.IX Header "EVIL MASTERMIND BEHIND IT ALL"
Brian Ingerson (INGY@cpan.org)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2001\-2009. Damian Conway. All rights reserved.
.PP
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
.PP
See http://www.perl.com/perl/misc/Artistic.html