1Inline::Files::Virtual(U3s)er Contributed Perl DocumentatIinolnine::Files::Virtual(3)
2
3
4

NAME

6       Inline::Files::Virtual - Multiple virtual files in a single file
7

VERSION

9       This document describes version 0.53 of Inline::Files::Virtual,
10       released May 25, 2001.
11

SYNOPSIS

13           use Inline::Files::Virtual;
14
15           # Load actual file, extracting virtual files that start with "^<VF>\n"
16           @virtual_filenames = vf_load($actual_file, "^<VF>\n");
17
18           # Open one of the virtual files for reading
19           open(FILE, $virtual_filenames[0]) or die;
20
21           print while <FILE>;
22
23           close(FILE);
24
25           # Open one of the virtual files for appending
26           open(FILE, ">> $virtual_filenames[1]") or die;
27
28           print FILE "extra text";
29           printf FILE "%6.2", $number;
30
31           close(FILE);
32
33           # Actual file will be updated at this point
34

WARNING

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
40       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

DESCRIPTION

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
52       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
57               --
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
67       or the pattern "/##### \w+ #####/":
68
69               ##### 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
79       Note that the SOVFM is not considered to be part of the file contents.
80
81   Interface
82       The module exports the following methods:
83
84       "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
92                   =info names
93
94                   Damian
95                   Nathan
96                   Mephistopheles
97
98                   =info numbers
99
100                   555-1212
101                   555-6874
102                   555-3452
103
104                   =info comment
105
106                   Mad
107                   Bad
108                   Dangerous to know
109
110           then you could load it as three virtual files with:
111
112                   @virtual_filenames =
113                           vf_load("/usr/local/details.dat", qr/^=info\s+\S+\s*?\n/);
114
115           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
119           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
125                   /usr/local/details.dat(00000000000000000000)
126                   /usr/local/details.dat(00000000000000000048)
127                   /usr/local/details.dat(00000000000000000097)
128
129           When any of these virtual filenames is subsequently used in an
130           "open", the corresponding virtual file is opened.
131
132       "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
139           "vf_save" is automatically called in an "END" block at the
140           termination of any program using the module.
141
142       "vf_marker $virtual_filename"
143           This subroutine returns the SOVFM that preceded the nominated
144           virtual file.
145
146       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
150       As a special case, it is also possible to use the raw SOVFM as a
151       virtual file name:
152
153           use Inline::Files::Virtual;
154
155           vf_load $filename, qr/__[A-Z]+__/;
156
157           open FILE, "__MARKER__";
158
159           # and in the file that was vf_load-ed
160
161           __MARKER__
162           file contents here
163
164       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
168   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
174               <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
187       Each of the "<DATA>...</DATA>" blocks could be treated as a separate
188       virtual file by specifying:
189
190               @datasets = vf_load("data.xml", '<DATA>');
191
192       But this would cause the individual virtual files to contain invalid
193       XML, such as:
194
195                       <DESC>This is data set 1</DESC>
196                       <DATUM/>datum 1
197                       <DATUM/>datum 2
198                       <DATUM/>datum 3
199               </DATA>
200
201       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
205               @datasets = vf_load("data.xml", '(?=<DATA>)');
206
207       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

DIAGNOSTICS

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
216       "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
221       "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
225       "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

AUTHOR

230       Damian Conway  (damian@conway.org)
231

EVIL GENIUS WHO MADE HIM DO IT

233       Brian Ingerson (INGY@cpan.org)
234
236       Copyright (c) 2001. Damian Conway. All rights reserved.
237
238       This module is free software; you can redistribute it and/or modify it
239       under the same terms as Perl itself.
240
241       See http://www.perl.com/perl/misc/Artistic.html
242
243
244
245perl v5.16.3                      2011-01-31         Inline::Files::Virtual(3)
Impressum