.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) .\" .\" 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" '' '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 turned on, 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. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Inline::Files::Virtual 3pm" .TH Inline::Files::Virtual 3pm "2011-01-31" "perl v5.14.2" "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::Virtual \- Multiple virtual files in a single file .SH "VERSION" .IX Header "VERSION" This document describes version 0.53 of Inline::Files::Virtual, released May 25, 2001. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Inline::Files::Virtual; \& \& # Load actual file, extracting virtual files that start with "^\en" \& @virtual_filenames = vf_load($actual_file, "^\en"); \& \& # Open one of the virtual files for reading \& open(FILE, $virtual_filenames[0]) or die; \& \& print while ; \& \& close(FILE); \& \& # Open one of the virtual files for appending \& open(FILE, ">> $virtual_filenames[1]") or die; \& \& print FILE "extra text"; \& printf FILE "%6.2", $number; \& \& close(FILE); \& \& # Actual file will be updated at this point .Ve .SH "WARNING" .IX Header "WARNING" This module is still experimental. Careless use of it will almost certainly cause the source code in files that use it to be overwritten. You are \fIstrongly\fR advised to use the Inline::Files module instead. .PP If you chose to use this module anyway, you thereby agree that the authors will b 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" This module allows you to treat a single disk file as a collection of virtual files, which may then be individually opened for reading or writing. Virtual files which have been modified are written back to their actual disk at the end of the program's execution (or earlier if the \f(CW\*(C`vf_save\*(C'\fR subroutine is explicitly called). .PP Each such virtual file is introduced by a start-of-virtual-file marker (\s-1SOVFM\s0). This may be any sequence (or pattern) of characters that marks the beginning of the content of a virtual file. For example, the string \&\f(CW"\-\-"\fR might be used: .PP .Vb 9 \& \-\- \& Contents of virtual \& file number 1 \& \-\- \& Contents of virtual \& file number 2 \& \-\- \& Contents of virtual \& file number 3 .Ve .PP or the pattern \f(CW\*(C`/##### \ew+ #####/\*(C'\fR: .PP .Vb 9 \& ##### VF1 ##### \& Contents of virtual \& file number 1 \& ##### VF2 ##### \& Contents of virtual \& file number 2 \& ##### VF3 ##### \& Contents of virtual \& file number 3 .Ve .PP Note that the \s-1SOVFM\s0 is not considered to be part of the file contents. .SS "Interface" .IX Subsection "Interface" The module exports the following methods: .ie n .IP """vf_load $file, $SOVFM_pattern""" 4 .el .IP "\f(CWvf_load $file, $SOVFM_pattern\fR" 4 .IX Item "vf_load $file, $SOVFM_pattern" This subroutine is called to load an actual disk file containing one or more virtual files. The first argument specifies the name of the file to be loaded as a string. The second argument specifies a pattern (as either a string or \f(CW\*(C`qr\*(C'\fR regex) that matches each start-of-virtual-file marker within the file. For example, if the file \&\f(CW\*(C`/usr/local/details.dat\*(C'\fR contains: .Sp .Vb 1 \& =info names \& \& Damian \& Nathan \& Mephistopheles \& \& =info numbers \& \& 555\-1212 \& 555\-6874 \& 555\-3452 \& \& =info comment \& \& Mad \& Bad \& Dangerous to know .Ve .Sp then you could load it as three virtual files with: .Sp .Vb 2 \& @virtual_filenames = \& vf_load("/usr/local/details.dat", qr/^=info\es+\eS+\es*?\en/); .Ve .Sp Note that, because the actual file is decomposed into virtual files using a \f(CW\*(C`split\*(C'\fR, it is vital that the pattern does not contain any capturing parentheses. .Sp On success, \f(CW\*(C`vf_load\*(C'\fR returns a list of \fIvirtual filenames\fR for the virtual files. Each virtual filename consists of the actual name of the file containing the virtual file, concatenated with the offset of the virtual file's \s-1SOVFM\s0 within the actual file. For example, the above call to \f(CW\*(C`vf_load\*(C'\fR would return three virtual filenames: .Sp .Vb 3 \& /usr/local/details.dat(00000000000000000000) \& /usr/local/details.dat(00000000000000000048) \& /usr/local/details.dat(00000000000000000097) .Ve .Sp When any of these virtual filenames is subsequently used in an \f(CW\*(C`open\*(C'\fR, the corresponding virtual file is opened. .ie n .IP """vf_save @actual_filenames""" 4 .el .IP "\f(CWvf_save @actual_filenames\fR" 4 .IX Item "vf_save @actual_filenames" .PD 0 .ie n .IP """vf_save""" 4 .el .IP "\f(CWvf_save\fR" 4 .IX Item "vf_save" .PD This subroutine causes the virtual files belonging to the nominated actual file (or files) to be written back to disk. If \f(CW\*(C`vf_save\*(C'\fR is called without arguments, then \fIall\fR currently loaded virtual files are saved to their respective actual files at that point. .Sp \&\f(CW\*(C`vf_save\*(C'\fR is automatically called in an \f(CW\*(C`END\*(C'\fR block at the termination of any program using the module. .ie n .IP """vf_marker $virtual_filename""" 4 .el .IP "\f(CWvf_marker $virtual_filename\fR" 4 .IX Item "vf_marker $virtual_filename" This subroutine returns the \s-1SOVFM\s0 that preceded the nominated virtual file. .PP The module also modifies the \f(CW\*(C`open\*(C'\fR, \f(CW\*(C`close\*(C'\fR, \f(CW\*(C`print\*(C'\fR, \f(CW\*(C`printf\*(C'\fR, \&\f(CW\*(C`read\*(C'\fR, \f(CW\*(C`getline\*(C'\fR, \f(CW\*(C`getc\*(C'\fR, \f(CW\*(C`seek\*(C'\fR, \f(CW\*(C`tell\*(C'\fR, and \f(CW\*(C`truncate\*(C'\fR built-in functions so that they operate correctly on virtual files. .PP As a special case, it is also possible to use the raw \s-1SOVFM\s0 as a virtual file name: .PP .Vb 1 \& use Inline::Files::Virtual; \& \& vf_load $filename, qr/_\|_[A\-Z]+_\|_/; \& \& open FILE, "_\|_MARKER_\|_"; \& \& # and in the file that was vf_load\-ed \& \& _\|_MARKER_\|_ \& file contents here .Ve .PP However, this always opens the very first virtual file with that \s-1SOVFM\s0, no matter how often it is called, or how many such markers appear in the file. .ie n .SS "Handling ""implicit"" virtual start-of-virtual-file markers" .el .SS "Handling ``implicit'' virtual start-of-virtual-file markers" .IX Subsection "Handling implicit virtual start-of-virtual-file markers" Sometimes an \s-1SOVFM\s0 is \*(L"implicit\*(R". That is, rather thanb being a separate marker for the start of a virtual file, it is the first part of the actual data of the virtual file. For example, consider the following \s-1XML\s0 file: .PP .Vb 12 \& \& This is data set 1 \& datum 1 \& datum 2 \& datum 3 \& \& \& This is data set 2 \& datum 4 \& datum 5 \& datum 6 \& .Ve .PP Each of the \f(CW\*(C`...\*(C'\fR blocks could be treated as a separate virtual file by specifying: .PP .Vb 1 \& @datasets = vf_load("data.xml", \*(Aq\*(Aq); .Ve .PP But this would cause the individual virtual files to contain invalid \&\s-1XML\s0, such as: .PP .Vb 5 \& This is data set 1 \& datum 1 \& datum 2 \& datum 3 \& .Ve .PP One can indicate that the nominated SOVFMs are also part of the virtual files' contents, by specifying the markers as a look-ahead pattern: .PP .Vb 1 \& @datasets = vf_load("data.xml", \*(Aq(?=)\*(Aq); .Ve .PP This causes \f(CW\*(C`vf_load\*(C'\fR to identify the sequence \f(CW\*(C`\*(C'\fR as a start-of-virtual-file marker but not consume it, thereby leaving it as the initial sequence of the virtual file's content. .SH "DIAGNOSTICS" .IX Header "DIAGNOSTICS" .ie n .IP """Could not vf_load \*(Aq%s\*(Aq""" 4 .el .IP "\f(CWCould not vf_load \*(Aq%s\*(Aq\fR" 4 .IX Item "Could not vf_load %s" The module could not open the specified disk file and read it in as a set of virtual files. .ie n .IP """Unable to complete vf_save""" 4 .el .IP "\f(CWUnable to complete vf_save\fR" 4 .IX Item "Unable to complete vf_save" The module could not open the specified disk file and write it out as a set of virtual files. A preceding warning may indicate which virtual file caused the problem. .ie n .IP """Virtual file not open for input""" 4 .el .IP "\f(CWVirtual file not open for input\fR" 4 .IX Item "Virtual file not open for input" An attempt was made to \f(CW\*(C`getline\*(C'\fR, \f(CW\*(C`getc\*(C'\fR, or \f(CW\*(C`read\*(C'\fR a virtual file that was opened for output only. (Warning only) .ie n .IP """Virtual file not open for output""" 4 .el .IP "\f(CWVirtual file not open for output\fR" 4 .IX Item "Virtual file not open for output" An attempt was made to \f(CW\*(C`print\*(C'\fR or \f(CW\*(C`printf\*(C'\fR a virtual file that was opened for input only. (Warning only) .SH "AUTHOR" .IX Header "AUTHOR" Damian Conway (damian@conway.org) .SH "EVIL GENIUS WHO MADE HIM DO IT" .IX Header "EVIL GENIUS WHO MADE HIM DO IT" Brian Ingerson (INGY@cpan.org) .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (c) 2001. 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