1Inline::Files(3)      User Contributed Perl Documentation     Inline::Files(3)
2
3
4

NAME

6       Inline::Files - Multiple virtual files at the end of your code
7

VERSION

9       This document describes version 0.69 of Inline::Files, released June
10       24, 2015.
11

SYNOPSIS

13           use Inline::Files;
14
15           my Code $here;
16
17           # etc.
18           # etc.
19           # etc.
20
21           __FOO__
22           This is a virtual file at the end
23           of the data
24
25           __BAR__
26           This is another
27           virtual
28
29           file
30           __FOO__
31           This is yet another
32           such file
33

WARNING

35       It is possible that this module may overwrite the source code in files
36       that use it. To protect yourself against this possibility, you are
37       strongly advised to use the "-backup" option described in "Safety
38       first".
39
40       This module is still experimental. Regardless of whether you use
41       "-backup" or not, by using this module you agree that the authors will
42       b<under no circumstances> be responsible for any loss of data, code,
43       time, money, or limbs, or for any other disadvantage incurred as a
44       result of using Inline::Files.
45

DESCRIPTION

47       Inline::Files generalizes the notion of the "__DATA__" marker and the
48       associated "<DATA>" filehandle, to an arbitrary number of markers and
49       associated filehandles.
50
51       When you add the line:
52
53           use Inline::Files;
54
55       to a source file you can then specify an arbitrary number of distinct
56       virtual files at the end of the code. Each such virtual file is marked
57       by a line of the form:
58
59           __SOME_SYMBOL_NAME_IN_UPPER_CASE__
60
61       The following text -- up to the next such marker -- is treated as a
62       file, whose (pseudo-)name is available as an element of the package
63       array @SOME_SYMBOL_NAME_IN_UPPER_CASE. The name of the first virtual
64       file with this marker is also available as the package scalar
65       $SOME_SYMBOL_NAME_IN_UPPER_CASE.
66
67       The filehandle of the same name is magical -- just like "ARGV" -- in
68       that it automatically opens itself when first read. Furthermore -- just
69       like "ARGV" -- the filehandle re-opens itself to the next appropriate
70       virtual file (by "shift"-ing the first element of
71       @SOME_SYMBOL_NAME_IN_UPPER_CASE into $SOME_SYMBOL_NAME_IN_UPPER_CASE)
72       whenever it reaches EOF.
73
74       So, just as with "ARGV", you can treat all the virtual files associated
75       with a single symbol either as a single, multi-part file:
76
77           use Inline::Files;
78
79           while (<FILE>) {
80               print "$FILE: $_";
81           }
82
83           __FILE__
84           File 1
85           here
86
87           __FILE__
88           File 2
89           here
90
91           __OTHER_FILE__
92           Other file 1
93
94           __FILE__
95           File 3
96           here
97
98       or as a series of individual files:
99
100           use Inline::Files;
101
102           foreach $filename (@FILE) {
103               open HANDLE, $filename;
104               print "<<$filename>>\n";
105               while (<HANDLE>) {
106                   print;
107               }
108           }
109
110           __FILE__
111           File 1
112           here
113
114           __FILE__
115           File 2
116           here
117
118           __OTHER_FILE__
119           Other file 1
120
121           __FILE__
122           File 3
123           here
124
125       Note that these two examples completely ignore the lines:
126
127           __OTHER_FILE__
128           Other file 1
129
130       which would be accessed via the "OTHER_FILE" filehandle.
131
132       Unlike "<ARGV>"/@ARGV/$ARGV, Inline::Files also makes use of the hash
133       associated with an inline file's symbol. That is, when you create an
134       inline file with a marker "__WHATEVER__", the hash %WHATEVER will
135       contain information about that file. That information is:
136
137       $WHATEVER{file}
138           The name of the disk file in which the inlined "__WHATEVER__" files
139           were defined;
140
141       $WHATEVER{line}
142           The line (starting from 1) at which the current inline
143           "__WHATEVER__" file being accessed by "<WHATEVER>" started.
144
145       $WHATEVER{offset}
146           The byte offset (starting from 0) at which the current inline
147           "__WHATEVER__" file being accessed by "<WHATEVER>" started.
148
149       $WHATEVER{writable}
150           Whether the the current inline file being accessed by "<WHATEVER>"
151           is opened for output.
152
153       The hash and its elements are read-only and the entry values are only
154       meaningful when the corresponding filehandle is open.
155
156   Writable virtual files
157       If the source file that uses Inline::Files is itself writable, then the
158       virtual files it contains may also be opened for write access. For
159       example, here is a very simple persistence mechanism:
160
161           use Inline::Files;
162           use Data::Dumper;
163
164           open CACHE or die $!;   # read access (uses $CACHE to locate file)
165           eval join "", <CACHE>;
166           close CACHE or die $!;
167
168           print "\$var was '$var'\n";
169           while (<>) {
170               chomp;
171               $var = $_;
172               print "\$var now '$var'\n";
173           }
174
175           open CACHE, ">$CACHE" or die $!;    # write access
176           print CACHE Data::Dumper->Dump([$var],['var']);
177           close CACHE or die $!;
178
179           __CACHE__
180           $var = 'Original value';
181
182       Unlike "ARGV", if a virtual file is part of a writable file and is
183       automagically opened, it is opened for full read/write access. So the
184       above example, could be even simpler:
185
186           use Inline::Files;
187           use Data::Dumper;
188
189           eval join "", <CACHE>;      # Automagically opened
190
191           print "\$var was '$var'\n";
192           while (<>) {
193               chomp;
194               $var = $_;
195               print "\$var now '$var'\n";
196           }
197
198           seek CACHE, 0, 0;
199           print CACHE Data::Dumper->Dump([$var],['var']);
200
201           __CACHE__
202           $var = 'Original value';
203
204       In either case, the original file is updated only at the end of
205       execution, on an explicit "close" of the virtual file's handle, or when
206       "Inline::Files::Virtual::vf_save" is explicitly called.
207
208   Creating new Inline files on the fly.
209       You can also open up new Inline output files at run time. Simply use
210       the open function with a valid new Inline file handle name and no file
211       name. Like this:
212
213           use Inline::Files;
214
215           open IFILE, '>';
216
217           print IFILE "This line will be placed into a new Inline file\n";
218           print IFILE "which is marked by '__IFILE__'\n";
219
220   Safety first
221       Because Inline::Files handles are often read-write, it's possible to
222       accidentally nuke your hard-won data. But Inline::Files can save you
223       from yourself.
224
225       If Inline::Files is loaded with the "-backup" option:
226
227           use Inline::Files -backup;
228
229       then the source file that uses it is backed up before the inline files
230       are extracted. The backup file is the name of the source file with the
231       suffix ".bak" appended.
232
233       You can also specify a different name for the backup file, by
234       associating that name with the "-backup" flag:
235
236           use Inline::Files -backup => '/tmp/sauve_qui_peut';
237

SEE ALSO

239       The Inline::Files::Virtual module
240
241       The Filter::Util::Call module
242
243   BUGS ADDED BY
244       Alberto Simoes  (ambs@cpan.org)
245

UNWITTING PAWN OF AN AUTHOR

247       Damian Conway  (damian@conway.org)
248

EVIL MASTERMIND BEHIND IT ALL

250       Brian Ingerson (INGY@cpan.org)
251
253       Copyright (c) 2001-2009. Damian Conway. All rights reserved.
254
255       This module is free software; you can redistribute it and/or modify it
256       under the same terms as Perl itself.
257
258       See http://www.perl.com/perl/misc/Artistic.html
259
260
261
262perl v5.34.0                      2022-01-21                  Inline::Files(3)
Impressum