1Inline::Files(3) User Contributed Perl Documentation Inline::Files(3)
2
6 Inline::Files - Multiple virtual files at the end of your code
7
9 This document describes version 0.69 of Inline::Files, released June
10 24, 2015.
11
13 use Inline::Files;
14 my Code $here;
16 # etc.
18 # etc.
19 # etc.
20 __FOO__
22 This is a virtual file at the end
23 of the data
24 __BAR__
26 This is another
27 virtual
28 file
30 __FOO__
31 This is yet another
32 such file
33
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 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
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 When you add the line:
52 use Inline::Files;
54 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 __SOME_SYMBOL_NAME_IN_UPPER_CASE__
60 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 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 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 use Inline::Files;
78 while (<FILE>) {
80 print "$FILE: $_";
81 }
82 __FILE__
84 File 1
85 here
86 __FILE__
88 File 2
89 here
90 __OTHER_FILE__
92 Other file 1
93 __FILE__
95 File 3
96 here
97 or as a series of individual files:
99 use Inline::Files;
101 foreach $filename (@FILE) {
103 open HANDLE, $filename;
104 print "<<$filename>>\n";
105 while (<HANDLE>) {
106 print;
107 }
108 }
109 __FILE__
111 File 1
112 here
113 __FILE__
115 File 2
116 here
117 __OTHER_FILE__
119 Other file 1
120 __FILE__
122 File 3
123 here
124 Note that these two examples completely ignore the lines:
126 __OTHER_FILE__
128 Other file 1
129 which would be accessed via the "OTHER_FILE" filehandle.
131 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 $WHATEVER{file}
138 The name of the disk file in which the inlined "__WHATEVER__" files
139 were defined;
140 $WHATEVER{line}
142 The line (starting from 1) at which the current inline
143 "__WHATEVER__" file being accessed by "<WHATEVER>" started.
144 $WHATEVER{offset}
146 The byte offset (starting from 0) at which the current inline
147 "__WHATEVER__" file being accessed by "<WHATEVER>" started.
148 $WHATEVER{writable}
150 Whether the the current inline file being accessed by "<WHATEVER>"
151 is opened for output.
152 The hash and its elements are read-only and the entry values are only
154 meaningful when the corresponding filehandle is open.
155 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 use Inline::Files;
162 use Data::Dumper;
163 open CACHE or die $!; # read access (uses $CACHE to locate file)
165 eval join "", <CACHE>;
166 close CACHE or die $!;
167 print "\$var was '$var'\n";
169 while (<>) {
170 chomp;
171 $var = $_;
172 print "\$var now '$var'\n";
173 }
174 open CACHE, ">$CACHE" or die $!; # write access
176 print CACHE Data::Dumper->Dump([$var],['var']);
177 close CACHE or die $!;
178 __CACHE__
180 $var = 'Original value';
181 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 use Inline::Files;
187 use Data::Dumper;
188 eval join "", <CACHE>; # Automagically opened
190 print "\$var was '$var'\n";
192 while (<>) {
193 chomp;
194 $var = $_;
195 print "\$var now '$var'\n";
196 }
197 seek CACHE, 0, 0;
199 print CACHE Data::Dumper->Dump([$var],['var']);
200 __CACHE__
202 $var = 'Original value';
203 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 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 use Inline::Files;
214 open IFILE, '>';
216 print IFILE "This line will be placed into a new Inline file\n";
218 print IFILE "which is marked by '__IFILE__'\n";
219 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 If Inline::Files is loaded with the "-backup" option:
226 use Inline::Files -backup;
228 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 You can also specify a different name for the backup file, by
234 associating that name with the "-backup" flag:
235 use Inline::Files -backup => '/tmp/sauve_qui_peut';
237
239 The Inline::Files::Virtual module
240 The Filter::Util::Call module
242 BUGS ADDED BY
244 Alberto Simoes (ambs@cpan.org)
245
247 Damian Conway (damian@conway.org)
248
250 Brian Ingerson (INGY@cpan.org)
251
253 Copyright (c) 2001-2009. Damian Conway. All rights reserved.
254 This module is free software; you can redistribute it and/or modify it
256 under the same terms as Perl itself.
257 See http://www.perl.com/perl/misc/Artistic.html
259perl v5.30.1 2020-01-30 Inline::Files(3)