RubyGems - exiftool_vendored - Versions diffs - 9.45.0 → 9.46.0 - Mend

exiftool_vendored 9.45.0 → 9.46.0

Potentially problematic release.

This version of exiftool_vendored might be problematic. Click here for more details.

Files changed (1073) hide show

data/bin/Image-ExifTool-9.45/html/metafiles.html DELETED Viewed

@@ -1,266 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
-        "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
-<html>
-<head>
-  <title>Metadata Sidecar Files</title>
-<link rel=stylesheet type='text/css' href='style.css' title='Style'>
-<style type="text/css">
-<!--
-blockquote  { margin-top: 1em; margin-bottom: 1em }
-pre         { color: #800; margin-left: 4em }
-pre.code    { color: #000; padding: 0; margin: 0 }
-.lt         { color: #666 }
-.ind        { margin-left: 2.5em }
-p.a         { margin: 1em 2em 0 1em }
-p.b         { margin: 0 2em 1em 2.2em; color: #666 }
-p.c         { margin: 1em 2em 1em 2.2em; color: #666 }
--->
-</style>
-</head>
-<body>
-<div class='index'>
-<a href="#xmp">XMP Sidecar Files</a>
-<br><a href="#xml">ExifTool XML Files</a>
-<br><a href="#exif">EXIF Files</a>
-<br><a href="#mie">MIE Files</a>
-</div>
-<h1 class=up>Metadata Sidecar Files</h1>
-<p>Metadata for images and other file types may be stored in a separate metadata
-file. These are the only files that exiftool can create from scratch.  A common
-example of this is the XMP "sidecar" file (which is discussed in the next
-section in some detail).  Other supported metadata file types are EXIF, MIE,
-ICC and VRD.  As well, ExifTool supports XML-format output, which can also be
-used to generate metadata sidecar files.</p>
-<hr>
-<a name="xmp"></a>
-<h3>XMP Sidecar Files</h3>
-<p>There are a number of different ways to generate an XMP sidecar file with
-exiftool, and the method you choose depends on your circumstances and
-preferences. Below are a number of example commands which write an output XMP
-file from information in a source file of any type.</p>
-<p class=a>1. Copy same-named tags from all information types to preferred locations in XMP:</p>
-<p class=b>(<code><i>SRC</i>.<i>EXT</i></code> is the source file name and
-extension, and <code><i>DST</i></code> is the destination file name)</p>
-<pre>exiftool -tagsfromfile <i>SRC</i>.<i>EXT</i> <i>DST</i>.xmp</pre>
-<p class=a>2. Rewrite source file to destination XMP file:</p>
-<p class=b>(same effect as above, but the command will exit with an error if the output XMP file already exists)</p>
-<pre>exiftool <i>SRC</i>.<i>EXT</i> -o <i>DST</i>.xmp</pre>
-<p class=a>3. Copy XMP, preserving original locations:</p>
-<p class=b>(ie. copies XMP tags only to the same namespaces in the destination file)</p>
-<pre>exiftool -tagsfromfile <i>SRC</i>.<i>EXT</i> -all:all <i>DST</i>.xmp</pre>
-<p class=c>Advanced: Notice that <code>-all:all</code> is used above instead of
-<code>-xmp:all</code> even though only XMP tags will be copied (since the destination
-is an XMP file).  This is because <code>-all:all</code> preserves the family 1 group
-(ie. XMP namespace) while <code>-xmp:all</code> would copy tags to the preferred XMP
-namespace, which may be different for XMP tags that exist in multiple namespaces.
-To get the best of both worlds, <code>"-xmp:all>all:all"</code> may be used to
-avoid the inefficiencies of assigning tags which aren't copied, while still
-preserving the family 1 group.</p>
-<p class=a>4. Rewrite source to XMP file, preserving locations:</p>
-<p class=b>(same effect as above, but the command will fail if the XMP file already exists)</p>
-<pre>exiftool <i>SRC</i>.<i>EXT</i> -o <i>DST</i>.xmp -all:all</pre>
-<p class=a>5. Generate XMP from EXIF and IPTC using standard tag name mappings:</p>
-<p class=b> (the <code>.args</code> files are available in the full ExifTool distribution)</p>
-<pre>exiftool -tagsfromfile <i>SRC</i>.<i>EXT</i> -@ exif2xmp.args -@ iptc2xmp.args <i>DST</i>.xmp</pre>
-<p class=a>6. Copy XMP as a block to an XMP file:</p>
-<p class=b>(writing as a block is the only way to transfer unknown or non-writable XMP tags)</p>
-<pre>exiftool -tagsfromfile <i>SRC</i>.<i>EXT</i> -xmp <i>DST</i>.xmp</pre>
-<p>7. Extract XMP as a block and write to output XMP file: <span class=lt>(same effect as above)</span></p>
-<pre>exiftool -xmp -b <i>SRC</i>.<i>EXT</i> > <i>DST</i>.xmp</pre>
-<p class=a>8. Extract XMP as a block to an output text file with .xmp extension:</p>
-<p class=b>(same effect as above, but the destination file name will be the same
-as the source file, and this command will fail if the XMP file exists while the
-previous command will overwrite an existing file)</p>
-<pre>exiftool -xmp -b -w xmp <i>SRC</i>.<i>EXT</i></pre>
-<p>9. Restore all XMP tags from an XMP sidecar file to XMP in a JPG image:</p>
-<pre>exiftool -tagsfromfile <i>SRC</i>.xmp -all:all <i>DST</i>.jpg</pre>
-<p class=a>10. Restore XMP as a block from an XMP sidecar file to a JPG image:</p>
-<p class=b>(same effect as above except that any non-writable XMP tags would be
-copied by this command, and the 2 kB of padding recommended by the XMP
-specification is not added when copying as a block)</p>
-<pre>exiftool -tagsfromfile <i>SRC</i>.xmp -xmp <i>DST</i>.jpg</pre>
-<h4>Batch Processing</h4>
-<p>When batch-generating sidecar files from many images, the <code>-o</code>
-form of the command is easier to use:</p>
-<pre>exiftool -ext <i>EXT</i> -o %d%f.xmp -r <i>DIR</i></pre>
-<p>where <code><i>DIR</i></code> is the name of the directory containing the
-images.  Multiple <code>-ext</code> options may be used to process different
-file types in a single command.</p>
-<p>However, this technique can not be used to add information to XMP
-sidecar files that already exist.  For this, the <code>-tagsFromFile</code>
-form must be used:</p>
-<pre>exiftool -ext xmp -tagsfromfile %d%f.<i>EXT</i> -r <i>DIR</i></pre>
-<p>But note that this command searches for the XMP files instead of the image
-files, so it will not generate new XMP sidecar files if some images don't
-have them.  For this, the advanced (ie. tricky and confusing to use)
-<code>-srcfile</code> option comes in handy:</p>
-<pre>exiftool -ext <i>EXT</i> -tagsfromfile @ -srcfile %d%f.xmp -r <i>DIR</i></pre>
-<p>The <code>-srcfile</code> option also allows multiple files to be specified,
-in which case the first existing file is processed.  This feature allows a
-sidecar file to be used only if it already exists. For example, this command
-writes to a sidecar XMP file if it exists, or the original file otherwise:</p>
-<pre>exiftool -ext <i>EXT</i> -artist="Phil" -srcfile %d%f.xmp -srcfile @ <i>DIR</i></pre>
-<p>Any of these commands may be used to process sidecar files stored in a
-directory other than that of the original images by specifying a directory name
-instead of "<code>%d</code>" in the filename format string.  For example,</p>
-<pre>exiftool -ext <i>EXT</i> -o <i>DSTDIR</i>/%f.xmp -r <i>SRCDIR</i></pre>
-<p>will output XMP files to <code><i>DSTDIR</i></code> with information
-from images in <code><i>SRCDIR</i></code>.</p>
-<h4>Via the API</h4>
-<p>By specifying different tags in the
-<a href="ExifTool.html#SetNewValuesFromFile">SetNewValuesFromFile</a>
-call, the above examples numbered 1-6 are programmed like this:</p>
-<blockquote><table class='box'><tr><td><pre class='code'>
-$exifTool-><a href="ExifTool.html#SetNewValuesFromFile">SetNewValuesFromFile</a>('SRC.EXT', @tags_to_copy);
-$exifTool-><a href="ExifTool.html#WriteInfo">WriteInfo</a>(undef, 'DST.xmp');
-</pre></td></tr></table></blockquote>
-<p>and examples 7 and 8 use this general technique:</p>
-<blockquote><table class='box'><tr><td><pre class='code'>
-my $info = <a href="ExifTool.html#ImageInfo">ImageInfo</a>('SRC.EXT', 'xmp');
-die "No XMP" unless $$info{XMP};
-open FILE, '&gt;DST.xmp';
-print FILE ${$$info{XMP}};
-close FILE;
-</pre></td></tr></table></blockquote>
-<hr>
-<a name="xml"></a>
-<h3>ExifTool XML Files</h3>
-<p>Closely related to the XMP sidecar file is the XML file written using the
-exiftool <code>-X</code> option.  This file is RDF/XML format like XMP, but uses
-exiftool-specific namespaces to give an exact mapping for all exiftool tag
-names.  This type of file is better suited to general information
-storage/recovery since it facilitates copying of more original metadata than an
-XMP file, but it doesn't have the portability of an XMP file or the ability to
-store native-format data like a MIE file, and ExifTool can not be used to edit
-XML files as it can with other metadata files.  Below are example commands
-demonstrating the use of exiftool XML files.</p>
-<p>Create an exiftool XML sidecar file:</p>
-<pre>exiftool a.jpg -X > a.xml</pre>
-<p>Restore original meta information from exiftool XML file:</p>
-<pre>exiftool -tagsfromfile a.xml -all:all a.jpg</pre>
-<h4>Via the API</h4>
-<p>There is no way to automatically produce a sidecar exiftool XML file via the
-API since this function is accomplished with an output formatting option of the
-exiftool application.  However, the the API may be used to read and copy tags
-from an exiftool XML file just like any other file format.  When reading
-ExifTool XML files, all tags except those in the <code>ExifTool</code>,
-<code>File</code> and <code>Composite</code> groups are extracted with their
-original family 1 groups to facilitate copying of these tags back into their
-original locations in an image.</p>
-<hr>
-<a name="exif"></a>
-<h3>EXIF Files</h3>
-<p>EXIF files store EXIF information in the same format as in the APP1 segment
-of a JPEG image (<i>with the exception that there is no size limit for an
-EXIF file, while EXIF data in a JPEG image is limited to a maximum of 65527
-bytes</i>). The three commands below illustrate techniques for copying the
-entire EXIF block from a source image (<code><i>SRCFILE</i></code>) to an
-output EXIF file (<code>out.exif</code>):</p>
-<pre>exiftool -exif -b <i>SRCFILE</i> > out.exif
-exiftool -tagsfromfile <i>SRCFILE</i> -exif out.exif
-exiftool -o out.exif -exif <i>SRCFILE</i></pre>
-<p>It is the specification of the <a href="TagNames/Extra.html">Extra</a> EXIF
-tag in each of the above commands (the "<code>-exif</code>" argument) that
-causes the EXIF information to be extracted as a block.  JPEG, PNG, JP2, MIE and
-MIFF files all support storage of EXIF data blocks in this format, although
-exiftool does not current write MIFF images.</p>
-<p>Tags may also be copied individually to and from an EXIF file, but remember
-that this will not copy "unsafe" tags unless they are specified explicitly. This
-technique must be used when creating an EXIF sidecar file if the source file
-does not contain EXIF:</p>
-<pre>exiftool -o out.exif -all -unsafe <i>SRCFILE</i>
-</pre>
-<p>or for all files in a directory:</p>
-<pre>exiftool -o %f.exif -all -unsafe <i>DIR</i>
-</pre>
-<hr>
-<a name="mie"></a>
-<h3>MIE Files</h3>
-<p>The <a href="MIE1.1-20070121.pdf">MIE file format</a> allows storage of
-native binary meta information, and is the best option for saving metadata from
-a file in its original format.  Here are two examples that copy all individual
-tags plus the ICC Profile to a MIE sidecar file:</p>
-<pre>exiftool -tagsfromfile a.jpg -all:all -icc_profile a.mie</pre>
-<pre>exiftool -o a.mie -all:all -icc_profile a.jpg</pre>
-<p>And the following command performs the inverse operation, restoring metadata
-in a JPG image from a MIE file:</p>
-<pre>exiftool -tagsfromfile a.mie -all:all -icc_profile a.jpg</pre>
-<p>Information can also be copied in block form to a MIE file.  This allows
-preservation of the original data structure as well as unknown and non-writable
-tags.  The command below copies the full EXIF segment as a block from a JPEG
-image,</p>
-<pre>exiftool -tagsfromfile a.jpg -exif a.mie</pre>
-<p>which is functionally different from copying all writable EXIF tags
-individually with a command more like this</p>
-<pre>exiftool -tagsfromfile a.jpg -exif:all a.mie</pre>
-<p>Block-writable tags are listed in the
-<a href="TagNames/Extra.html">Extra Tags documentation</a>.</p>
-<p>MIE files also have the ability to store information in compressed format with
-the <code>-z</code> option (provided Compress::Zlib is installed on your system),
-which may be useful if disk space is at a premium.</p>
-<hr>
-<i>Created Nov 12, 2008</i><br>
-<i>Last revised Oct 7, 2012</i>
-<p class='lf'><a href="index.html">&lt;-- Back to ExifTool home page</a></p>
-</body>
-</html>

data/bin/Image-ExifTool-9.45/html/under.html DELETED Viewed

@@ -1,124 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
-        "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
-<html>
-<head>
-  <title>Under the Hood</title>
-<link rel=stylesheet type='text/css' href='style.css' title='Style'>
-<style type="text/css">
-<!--
-pre         { margin: 0 }
-ol.index    { margin: 0; padding: 0 0 0 2em }
--->
-</style>
-</head>
-<body>
-<div class='index'>
-<a href="#overview">Overview</a>
-<br><a href="#conversions">Value Conversions</a>
-<br><a href="#philophies">Underlying Philosophies</a>
-</div>
-<h1 class='up'>"Under the Hood" of ExifTool</h1>
-<p>This page is a work in progress, and will be used to explain some details
-of ExifTool's inner workings.</p>
-<a name="overview"></a>
-<h2>Overview of ExifTool</h2>
-<p>Below is a diagram showing the flow of information for the exiftool
-application.  Indicated outside the boxes on the diagram are some command-line
-options associated with the various stages of processing.  All of these options
-are directly associated with options or function calls available via the API
-(Application Programming Interface), with the exception of the output text
-formatting which is handled at the application level.</p>
-<center><img src="overview.png" alt="ExifTool Overview" width="680" height="460"></center>
-<p>The information flow is separated into two distinct modes: 1) Reading or
-extracting information, and 2) Writing or editing.  The application runs in
-<b>read</b> mode by default, but switches to <b>write</b> mode if a new value is
-assigned to any tag (via "<code>-TAG=</code>", "<code>-tagsFromFile</code>",
-"<code>-geotag</code>", "<code>-csv=</code>" or "<code>-json=</code>" on the
-command line).</p>
-<a name="conversions"></a>
-<h2>Value Conversions</h2>
-<p>When ExifTool reads or writes the value of a tag, there are 3 separate
-conversions applied to each value, resulting in 4 different levels for the value
-of each tag.  By default, users interact only with the human-readable
-("<b>PrintConv</b>") value, but other levels are exposed through various exiftool
-options:</p>
-<ol start=3><li>The "<b>PrintConv</b>" value is the final human-readable value
-which has been converted for display.  Often, the "PrintConv" conversion will
-translate numbers into words for better readability.  The <code>-lang</code>
-(Lang) option is used to specify the language for this conversion, and the
-<code>-c</code> and <code>-d</code> (CoordFormat and DateFormat) options specify
-this formatting for GPS coordinates and date/time values.</li></ol>
-<ol start=2><li>The "<b>ValueConv</b>" value is a numerical value, suitable for
-use in calculations.  Typically, this value is converted to standard units (ie.
-degrees, meters, or seconds) to make calculations simpler.  This value is
-returned for all tags when the <code>-n</code> option is used, or for individual
-tags by suffixing the tag name with a <code>#</code> character.</li></ol>
-<ol start=1><li>The "<b>Raw</b>" value is the value after initial formatting is
-applied to the binary data from the file.  Most tags have no separate "ValueConv"
-conversion, so for these tags the "Raw" value is the same as the "ValueConv"
-value.  This value may be seen by using the <code>-v</code> option.</li></ol>
-<ol start=0><li>The "<b>Binary</b>" value is actual binary data stored in the
-file. This data is displayed in hexadecimal form with the <code>-v3</code>
-option, or by using the <code>-htmlDump</code> feature.  Note that this value is
-not related to the <code>-b</code> (<code>-binary</code>) option, which actually
-returns the "ValueConv" value and is used for tags where this value can not be
-presented in a simple text format.</li></ol>
-<p>Below are some examples of these different values for a few tags:</p>
-<blockquote><table class=norm>
-<tr><th>Tag</th><th>3.&nbsp;PrintConv</th><th>2.&nbsp;ValueConv</th><th>1.&nbsp;Raw</th><th>0.&nbsp;Binary</th></tr>
-<tr align='center'><td>Orientation</td><td>Horizontal (normal)</td><td>1</td><td>1</td><td><pre>00 01</pre></td></tr>
-<tr align='center'><td>GPSLatitude</td><td>45 deg 20' 11.00"</td><td>45.3363888888889</td><td>45 20 11<br>(45/1 20/1 11/1)</td>
-  <td><pre>00 00 00 2d 00 00 00 01<br>00 00 00 14 00 00 00 01<br>00 00 00 0b 00 00 00 01</pre></td></tr>
-<tr align='center'><td>ExposureTime</td><td>1/30</td><td>0.03333333333</td><td>0.03333333333<br>(1/30)</td>
-  <td><pre>00 00 00 01 00 00 00 1e</pre></td></tr>
-<tr align='center'><td>ShutterSpeedValue</td><td>1/30</td><td>0.0333333334629176</td><td>4.90689059<br>(19868/4049)</td>
-  <td><pre>00 00 4d 9c 00 00 0f d1</pre></td></tr>
-</table></blockquote>
-<a name="philophies"></a>
-<h2>Underlying Philosophies</h2>
-<p>You have the right to know about the metadata contained in your images.  A main
-goal of the Exiftool project is to make this information freely available, both to
-the general public and as a resource for other developers.</p>
-<p>In the design of exiftool, there have been a number of underlying philosophies
-which have helped to influence the overall development:</p>
-<ol>
-<li>Make <a href="ExifTool.html">Image::ExifTool</a> as independent as possible
-    from other libraries to make it portable and easy to install.  (Portable to
-    a wide range of systems and Perl versions.)</li>
-<li>Keep the interface simple for simple tasks (sometimes at the expense of making
-    it more complicated for complex tasks).</li>
-<li>The <a href="ExifTool.html#Methods">API functions</a> should be isolated from
-    the details of the metadata formats (otherwise the interface turns into a giant
-    hairball, like the metadata).</li>
-<li>Maintain flexibility to allow users the freedom to do what they want.</li>
-<li>Design the code to be efficient for batch processing, even if it increases the
-    initial overhead.</li>
-<li>When writing files, remember 3 things: 1) data integrity, 2) data integrity, and
-    3) data integrity.  If you can't do it right, don't do it at all.</li>
-<li>If possible, recognize file types by their structure, not by their extension.</li>
-<li>Maintain backward compatibility when making changes to the ExifTool API or
-    command line application.</li>
-</ol>
-<hr>
-<i>Last revised May 27, 2013</i>
-<p class='lf'><a href="index.html">&lt;-- Back to ExifTool home page</a></p>
-</body>
-</html>

