1Inline::Files::Virtual(U3s)er Contributed Perl DocumentatIinolnine::Files::Virtual(3)
2
6 Inline::Files::Virtual - Multiple virtual files in a single file
7
9 This document describes version 0.53 of Inline::Files::Virtual,
10 released May 25, 2001.
11
13 use Inline::Files::Virtual;
14 # Load actual file, extracting virtual files that start with "^<VF>\n"
16 @virtual_filenames = vf_load($actual_file, "^<VF>\n");
17 # Open one of the virtual files for reading
19 open(FILE, $virtual_filenames[0]) or die;
20 print while <FILE>;
22 close(FILE);
24 # Open one of the virtual files for appending
26 open(FILE, ">> $virtual_filenames[1]") or die;
27 print FILE "extra text";
29 printf FILE "%6.2", $number;
30 close(FILE);
32 # Actual file will be updated at this point
34
36 This module is still experimental. Careless use of it will almost
37 certainly cause the source code in files that use it to be overwritten.
38 You are strongly advised to use the Inline::Files module instead.
39 If you chose to use this module anyway, you thereby agree that the
41 authors will b<under no circumstances> be responsible for any loss of
42 data, code, time, money, or limbs, or for any other disadvantage
43 incurred as a result of using Inline::Files.
44
46 This module allows you to treat a single disk file as a collection of
47 virtual files, which may then be individually opened for reading or
48 writing. Virtual files which have been modified are written back to
49 their actual disk at the end of the program's execution (or earlier if
50 the "vf_save" subroutine is explicitly called).
51 Each such virtual file is introduced by a start-of-virtual-file marker
53 (SOVFM). This may be any sequence (or pattern) of characters that marks
54 the beginning of the content of a virtual file. For example, the string
55 "--" might be used:
56 --
58 Contents of virtual
59 file number 1
60 --
61 Contents of virtual
62 file number 2
63 --
64 Contents of virtual
65 file number 3
66 or the pattern "/##### \w+ #####/":
68 ##### VF1 #####
70 Contents of virtual
71 file number 1
72 ##### VF2 #####
73 Contents of virtual
74 file number 2
75 ##### VF3 #####
76 Contents of virtual
77 file number 3
78 Note that the SOVFM is not considered to be part of the file contents.
80 Interface
82 The module exports the following methods:
83 "vf_load $file, $SOVFM_pattern"
85 This subroutine is called to load an actual disk file containing
86 one or more virtual files. The first argument specifies the name of
87 the file to be loaded as a string. The second argument specifies a
88 pattern (as either a string or "qr" regex) that matches each start-
89 of-virtual-file marker within the file. For example, if the file
90 "/usr/local/details.dat" contains:
91 =info names
93 Damian
95 Nathan
96 Mephistopheles
97 =info numbers
99 555-1212
101 555-6874
102 555-3452
103 =info comment
105 Mad
107 Bad
108 Dangerous to know
109 then you could load it as three virtual files with:
111 @virtual_filenames =
113 vf_load("/usr/local/details.dat", qr/^=info\s+\S+\s*?\n/);
114 Note that, because the actual file is decomposed into virtual files
116 using a "split", it is vital that the pattern does not contain any
117 capturing parentheses.
118 On success, "vf_load" returns a list of virtual filenames for the
120 virtual files. Each virtual filename consists of the actual name of
121 the file containing the virtual file, concatenated with the offset
122 of the virtual file's SOVFM within the actual file. For example,
123 the above call to "vf_load" would return three virtual filenames:
124 /usr/local/details.dat(00000000000000000000)
126 /usr/local/details.dat(00000000000000000048)
127 /usr/local/details.dat(00000000000000000097)
128 When any of these virtual filenames is subsequently used in an
130 "open", the corresponding virtual file is opened.
131 "vf_save @actual_filenames"
133 "vf_save"
134 This subroutine causes the virtual files belonging to the nominated
135 actual file (or files) to be written back to disk. If "vf_save" is
136 called without arguments, then all currently loaded virtual files
137 are saved to their respective actual files at that point.
138 "vf_save" is automatically called in an "END" block at the
140 termination of any program using the module.
141 "vf_marker $virtual_filename"
143 This subroutine returns the SOVFM that preceded the nominated
144 virtual file.
145 The module also modifies the "open", "close", "print", "printf",
147 "read", "getline", "getc", "seek", "tell", and "truncate" built-in
148 functions so that they operate correctly on virtual files.
149 As a special case, it is also possible to use the raw SOVFM as a
151 virtual file name:
152 use Inline::Files::Virtual;
154 vf_load $filename, qr/__[A-Z]+__/;
156 open FILE, "__MARKER__";
158 # and in the file that was vf_load-ed
160 __MARKER__
162 file contents here
163 However, this always opens the very first virtual file with that SOVFM,
165 no matter how often it is called, or how many such markers appear in
166 the file.
167 Handling "implicit" virtual start-of-virtual-file markers
169 Sometimes an SOVFM is "implicit". That is, rather thanb being a
170 separate marker for the start of a virtual file, it is the first part
171 of the actual data of the virtual file. For example, consider the
172 following XML file:
173 <DATA>
175 <DESC>This is data set 1</DESC>
176 <DATUM/>datum 1
177 <DATUM/>datum 2
178 <DATUM/>datum 3
179 </DATA>
180 <DATA>
181 <DESC>This is data set 2</DESC>
182 <DATUM/>datum 4
183 <DATUM/>datum 5
184 <DATUM/>datum 6
185 </DATA>
186 Each of the "<DATA>...</DATA>" blocks could be treated as a separate
188 virtual file by specifying:
189 @datasets = vf_load("data.xml", '<DATA>');
191 But this would cause the individual virtual files to contain invalid
193 XML, such as:
194 <DESC>This is data set 1</DESC>
196 <DATUM/>datum 1
197 <DATUM/>datum 2
198 <DATUM/>datum 3
199 </DATA>
200 One can indicate that the nominated SOVFMs are also part of the
202 virtual files' contents, by specifying the markers as a look-ahead
203 pattern:
204 @datasets = vf_load("data.xml", '(?=<DATA>)');
206 This causes "vf_load" to identify the sequence "<DATA>" as a start-of-
208 virtual-file marker but not consume it, thereby leaving it as the
209 initial sequence of the virtual file's content.
210
212 "Could not vf_load '%s'"
213 The module could not open the specified disk file and read it in as
214 a set of virtual files.
215 "Unable to complete vf_save"
217 The module could not open the specified disk file and write it out
218 as a set of virtual files. A preceding warning may indicate which
219 virtual file caused the problem.
220 "Virtual file not open for input"
222 An attempt was made to "getline", "getc", or "read" a virtual file
223 that was opened for output only. (Warning only)
224 "Virtual file not open for output"
226 An attempt was made to "print" or "printf" a virtual file that was
227 opened for input only. (Warning only)
228
230 Damian Conway (damian@conway.org)
231
233 Brian Ingerson (INGY@cpan.org)
234
236 Copyright (c) 2001. Damian Conway. All rights reserved.
237 This module is free software; you can redistribute it and/or modify it
239 under the same terms as Perl itself.
240 See http://www.perl.com/perl/misc/Artistic.html
242perl v5.16.3 2011-01-31 Inline::Files::Virtual(3)