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 → Image-ExifTool-9.46}/html/install.html RENAMED Viewed

File without changes

data/bin/Image-ExifTool-9.46/html/metafiles.html ADDED Viewed

@@ -0,0 +1,274 @@
+<!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 class=c>Note that this will not deal with extended XMP segments in JPEG
+images if they exist.</p>
+<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=c>As with the previous command, this command will not copy extended XMP
+segments in JPEG images, but in this case the <code>-a</code> option may be
+added to also extract extended XMP blocks.  However, the result would be a
+non-standard XMP file that ExifTool could read but other utilities may not.</p>
+<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 class=c>The advantage of this command is that it may be applied to multiple
+source files or entire directories.</p>
+<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 Dec 23, 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 → Image-ExifTool-9.46}/html/overview.png RENAMED Viewed

File without changes

data/bin/{Image-ExifTool-9.45 → Image-ExifTool-9.46}/html/standards.html RENAMED Viewed

File without changes

data/bin/{Image-ExifTool-9.45 → Image-ExifTool-9.46}/html/struct.html RENAMED Viewed

File without changes

data/bin/{Image-ExifTool-9.45 → Image-ExifTool-9.46}/html/style.css RENAMED Viewed

File without changes

data/bin/Image-ExifTool-9.46/html/under.html ADDED Viewed

@@ -0,0 +1,126 @@
+<!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.  The Writable column in the
+<a href="TagNames/index.html">Tag Name documentation</a>
+gives the format of this binary data for writable tags.</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 Dec 24, 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 → Image-ExifTool-9.46}/html/verbose.html RENAMED Viewed

File without changes

data/bin/{Image-ExifTool-9.45 → Image-ExifTool-9.46}/html/writing.html RENAMED Viewed

File without changes

data/bin/Image-ExifTool-9.46/lib/File/RandomAccess.pm ADDED Viewed

@@ -0,0 +1,378 @@
+#------------------------------------------------------------------------------
+# 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-2014 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