data/bin/Image-ExifTool-9.45/lib/File/RandomAccess.pm DELETED Viewed

@@ -1,378 +0,0 @@
-#------------------------------------------------------------------------------
-# File:         RandomAccess.pm
-#
-# Description:  Buffer to support random access reading of sequential file
-#
-# Revisions:    02/11/2004 - P. Harvey Created
-#               02/20/2004 - P. Harvey Added flag to disable SeekTest in new()
-#               11/18/2004 - P. Harvey Fixed bug with seek relative to end of file
-#               01/02/2005 - P. Harvey Added DEBUG code
-#               01/09/2006 - P. Harvey Fixed bug in ReadLine() when using
-#                            multi-character EOL sequences
-#               02/20/2006 - P. Harvey Fixed bug where seek past end of file could
-#                            generate "substr outside string" warning
-#               06/10/2006 - P. Harvey Decreased $CHUNK_SIZE from 64k to 8k
-#               11/23/2006 - P. Harvey Limit reads to < 0x80000000 bytes
-#               11/26/2008 - P. Harvey Fixed bug in ReadLine when reading from a
-#                            scalar with a multi-character newline
-#               01/24/2009 - PH Protect against reading too much at once
-#
-# Notes:        Calls the normal file i/o routines unless SeekTest() fails, in
-#               which case the file is buffered in memory to allow random access.
-#               SeekTest() is called automatically when the object is created
-#               unless specified.
-#
-#               May also be used for string i/o (just pass a scalar reference)
-#
-# Legal:        Copyright (c) 2003-2013 Phil Harvey (phil at owl.phy.queensu.ca)
-#               This library is free software; you can redistribute it and/or
-#               modify it under the same terms as Perl itself.
-#------------------------------------------------------------------------------
-package File::RandomAccess;
-use strict;
-require 5.002;
-require Exporter;
-use vars qw($VERSION @ISA @EXPORT_OK);
-$VERSION = '1.10';
-@ISA = qw(Exporter);
-sub Read($$$);
-# constants
-my $CHUNK_SIZE = 8192;  # size of chunks to read from file (must be power of 2)
-my $SLURP_CHUNKS = 16;  # read this many chunks at a time when slurping
-#------------------------------------------------------------------------------
-# Create new RandomAccess object
-# Inputs: 0) reference to RandomAccess object or RandomAccess class name
-#         1) file reference or scalar reference
-#         2) flag set if file is already random access (disables automatic SeekTest)
-sub new($$;$)
-{
-    my ($that, $filePt, $isRandom) = @_;
-    my $class = ref($that) || $that;
-    my $self;
-    if (ref $filePt eq 'SCALAR') {
-        # string i/o
-        $self = {
-            BUFF_PT => $filePt,
-            POS => 0,
-            LEN => length($$filePt),
-            TESTED => -1,
-        };
-        bless $self, $class;
-    } else {
-        # file i/o
-        my $buff = '';
-        $self = {
-            FILE_PT => $filePt, # file pointer
-            BUFF_PT => \$buff,  # reference to file data
-            POS => 0,           # current position in file
-            LEN => 0,           # data length
-            TESTED => 0,        # 0=untested, 1=passed, -1=failed (requires buffering)
-        };
-        bless $self, $class;
-        $self->SeekTest() unless $isRandom;
-    }
-    return $self;
-}
-#------------------------------------------------------------------------------
-# Enable DEBUG code
-# Inputs: 0) reference to RandomAccess object
-sub Debug($)
-{
-    my $self = shift;
-    $self->{DEBUG} = { };
-}
-#------------------------------------------------------------------------------
-# Perform seek test and turn on buffering if necessary
-# Inputs: 0) reference to RandomAccess object
-# Returns: 1 if seek test passed (ie. no buffering required)
-# Notes: Must be done before any other i/o
-sub SeekTest($)
-{
-    my $self = shift;
-    unless ($self->{TESTED}) {
-        my $fp = $self->{FILE_PT};
-        if (seek($fp, 1, 1) and seek($fp, -1, 1)) {
-            $self->{TESTED} = 1;    # test passed
-        } else {
-            $self->{TESTED} = -1;   # test failed (requires buffering)
-        }
-    }
-    return $self->{TESTED} == 1 ? 1 : 0;
-}
-#------------------------------------------------------------------------------
-# Get current position in file
-# Inputs: 0) reference to RandomAccess object
-# Returns: current position in file
-sub Tell($)
-{
-    my $self = shift;
-    my $rtnVal;
-    if ($self->{TESTED} < 0) {
-        $rtnVal = $self->{POS};
-    } else {
-        $rtnVal = tell($self->{FILE_PT});
-    }
-    return $rtnVal;
-}
-#------------------------------------------------------------------------------
-# Seek to position in file
-# Inputs: 0) reference to RandomAccess object
-#         1) position, 2) whence (0 or undef=from start, 1=from cur pos, 2=from end)
-# Returns: 1 on success
-# Notes: When buffered, this doesn't quite behave like seek() since it will return
-#        success even if you seek outside the limits of the file.  However if you
-#        do this, you will get an error on your next Read().
-sub Seek($$;$)
-{
-    my ($self, $num, $whence) = @_;
-    $whence = 0 unless defined $whence;
-    my $rtnVal;
-    if ($self->{TESTED} < 0) {
-        my $newPos;
-        if ($whence == 0) {
-            $newPos = $num;                 # from start of file
-        } elsif ($whence == 1) {
-            $newPos = $num + $self->{POS};  # relative to current position
-        } else {
-            $self->Slurp();                 # read whole file into buffer
-            $newPos = $num + $self->{LEN};  # relative to end of file
-        }
-        if ($newPos >= 0) {
-            $self->{POS} = $newPos;
-            $rtnVal = 1;
-        }
-    } else {
-        $rtnVal = seek($self->{FILE_PT}, $num, $whence);
-    }
-    return $rtnVal;
-}
-#------------------------------------------------------------------------------
-# Read from the file
-# Inputs: 0) reference to RandomAccess object, 1) buffer, 2) bytes to read
-# Returns: Number of bytes read
-sub Read($$$)
-{
-    my $self = shift;
-    my $len = $_[1];
-    my $rtnVal;
-    # protect against reading too much at once
-    # (also from dying with a "Negative length" error)
-    if ($len & 0xf8000000) {
-        return 0 if $len < 0;
-        # read in smaller blocks because Windows attempts to pre-allocate
-        # memory for the full size, which can lead to an out-of-memory error
-        my $maxLen = 0x4000000; # (MUST be less than bitmask in "if" above)
-        my $num = Read($self, $_[0], $maxLen);
-        return $num if $num < $maxLen;
-        for (;;) {
-            $len -= $maxLen;
-            last if $len <= 0;
-            my $l = $len < $maxLen ? $len : $maxLen;
-            my $buff;
-            my $n = Read($self, $buff, $l);
-            last unless $n;
-            $_[0] .= $buff;
-            $num += $n;
-            last if $n < $l;
-        }
-        return $num;
-    }
-    # read through our buffer if necessary
-    if ($self->{TESTED} < 0) {
-        my $buff;
-        my $newPos = $self->{POS} + $len;
-        # number of bytes to read from file
-        my $num = $newPos - $self->{LEN};
-        if ($num > 0 and $self->{FILE_PT}) {
-            # read data from file in multiples of $CHUNK_SIZE
-            $num = (($num - 1) | ($CHUNK_SIZE - 1)) + 1;
-            $num = read($self->{FILE_PT}, $buff, $num);
-            if ($num) {
-                ${$self->{BUFF_PT}} .= $buff;
-                $self->{LEN} += $num;
-            }
-        }
-        # number of bytes left in data buffer
-        $num = $self->{LEN} - $self->{POS};
-        if ($len <= $num) {
-            $rtnVal = $len;
-        } elsif ($num <= 0) {
-            $_[0] = '';
-            return 0;
-        } else {
-            $rtnVal = $num;
-        }
-        # return data from our buffer
-        $_[0] = substr(${$self->{BUFF_PT}}, $self->{POS}, $rtnVal);
-        $self->{POS} += $rtnVal;
-    } else {
-        # read directly from file
-        $_[0] = '' unless defined $_[0];
-        $rtnVal = read($self->{FILE_PT}, $_[0], $len) || 0;
-    }
-    if ($self->{DEBUG}) {
-        my $pos = $self->Tell() - $rtnVal;
-        unless ($self->{DEBUG}->{$pos} and $self->{DEBUG}->{$pos} > $rtnVal) {
-            $self->{DEBUG}->{$pos} = $rtnVal;
-        }
-    }
-    return $rtnVal;
-}
-#------------------------------------------------------------------------------
-# Read a line from file (end of line is $/)
-# Inputs: 0) reference to RandomAccess object, 1) buffer
-# Returns: Number of bytes read
-sub ReadLine($$)
-{
-    my $self = shift;
-    my $rtnVal;
-    my $fp = $self->{FILE_PT};
-    if ($self->{TESTED} < 0) {
-        my ($num, $buff);
-        my $pos = $self->{POS};
-        if ($fp) {
-            # make sure we have some data after the current position
-            while ($self->{LEN} <= $pos) {
-                $num = read($fp, $buff, $CHUNK_SIZE);
-                return 0 unless $num;
-                ${$self->{BUFF_PT}} .= $buff;
-                $self->{LEN} += $num;
-            }
-            # scan and read until we find the EOL (or hit EOF)
-            for (;;) {
-                $pos = index(${$self->{BUFF_PT}}, $/, $pos);
-                if ($pos >= 0) {
-                    $pos += length($/);
-                    last;
-                }
-                $pos = $self->{LEN};    # have scanned to end of buffer
-                $num = read($fp, $buff, $CHUNK_SIZE) or last;
-                ${$self->{BUFF_PT}} .= $buff;
-                $self->{LEN} += $num;
-            }
-        } else {
-            # string i/o
-            $pos = index(${$self->{BUFF_PT}}, $/, $pos);
-            if ($pos < 0) {
-                $pos = $self->{LEN};
-                $self->{POS} = $pos if $self->{POS} > $pos;
-            } else {
-                $pos += length($/);
-            }
-        }
-        # read the line from our buffer
-        $rtnVal = $pos - $self->{POS};
-        $_[0] = substr(${$self->{BUFF_PT}}, $self->{POS}, $rtnVal);
-        $self->{POS} = $pos;
-    } else {
-        $_[0] = <$fp>;
-        if (defined $_[0]) {
-            $rtnVal = length($_[0]);
-        } else {
-            $rtnVal = 0;
-        }
-    }
-    if ($self->{DEBUG}) {
-        my $pos = $self->Tell() - $rtnVal;
-        unless ($self->{DEBUG}->{$pos} and $self->{DEBUG}->{$pos} > $rtnVal) {
-            $self->{DEBUG}->{$pos} = $rtnVal;
-        }
-    }
-    return $rtnVal;
-}
-#------------------------------------------------------------------------------
-# Read whole file into buffer (without changing read pointer)
-# Inputs: 0) reference to RandomAccess object
-sub Slurp($)
-{
-    my $self = shift;
-    my $fp = $self->{FILE_PT} || return;
-    # read whole file into buffer (in large chunks)
-    my ($buff, $num);
-    while (($num = read($fp, $buff, $CHUNK_SIZE * $SLURP_CHUNKS)) != 0) {
-        ${$self->{BUFF_PT}} .= $buff;
-        $self->{LEN} += $num;
-    }
-}
-#------------------------------------------------------------------------------
-# set binary mode
-# Inputs: 0) reference to RandomAccess object
-sub BinMode($)
-{
-    my $self = shift;
-    binmode($self->{FILE_PT}) if $self->{FILE_PT};
-}
-#------------------------------------------------------------------------------
-# close the file and free the buffer
-# Inputs: 0) reference to RandomAccess object
-sub Close($)
-{
-    my $self = shift;
-    if ($self->{DEBUG}) {
-        local $_;
-        if ($self->Seek(0,2)) {
-            $self->{DEBUG}->{$self->Tell()} = 0;    # set EOF marker
-            my $last;
-            my $tot = 0;
-            my $bad = 0;
-            foreach (sort { $a <=> $b } keys %{$self->{DEBUG}}) {
-                my $pos = $_;
-                my $len = $self->{DEBUG}->{$_};
-                if (defined $last and $last < $pos) {
-                    my $bytes = $pos - $last;
-                    $tot += $bytes;
-                    $self->Seek($last);
-                    my $buff;
-                    $self->Read($buff, $bytes);
-                    my $warn = '';
-                    if ($buff =~ /[^\0]/) {
-                        $bad += ($pos - $last);
-                        $warn = ' - NON-ZERO!';
-                    }
-                    printf "0x%.8x - 0x%.8x (%d bytes)$warn\n", $last, $pos, $bytes;
-                }
-                my $cur = $pos + $len;
-                $last = $cur unless defined $last and $last > $cur;
-            }
-            print "$tot bytes missed";
-            $bad and print ", $bad non-zero!";
-            print "\n";
-        } else {
-            warn "File::RandomAccess DEBUG not working (file already closed?)\n";
-        }
-        delete $self->{DEBUG};
-    }
-    # close the file
-    if ($self->{FILE_PT}) {
-        close($self->{FILE_PT});
-        delete $self->{FILE_PT};
-    }
-    # reset the buffer
-    my $emptyBuff = '';
-    $self->{BUFF_PT} = \$emptyBuff;
-    $self->{LEN} = 0;
-    $self->{POS} = 0;
-}
-#------------------------------------------------------------------------------
-1;  # end