Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Inline::Files::VirtualUser Contributed Perl DocumentaInline::Files::Virtual(3)

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

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

SYNOPSIS
	   use Inline::Files::Virtual;

	   # Load actual file, extracting virtual files	that start with	"^<VF>\n"
	   @virtual_filenames =	vf_load($actual_file, "^<VF>\n");

	   # Open one of the virtual files for reading
	   open(FILE, $virtual_filenames[0]) or	die;

	   print while <FILE>;

	   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

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 strongly	advised	to use the Inline::Files module	instead.

       If you chose to use this	module anyway, you thereby agree that the
       authors will b<under no circumstances> 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.

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 "vf_save" subroutine	is explicitly called).

       Each such virtual file is introduced by a start-of-virtual-file marker
       (SOVFM).	This may be any	sequence (or pattern) of characters that marks
       the beginning of	the content of a virtual file. For example, the	string
       "--" might be used:

	       --
	       Contents	of virtual
	       file number 1
	       --
	       Contents	of virtual
	       file number 2
	       --
	       Contents	of virtual
	       file number 3

       or the pattern "/##### \w+ #####/":

	       ##### VF1 #####
	       Contents	of virtual
	       file number 1
	       ##### VF2 #####
	       Contents	of virtual
	       file number 2
	       ##### VF3 #####
	       Contents	of virtual
	       file number 3

       Note that the SOVFM is not considered to	be part	of the file contents.

   Interface
       The module exports the following	methods:

       "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 "qr" regex) that matches each	start-
	   of-virtual-file marker within the file. For example,	if the file
	   "/usr/local/details.dat" contains:

		   =info names

		   Damian
		   Nathan
		   Mephistopheles

		   =info numbers

		   555-1212
		   555-6874
		   555-3452

		   =info comment

		   Mad
		   Bad
		   Dangerous to	know

	   then	you could load it as three virtual files with:

		   @virtual_filenames =
			   vf_load("/usr/local/details.dat", qr/^=info\s+\S+\s*?\n/);

	   Note	that, because the actual file is decomposed into virtual files
	   using a "split", it is vital	that the pattern does not contain any
	   capturing parentheses.

	   On success, "vf_load" returns a list	of virtual filenames 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 SOVFM within the actual file. For example,
	   the above call to "vf_load" would return three virtual filenames:

		   /usr/local/details.dat(00000000000000000000)
		   /usr/local/details.dat(00000000000000000048)
		   /usr/local/details.dat(00000000000000000097)

	   When	any of these virtual filenames is subsequently used in an
	   "open", the corresponding virtual file is opened.

       "vf_save	@actual_filenames"
       "vf_save"
	   This	subroutine causes the virtual files belonging to the nominated
	   actual file (or files) to be	written	back to	disk. If "vf_save" is
	   called without arguments, then all currently	loaded virtual files
	   are saved to	their respective actual	files at that point.

	   "vf_save" is	automatically called in	an "END" block at the
	   termination of any program using the	module.

       "vf_marker $virtual_filename"
	   This	subroutine returns the SOVFM that preceded the nominated
	   virtual file.

       The module also modifies	the "open", "close", "print", "printf",
       "read", "getline", "getc", "seek", "tell", and "truncate" built-in
       functions so that they operate correctly	on virtual files.

       As a special case, it is	also possible to use the raw SOVFM as a
       virtual file name:

	   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

       However,	this always opens the very first virtual file with that	SOVFM,
       no matter how often it is called, or how	many such markers appear in
       the file.

   Handling "implicit" virtual start-of-virtual-file markers
       Sometimes an SOVFM is "implicit". 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 XML file:

	       <DATA>
		       <DESC>This is data set 1</DESC>
		       <DATUM/>datum 1
		       <DATUM/>datum 2
		       <DATUM/>datum 3
	       </DATA>
	       <DATA>
		       <DESC>This is data set 2</DESC>
		       <DATUM/>datum 4
		       <DATUM/>datum 5
		       <DATUM/>datum 6
	       </DATA>

       Each of the "<DATA>...</DATA>" blocks could be treated as a separate
       virtual file by specifying:

	       @datasets = vf_load("data.xml", '<DATA>');

       But this	would cause the	individual virtual files to contain invalid
       XML, such as:

		       <DESC>This is data set 1</DESC>
		       <DATUM/>datum 1
		       <DATUM/>datum 2
		       <DATUM/>datum 3
	       </DATA>

       One can indicate	that the nominated  SOVFMs are also part of the
       virtual files' contents,	by specifying the markers as a look-ahead
       pattern:

	       @datasets = vf_load("data.xml", '(?=<DATA>)');

       This causes "vf_load" to	identify the sequence "<DATA>" as a start-of-
       virtual-file marker but not consume it, thereby leaving it as the
       initial sequence	of the virtual file's content.

DIAGNOSTICS
       "Could not vf_load '%s'"
	   The module could not	open the specified disk	file and read it in as
	   a set of virtual files.

       "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.

       "Virtual	file not open for input"
	   An attempt was made to "getline", "getc", or	"read" a virtual file
	   that	was opened for output only. (Warning only)

       "Virtual	file not open for output"
	   An attempt was made to "print" or "printf" a	virtual	file that was
	   opened for input only. (Warning only)

AUTHOR
       Damian Conway  (damian@conway.org)

EVIL GENIUS WHO	MADE HIM DO IT
       Brian Ingerson (INGY@cpan.org)

COPYRIGHT
       Copyright (c) 2001. Damian Conway. All rights reserved.

       This module is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

       See http://www.perl.com/perl/misc/Artistic.html

perl v5.32.1			  2019-03-31	     Inline::Files::Virtual(3)

NAME | VERSION | SYNOPSIS | WARNING | DESCRIPTION | DIAGNOSTICS | AUTHOR | EVIL GENIUS WHO MADE HIM DO IT | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Inline::Files::Virtual&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help