Unix/Linux Go Back    


CentOS 7.0 - man page for inline::files::virtual (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


Inline::Files::Virtual(3)      User Contributed Perl Documentation	Inline::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.16.3				    2011-01-31			Inline::Files::Virtual(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 03:04 AM.