file_pipeline 0.0.6 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 51b495ebce21752d34f27eef33a350539f8918076774063323e603cde82a7726
-  data.tar.gz: f6bd55e7129fe2308193af2e12630a867cca866ae6ce71dd177a9deea3e2aa00
+  metadata.gz: 2669b6e193cbdf383b4db7bf1fe9e16a4519cefb152b394e34310ea9690d4ed6
+  data.tar.gz: 5c07a106071954420545dfec51b1110f71027614384e77d553f4132322848faa
 SHA512:
-  metadata.gz: 47077cb546d41be57b9c662718710c815dda1c3d77b1834946800d2ddf5472abfde8ecf9e107f58b69f6eb573ea536464a316c5d60a5ae97e94a4d5deb6fbc01
-  data.tar.gz: 25b006ee9e71a989eea5f22eece86918feabe4f7579cf96425110cf64efe5f0e00ab40335b6002298d552f979894bbcd210869ce8e724c35628306d8da701e1e
+  metadata.gz: b193249acfb972b2a0bc167728a2147d9e7c39e4469a4f3808ed9ff23b3db0cdbfa06000e3477a83058918a31174bad854821a95287abfb964965e6db02421d4
+  data.tar.gz: 265d513deaf12846e01c767c71a63c481bb0f21a8bc81d7b00e7ba2ea2291afb0c3d99cd9c3830fd37715772a8c807e3455fdfb3c4f14d558e5df5cc9ba52183

data/README.rdoc

@@ -54,7 +54,7 @@ instructions on how to create custom operations).
 ==== Basic set up with default operations
 
 To define an operation, pass the class name of the operation in underscore
-notation and without the containing module name, and any options to
+notation without the containing module name, and any options to
 {#define_operation}[rdoc-ref:FilePipeline::Pipeline#define_operation].
 
 The example below adds an instance of 
@@ -87,8 +87,9 @@ call <tt>#define_operation</tt> with the desired operations and options.
 
 When file operations are to be used that are not included in the gem, place
 the source files for the class definitions in one or more directories and
-initialize the Pipeline object with the directory paths. The directories will
-be added to the {source directories}[rdoc-ref:FilePipeline.source_directories].
+initialize the Pipeline object with the paths to those directories. The
+directories will be added to the
+{source directories}[rdoc-ref:FilePipeline.source_directories].
 
 Directories are added to the source directories in reverse order, so that
 directories added later will have precedence when searching source files. The
@@ -103,7 +104,7 @@ finally in the included default operations.
 
 The basename for source files _must_ be the class name in underscore notation
 without the containing module name. If, for example, the operation is
-<tt>FileOperations::MyOperation</tt>, the source file basename should be
+<tt>FileOperations::MyOperation</tt>, the source file basename has to be
 <tt>'my_operation.rb'</tt>
 
   my_pipeline = FilePipeline::Pipeline.new('~/custom_operations',
@@ -146,7 +147,7 @@ VersionedFile provides access to a files metadata via the
 {#metadata}[rdoc-ref:FilePipeline::VersionedFile#metadata] method of the 
 versioned file instance.
 
-Both the metadata for the original file and the current (latest) version can
+Metadata for the original file, the current (latest) or an arbitrary version can
 be accessed:
 
   image = FilePipeline::VersionedFile.new('~/image.jpg')
@@ -167,12 +168,13 @@ versions available, pass the <tt>:for_version</tt> option with the symbol
 
 Some file operations can comprise metadata; many image processing libraries
 will not preserve all _Exif_ tags and their values when converting images to
-a different format, but only write a small subset of tags to the file they
-create. In these cases, the 
+a different format, but only write a subset of tags to the file they create.
+In these cases, the 
 {ExifRestoration}[rdoc-ref:FilePipeline::FileOperations::ExifRestoration]
-operation can be used to try to restore the tags that have been discarded, but
-it can not write all tags. It will store all tags and their values that it could 
-not write back to the file and return them as captured data.
+operation can be used to try to restore the tags that have been discarded. The
+operation uses Exiftool to write tags, and Exiftool will not write all tags.
+It will store any tags and their values that it could not write back to the file
+and return them as captured data.
 
 Likewise, if the 
 {ExifRedaction}[rdoc-ref:FilePipeline::FileOperations::ExifRedaction] is applied
@@ -246,8 +248,7 @@ The <tt>#initialize</tt> method _must_ take an +options+ argument (a hash
 with a default value, or a <em>double splat</em>) and _must_ be exposed
 through an <tt>#options</tt> getter method.
 
-The options passed can be any for the file operation to properly configure
-a specific instance of a method.
+The options passed can be any to properly configure an instance of the class.
 
 This requirement is imposed by the 
 {#define_operation}[rdoc-ref:FilePipeline::Pipeline#define_operation] instance
@@ -294,20 +295,26 @@ The three arguments required for implementations of <tt>#run</tt> are:
   succession of modified versions has been created.
 
 The <em>original file</em> will only be used by file operations that require
-it for reference, e.g. to restore file metadata that was compromised by
-other file operations.
+it for reference, e.g. to restore or recover file metadata that was compromised
+by other file operations.
 
 ===== Return value
 
-The method _must_ return the path to the file that was created by the
-operation (perferrably in the _directory_). It _may_ also return a 
-{Results}[rdoc-ref:FilePipeline::FileOperations::Results] object, containing the
-operation itself, a _success_ flag (+true+ or +false+), and any logs or data
-returned by the operation.
+If the operation modifies the file (i.e. creates a new version), the +run+
+method _must_ return the path to the file that was created (perferrably in the
+_directory_). If it does not modify and no results are returned, it _must_
+return +nil+.
+
+The method _may_ return a 
+{Results}[rdoc-ref:FilePipeline::FileOperations::Results] object along with the
+path or +nil+. The results object should contain the operation itself, a
+_success_ flag (+true+ or +false+), and any logs or data returned by the
+operation.
 
 If results are returned with the path to the created file, both values must
 be wrapped in an array, with the path as the first element, the results as
-the second.
+the second. If the operation does not modify and therefore not return a path,
+the first element of the array must be +nil+.
 
 ===== Example
 
@@ -365,15 +372,21 @@ logic to perform the actual file operation, but will call an
 {#operation method}[rdoc-label:label-The+operation+method] that _must_ be
 defined in the subclass unless the subclass overrides the <tt>#run</tt> method.
 
-The <tt>#run</tt> method will generate the new path that is passed to the
-<tt>#operation</tt> method, and to which the latter will write the new
-version of the file. The new file path will need an appropriate file type
-extension. The default behavior is to assume that the extension will be the
-same as for the file that was passed in as the basis from which the new
-version will be created. If the operation will result in a different file
-type, the subclass _should_ define a <tt>#target_extension</tt> method that
-returns the appropriate file extension (see
-{Target file extensions}[rdoc-label:label-Target+file+extensions]).
+If the operation is modifying (creates a new version), the <tt>#run</tt> method
+will generate the new path that is passed to the <tt>#operation</tt> method,
+and to which the latter will write the new version of the file. The new file
+path will need an appropriate file type extension. The default behavior is to
+assume that the extension will be the same as for the file that was passed in as
+the basis from which the new version will be created. If the operation will
+result in a different file type, the subclass _should_ define a
+<tt>#target_extension</tt> method that returns the appropriate file extension
+(see {Target file extensions}[rdoc-label:label-Target+file+extensions]).
+
+Subclasses of FileOperation are by default modifying. If the operation is not
+modifying (does not create a new version of the file), the subclass _must_
+override the <tt>#modiies?</tt> method or override the <tt>#run</tt> method to
+ensure it does not return a file path (see
+{Non-modifying operations}[rdoc-label:label-Non-modifying+operations]).
 
 ==== Initializer
 
@@ -488,6 +501,16 @@ return the appropriate
     return
   end
 
+==== Non-modifying operations
+
+If the operation will not create a new version, the class _must_ redefine the
+<tt>#modifies?</tt> method to return +false+:
+
+  # non-modiyfing operation
+  def modifies?
+    false
+  end
+
 ==== Target file extensions
 
 If the file that the operation creates is of a different type than the file

data/lib/file_pipeline.rb

@@ -4,6 +4,7 @@ require 'securerandom'
 
 require_relative 'file_pipeline/errors'
 require_relative 'file_pipeline/file_operations'
+require_relative 'file_pipeline/versions'
 require_relative 'file_pipeline/versioned_file'
 require_relative 'file_pipeline/pipeline'
 
@@ -22,7 +23,7 @@ module FilePipeline
     return source_directories if source_directories.include? directory_path
 
     no_dir = !File.directory?(directory_path)
-    raise Errors::SourceDirectoryError, dir: directory if no_dir
+    raise Errors::SourceDirectoryError.new dir: directory if no_dir
 
     @src_directories.prepend directory_path
   end
@@ -32,7 +33,7 @@ module FilePipeline
   def self.load(file_operation)
     const = file_operation.split('_').map(&:capitalize).join
     FilePipeline.load_file(file_operation) unless const_defined? const
-    const_get 'FileOperations::' + const
+    const_get "FileOperations::#{const}"
   rescue NameError
     # TODO: implement autogenerating module names from file_operation src path
     const_get const
@@ -44,9 +45,10 @@ module FilePipeline
     src_file += '.rb' unless src_file.end_with? '.rb'
     src_path = FilePipeline.source_path src_file
     if src_path.nil?
-      raise Errors::SourceFileError,
-            file: src_file,
-            directories: FilePipeline.source_directories
+      raise Errors::SourceFileError.new(
+        file: src_file,
+        directories: FilePipeline.source_directories
+      )
     end
     require src_path
   end

data/lib/file_pipeline/errors.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'errors/failed_modification_error'
+require_relative 'errors/misplaced_version_file_error'
 require_relative 'errors/missing_version_file_error'
 require_relative 'errors/source_directory_error'
 require_relative 'errors/source_file_error'

data/lib/file_pipeline/errors/failed_modification_error.rb

@@ -8,32 +8,64 @@ module FilePipeline
       # The file opration that caused the error.
       attr_reader :info
 
-      # FIXME: should contain original file name file name!
+      # Returns a new instance.
+      #
+      # ===== Arguments
+      #
+      # * +msg+ - error message for the exception. If none provided, the
+      #   instance will be initialized with the #default_message.
+      #
+      # ===== Options
+      #
+      # * <tt>info</tt> - a FileOperations::Results object or an object.
+      # * <tt>file</tt> - path to the file thas was being processed.
       def initialize(msg = nil, info: nil, file: nil)
         @file = file
         @info = info
-
-        if info.respond_to?(:operation) && info.respond_to?(:log)
-          msg ||= "#{@info.operation&.name} with options"\
-                  " #{@info.operation&.options} failed on #{file}."
-          if original_error
-            msg += "\nException raised by the operation:"\
-                   " #{original_error.inspect}. Backtrace:\n"
-            msg += original_backtrace if original_backtrace
-          end
-        else
-          msg ||= 'Operation failed' unless info
-        end
+        msg ||= default_message
         super msg
       end
 
+      # Returns the backtrace of the error that caused the exception.
       def original_backtrace
         original_error&.backtrace&.join("\n")
       end
 
+      # Returns the error that caused the exception.
       def original_error
         @info.log.find { |item| item.is_a? Exception }
       end
+
+      private
+
+      # Appends the backtrace of the error that caused the exception to the
+      # #default_message.
+      def append_backtrace(str)
+        return "#{str}\n" unless original_backtrace
+
+        "#{str} Backtrace:\n#{original_backtrace}"
+      end
+
+      # Appends the message of the error that caused the exception to the
+      # #default_message.
+      def append_error(str)
+        return str unless original_error
+
+        str += "\nException raised by the operation:"\
+          " #{original_error.inspect}."
+        append_backtrace str
+      end
+
+      # Returns a String with the #message for +self+.
+      def default_message
+        if info.respond_to?(:operation) && info.respond_to?(:log)
+          msg = "#{info.operation&.name} with options"\
+            " #{info.operation&.options} failed on #{@file}."
+          append_error msg
+        else
+          'Operation failed'
+        end
+      end
     end
   end
 end

data/lib/file_pipeline/errors/misplaced_version_file_error.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module FilePipeline
+  module Errors
+    # Error class for exceptions that are raised when a new version is added,
+    # but the file is not in the VersionedFile's working directory.
+    class MisplacedVersionFileError < StandardError
+      # Path for of the misplaced file for the version.
+      attr_reader :file
+
+      # Path for the directory where the file should have been (the
+      # VersionedFile's working directory).
+      attr_reader :directory
+
+      def initialize(msg = nil, file: nil, directory: nil)
+        @file = file
+        @directory = directory
+        msg ||= default_message
+        super msg
+      end
+
+      private
+
+      def default_message
+        "File #{File.basename @file} was expected in #{@directory},"\
+        " but was in #{File.dirname @file}."
+      end
+    end
+  end
+end

data/lib/file_pipeline/file_operations/default_operations/exif_recovery.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module FilePipeline
+  module FileOperations
+    # A non-modifying FileOperation that compares a file's _Exif_ Metadata with
+    # that of a reference file and returns tags missing in the working file as
+    # captured data.
+    #
+    # Used to recover _Exif_ tags that were not preserved during e.g. a file
+    # conversion.
+    class ExifRecovery < FileOperation
+      include ExifManipulable
+
+      # :args: options
+      #
+      # Returns a new instance.
+      #
+      # ===== Options
+      #
+      # * <tt>skip_tags</tt> - _Exif_ tags to be ignored during comparison.
+      #
+      # The ExifManipulable mixin defines a set of _Exif_
+      # {tags}[rdoc-ref:FilePipeline::FileOperations::ExifManipulable.file_tags]
+      # that will always be ignored.
+      def initialize(**opts)
+        defaults = { skip_tags: [] }
+        super(opts, defaults)
+        @options[:skip_tags] += ExifManipulable.file_tags
+      end
+
+      # Returns the DROPPED_EXIF_DATA tag defined in CapturedDataTags.
+      #
+      # Instances of ExifRecovery will capture any _Exif_ tags and their values
+      # that are present in the reference file but missing in the working file.
+      def captured_data_tag
+        CapturedDataTags::DROPPED_EXIF_DATA
+      end
+
+      # Instances of ExifRecovery do not modify the working file.
+      def modifies?
+        false
+      end
+
+      # Compares the _Exif_ metadata of <tt>src_file</tt> with that of
+      # +original+ and returns all tags that are present in +original+ but
+      # missing in <tt>src_file</tt>.
+      def operation(src_file, _, original)
+        original_exif, src_file_exif = read_exif original, src_file
+        missing_exif_fields(src_file_exif, original_exif)
+      end
+    end
+  end
+end

data/lib/file_pipeline/file_operations/default_operations/exif_restoration.rb

@@ -2,9 +2,12 @@
 
 module FilePipeline
   module FileOperations
-    # A FileOperation that compares Exif Metadata in two files and copies tags
-    # missing in one from the other. Used to restore Exif tags that were not
-    # preserved during e.g. a file conversion.
+    # A modifying FileOperation that compares a file's Exif Metadata with that
+    # of a reference file and attempts to copy tags missing in the working file
+    # from the reference file.
+    #
+    # Used to restore Exif tags that were not preserved during e.g. a file
+    # conversion.
     #
     # *Caveat:* if this operation is applied to a file together with
     # ExifRedaction, it should be applied _before_ the latter, to avoid
@@ -20,10 +23,9 @@ module FilePipeline
       #
       # * <tt>skip_tags</tt> - _Exif_ tags to be ignored during restoration.
       #
-      # The ExifManipulable mixin defines a set of _Exif_ tags that will always
-      # be ignored. These are tags relating to the file properties (e.g.
-      # filesize, MIME-type) that will have been altered by any prior operation,
-      # such as file format conversions.
+      # The ExifManipulable mixin defines a set of _Exif_
+      # {tags}[rdoc-ref:FilePipeline::FileOperations::ExifManipulable.file_tags]
+      # that will always be ignored.
       def initialize(**opts)
         defaults = { skip_tags: [] }
         super(opts, defaults)
@@ -38,8 +40,6 @@ module FilePipeline
         CapturedDataTags::DROPPED_EXIF_DATA
       end
 
-      # :args: src_file, out_file
-      #
       # Writes a new version of <tt>src_file</tt> to <tt>out_file</tt> with all
       # writable _Exif_ tags from +original+ restored.
       #

data/lib/file_pipeline/file_operations/default_operations/ptiff_conversion.rb

@@ -34,7 +34,7 @@ module FilePipeline
       def operation(*args)
         src_file, out_file = args
         image = Vips::Image.new_from_file src_file
-        image.tiffsave(out_file, options)
+        image.tiffsave(out_file, **options)
         # Return lof if any
       end
 

data/lib/file_pipeline/file_operations/exif_manipulable.rb

@@ -9,6 +9,10 @@ module FilePipeline
       # Returns an Array of tags to be ignored during comparison. These can
       # be merged with an ExifManipulable including FileOperation's options
       # to skip tags (e.g. the <tt>skip_tags</tt> option in ExifRestoration).
+      #
+      # The included tags relate to the file properties (e.g. filesize,
+      # MIME-type) that will have been altered by any prior operation, such as
+      # file format conversions.
       def self.file_tags
         %w[FileSize FileModifyDate FileAccessDate FileInodeChangeDate
            FilePermissions FileType FileTypeExtension MIMEType]
@@ -20,7 +24,7 @@ module FilePipeline
       end
 
       def self.strip_path(str) # :nodoc:
-        str.sub(%r{ - \/?(\/|[-:.]+|\w+)+\.\w+$}, '')
+        str.sub(%r{ - /?(/|[-:.]+|\w+)+\.\w+$}, '')
       end
 
       # Redacts (deletes) all <tt>tags_to_delete</tt> in <tt>out_file</tt>.

data/lib/file_pipeline/file_operations/file_operation.rb

@@ -18,6 +18,9 @@ module FilePipeline
     # that is passed to #run or #operation as <tt>src_file</tt>, the subclass
     # must have a #target_extension method that returns the appropriate
     # extension.
+    #
+    # If the operation is non-modifying, the subclass must redefine the
+    # #modifies? methods to return +false+.
     class FileOperation
       # A Hash; any options used when performing #operation.
       attr_reader :options
@@ -62,6 +65,12 @@ module FilePipeline
         results false, log_data
       end
 
+      # Returns +true+ if the FIleOperation will create a new version.
+      # _Default:_ +true+.
+      def modifies?
+        true
+      end
+
       # Returns the class name (string) of +self+ _without_ the names of the
       # modules that the class is nested in.
       def name
@@ -133,11 +142,11 @@ module FilePipeline
       # e.g. when exif metadata tags missing in the <tt>src_file</tt> are to
       # be copied over from another file.
       def run(src_file, directory, original = nil)
-        out_file = target directory, extension(src_file)
+        out_file = target directory, extension(src_file) if modifies?
         log_data = operation src_file, out_file, original
         [out_file, success(log_data)]
       rescue StandardError => e
-        FileUtils.rm out_file if File.exist? out_file
+        FileUtils.rm out_file if out_file && File.exist?(out_file)
         [out_file, failure(e)]
       end
 

data/lib/file_pipeline/pipeline.rb

@@ -41,10 +41,7 @@ module FilePipeline
     # Adds a file operation object #file_operations. The object must implement
     # a _run_ method (see FileOperations::FileOperation#run for details).
     def <<(file_operation_instance)
-      unless file_operation_instance.respond_to? :run
-        raise TypeError, 'File operations must implement a #run method'
-      end
-
+      validate file_operation_instance
       @file_operations << file_operation_instance
     end
 
@@ -88,7 +85,7 @@ module FilePipeline
     #
     def define_operation(file_operation, options = {})
       operation = FilePipeline.load file_operation
-      self << operation.new(options)
+      self << operation.new(**options)
       self
     end
 
@@ -106,5 +103,15 @@ module FilePipeline
         operation.run version, directory, original
       end
     end
+
+    private
+
+    # Raises TypeError if <tt>file_operation_instance</tt> does not implement a
+    # #run method.
+    def validate(file_operation_instance)
+      return file_operation_instance if file_operation_instance.respond_to? :run
+
+      raise TypeError, 'File operations must implement a #run method'
+    end
   end
 end

data/lib/file_pipeline/versioned_file.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'versions/validator'
 module FilePipeline
   # VersionedFile creates a directory where it stores any versions of _file_.
   class VersionedFile
@@ -19,6 +20,35 @@ module FilePipeline
     # by #finalize is not replacing the original.
     attr_reader :target_suffix
 
+    extend Forwardable
+
+    # Returns a two-dimesnional array, where each nested array has two items;
+    # the file operation object and data captured by the operartion (if any).
+    #
+    # <tt>[[description_object, data_or_nil], ...]</tt>
+    delegate captured_data: :history
+
+    # Returns any data captured by <tt>operation_name</tt>.
+    #
+    # If multiple instances of one operation class have modified the file,
+    # pass any +options+ the specific instance of the operation was initialized
+    # with as the optional second argument.
+    delegate captured_data_for: :history
+
+    # Returns an array with all data captured by operations with +tag+.
+    #
+    # Tags are defined in FileOperations::CapturedDataTags
+    delegate captured_data_with: :history
+
+    # Returns an array of triplets (arryas with three items each): the name of
+    # the file operation class (a string), options (a hash), and the actual log
+    # (an array).
+    delegate log: :history
+
+    # Returns an array with paths to the version files of +self+ (excluding
+    # #original).
+    delegate versions: :history
+
     # Returns a new instance with +file+ as the #original.
     #
     # ===== Arguments
@@ -41,23 +71,10 @@ module FilePipeline
 
       @original = file
       @basename = File.basename(file, '.*')
-      @history = {}
+      @history = Versions::History.new
       @directory = nil
       @target_suffix = target_suffix
-    end
-
-    # Copies the file with path _src_ to <em>/dir/filename</em>.
-    def self.copy(src, dir, filename)
-      dest = FilePipeline.path(dir, filename)
-      FileUtils.cp src, dest
-      dest
-    end
-
-    # Moves the file with path _src_ to <em>/dir/filename</em>.
-    def self.move(src, dir, filename)
-      dest = FilePipeline.path(dir, filename)
-      FileUtils.mv src, dest
-      dest
+      history[original] = nil
     end
 
     # Adds a new version to #history and returns _self_.
@@ -65,14 +82,10 @@ module FilePipeline
     # <tt>version_info</tt> must be a path to an existing file or an array with
     # the path and optionally a FileOperations::Results instance:
     # <tt>['path/to/file', results_object]</tt>.
-    # Will move the file to #directory if it is in another directory.
+    # Will raise MisplacedVersionFileError if it is in another directory.
     def <<(version_info)
-      file, info = version_info
-      if info&.failure
-        raise Errors::FailedModificationError, info: info, file: original
-      end
-
-      version = validate(file)
+      version, info = Versions::Validator[version_info, self]
+      version ||= @current
       @history[version] = info
       self
     rescue StandardError => e
@@ -80,37 +93,6 @@ module FilePipeline
       raise e
     end
 
-    # Returns a two-dimesnional array, where each nested array has two items;
-    # the file operation object and data captured by the operartion (if any).
-    #
-    # <tt>[[description_object, data_or_nil], ...]</tt>
-    def captured_data
-      filter_history :data
-    end
-
-    # Returns any data captured by <tt>operation_name</tt>.
-    #
-    # If multiple instances of one operation class have modified the file,
-    # pass any +options+ the specific instance of the operation was initialized
-    # with as the optional second argument.
-    def captured_data_for(operation_name, **options)
-      raw_data = captured_data.filter do |operation, _|
-        operation.name == operation_name &&
-          options.all? { |k, v| operation.options[k] == v }
-      end
-      raw_data.map(&:last)
-    end
-
-    # Returns an array with all data captured by operations with +tag+ has.
-    #
-    # Tags are defined in FileOperations::CapturedDataTags
-    def captured_data_with(tag)
-      return unless changed?
-
-      captured_data.select { |operation, _| operation.captured_data_tag == tag }
-                   .map(&:last)
-    end
-
     # Returns +true+ if there are #versions (file has been modified).
     #
     # *Warning:* It will also return +true+ if the file has been cloned.
@@ -122,7 +104,7 @@ module FilePipeline
     # the file to history, but no FileOperations::Results.
     def clone
       filename = FilePipeline.new_basename + current_extension
-      clone_file = VersionedFile.copy(current, directory, filename)
+      clone_file = Versions.copy(current, directory, filename)
       self << clone_file
     end
 
@@ -159,21 +141,15 @@ module FilePipeline
     #   * +true+ - The finalized version will replace the #original.
     def finalize(overwrite: false)
       yield(self) if block_given?
-      filename = overwrite ? replacing_trarget : preserving_taget
+      return original unless changed?
+
+      filename = overwrite ? replacing_target : preserving_target
       FileUtils.rm original if overwrite
-      @original = VersionedFile.copy(current, original_dir, filename)
+      @original = Versions.copy(current, original_dir, filename)
     ensure
       reset
     end
 
-    # Returns an array of triplets (arryas with three items each): the name of
-    # the file operation class (a string), options (a hash), and the actual log
-    # (an array).
-    def log
-      filter_history(:log)
-        .map { |operation, info| [operation.name, operation.options, info] }
-    end
-
     # Returns the Exif metadata
     #
     # ===== Options
@@ -186,10 +162,14 @@ module FilePipeline
     #--
     # TODO: when file is not an image file, this should return other metadata
     # than exif.
-    # TODO: implement the option to return metadata for a specif version index
     #++
     def metadata(for_version: :current)
-      file = public_send for_version
+      file = case for_version
+             when :current, :original
+               public_send for_version
+             else
+               for_version
+             end
       read_exif(file).first
     end
 
@@ -218,54 +198,32 @@ module FilePipeline
     # Returns a hash into which all captured data from file operations with the
     # FileOperations::CapturedDataTags::DROPPED_EXIF_DATA has been merged.
     def recovered_metadata
+      return unless changed?
+
       captured_data_with(FileOperations::CapturedDataTags::DROPPED_EXIF_DATA)
         &.reduce({}) { |recovered, data| recovered.merge data }
     end
 
-    # Returns an array with paths to the version files of +self+ (excluding
-    # #original).
-    def versions
-      history.keys
-    end
-
     alias touch clone
 
     private
 
-    # item = :data or :log
-    def filter_history(item)
-      history.inject([]) do |results, (_, info)|
-        next results unless info.respond_to?(item) && info.public_send(item)
-
-        results << [info.operation, info.public_send(item)]
-      end
-    end
-
     # Returns the filename for a target file that will not overwrite the
     # original.
-    def preserving_taget
-      basename + '_' + target_suffix + current_extension
+    def preserving_target
+      "#{basename}_#{target_suffix}#{current_extension}"
     end
 
     # Returns the filename for a target file that will overwrite the
     # original.
-    def replacing_trarget
+    def replacing_target
       basename + current_extension
     end
 
     # Deletes the work directory and resets #versions
     def reset
       FileUtils.rm_r directory, force: true
-      @history = {}
-    end
-
-    # Validates if file exists and has been stored in #directory.
-    def validate(file)
-      raise Errors::MissingVersionFileError, file: file unless File.exist? file
-
-      return file if File.dirname(file) == directory
-
-      VersionedFile.move file, directory, File.basename(file)
+      history.clear!
     end
 
     # Creates the directory containing all version files. Directory name is
@@ -273,9 +231,8 @@ module FilePipeline
     #
     # Raises SystemCallError if the directory already exists.
     def workdir
-      subdir = basename + '_versions'
       filedir = File.dirname(original)
-      dirname = File.join filedir, subdir
+      dirname = File.join filedir, "#{basename}_versions"
       FileUtils.mkdir(dirname)
       File.path dirname
     end

data/lib/file_pipeline/versions.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative 'versions/history'
+
+module FilePipeline
+  # Module that contains classes to work with VersionedFile.
+  module Versions
+    # Copies the file with path _src_ to <em>/dir/filename</em>.
+    def self.copy(src, dir, filename)
+      dest = FilePipeline.path(dir, filename)
+      FileUtils.cp src, dest
+      dest
+    end
+
+    # Moves the file with path _src_ to <em>/dir/filename</em>.
+    def self.move(src, dir, filename)
+      dest = FilePipeline.path(dir, filename)
+      FileUtils.mv src, dest
+      dest
+    end
+  end
+end

data/lib/file_pipeline/versions/history.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module FilePipeline
+  module Versions
+    # History objects keep track of a VersionedFile instances versions names and
+    # any associated logs or data for each version.
+    class History
+      # Returns a new instance.
+      def initialize
+        @entries = {}
+      end
+
+      # Retrieves the _results_ object for the <tt>version_name</tt>.
+      def [](version_name)
+        @entries[version_name]
+      end
+
+      # Associates the +results+ with the <tt>version_name</tt>.
+      def []=(version_name, results)
+        entry = @entries.fetch version_name, []
+        entry << results
+        @entries[version_name] = entry.compact
+      end
+
+      # Returns a two-dimensional array, where each nested array has two items:
+      # * the file operation object
+      # * data captured by the operartion (if any).
+      #
+      # <tt>[[file_operation_object, data_or_nil], ...]</tt>
+      def captured_data
+        filter :data
+      end
+
+      # Returns any data captured by <tt>operation_name</tt>.
+      #
+      # If multiple instances of one operation class have modified the file,
+      # pass any +options+ the specific instance of the operation was
+      # initialized with as the optional second argument.
+      def captured_data_for(operation_name, **options)
+        return if empty?
+
+        captured_data.filter { |op, _| matches? op, operation_name, options }
+                     .map(&:last)
+      end
+
+      # Returns an array with all data captured by operations with +tag+.
+      # Returns an empty array if there is no data for +tag+.
+      #
+      # Tags are defined in FileOperations::CapturedDataTags
+      def captured_data_with(tag)
+        captured_data.filter { |op, _| op.captured_data_tag == tag }
+                     .map(&:last)
+      end
+
+      # Clears all history entries (version names and associated results).
+      def clear!
+        @entries.clear
+      end
+
+      # Returns +true+ if +self+ has no entries (version names and associated
+      # results), +true+ otherwise.
+      def empty?
+        @entries.empty?
+      end
+
+      # Returns an array of triplets (arryas with three items each):
+      #  * Name of the file operation class (String).
+      #  * Options for the file operation instance (Hash).
+      #  * The log (Array).
+      def log
+        filter(:log).map { |op, results| [op.name, op.options, results] }
+      end
+
+      # Returns a two-dimensional Array where every nested Array will consist
+      # of the version name (file path) at index +0+ and +nil+ or an Array with
+      # all _results_ objects for the version at index +1+:
+      #
+      # <tt>[version_name, [results1, ...]]</tt>
+      def to_a
+        @entries.to_a
+      end
+
+      # Returns an array with paths to the version files of +self+ (excluding
+      # #original).
+      def versions
+        @entries.keys
+      end
+
+      private
+
+      # Filters entries in self by +item+ (<tt>:log</tt> or <tt>:data</tt>).
+      def filter(item)
+        @entries.values.flatten.select(&item).map do |results|
+          [results.operation, results.public_send(item)]
+        end
+      end
+
+      # Returns +true+ if +name+ matches the _name_ attribute of +operation+ and
+      # +options+ matches the options the operation instance is initialized
+      # with.
+      def matches?(operation, name, opts)
+        operation.name == name && opts.all? { |k, v| operation.options[k] == v }
+      end
+    end
+  end
+end

data/lib/file_pipeline/versions/validator.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module FilePipeline
+  module Versions
+    # Validator objects verify the version file and results returned by a
+    # FileOperation.
+    #
+    # They will validate:
+    # - that the version file existst
+    # - that it is in the correct directory
+    # - that the file operation has not returned any failures
+    class Validator
+      extend Forwardable
+
+      # File for the version that resulted from a FileOperation.
+      attr_reader :file
+
+      # FileOperation::Results object.
+      attr_reader :info
+
+      # Returns a new instance.
+      #
+      # ===== Arguments
+      #
+      # * <tt>version_info</tt> - path to an existing file or an array with the
+      #   path and optionally a FileOperations::Results instance.
+      # * +directory+ - directory where the file is expected (the working
+      #   directory of a VersionedFile).
+      # * +filename+ - name of the file to be returned if the file operation was
+      #   was non-modifying (usually the VersionedFile#original).
+      def initialize(version_info, directory, filename)
+        @file, @info = [version_info].flatten
+        @directory = directory
+        @filename = filename
+      end
+
+      # Validates file, directory, and info for <tt>version_info</tt> in the
+      # context of <tt>versioned_file</tt>.
+      #
+      # ===== Arguments
+      #
+      # * <tt>version_info</tt> - path to an existing file or an array with the
+      #   path and optionally a FileOperations::Results instance.
+      # * <tt>versioned_file</tt> - an object that responds to #original and
+      # returns a file path, and #directory and returns a directory path.
+      def self.[](version_info, versioned_file)
+        new(version_info, versioned_file.directory, versioned_file.original)
+          .validate_info
+          .validate_file
+          .validate_directory
+          .then { |validator| [validator.file, validator.info] }
+      end
+
+      # Returns +true+ when there is no file for the version (result of a
+      # non-modifying file operation), +false+ otherwise.
+      def unmodified?
+        @file.nil?
+      end
+
+      # Raises MisplacedVersionFileError if #file is not in #directory.
+      def validate_directory
+        return self if unmodified? || File.dirname(@file) == @directory
+
+        raise Errors::MisplacedVersionFileError.new file: @file,
+                                                    directory: @directory
+      end
+
+      # Raises MissingVersionFileError if #file does not exist on the file
+      # system.
+      def validate_file
+        return self if unmodified? || File.exist?(@file)
+
+        raise Errors::MissingVersionFileError.new file: @file
+      end
+
+      # Raises FailedModificationError if the file operation generatint the
+      # #info failed.
+      def validate_info
+        return self unless @info&.failure
+
+        raise Errors::FailedModificationError.new info: @info, file: @filename
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: file_pipeline
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.1.1
 platform: ruby
 authors:
 - Martin Stein
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2019-11-19 00:00:00.000000000 Z
+date: 2021-02-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: multi_exiftool
@@ -16,29 +16,29 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.11.0
+        version: 0.16.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.11.0
+        version: 0.16.0
 - !ruby/object:Gem::Dependency
   name: ruby-vips
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.0.16
+        version: 2.0.17
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.0.16
-description: The file_pipeline gem provides a framework fornondestructive application
+        version: 2.0.17
+description: The file_pipeline gem provides a framework for nondestructive application
   of file operation batches to files.
 email: loveablelobster@fastmail.fm
 executables: []
@@ -50,11 +50,13 @@ files:
 - lib/file_pipeline.rb
 - lib/file_pipeline/errors.rb
 - lib/file_pipeline/errors/failed_modification_error.rb
+- lib/file_pipeline/errors/misplaced_version_file_error.rb
 - lib/file_pipeline/errors/missing_version_file_error.rb
 - lib/file_pipeline/errors/source_directory_error.rb
 - lib/file_pipeline/errors/source_file_error.rb
 - lib/file_pipeline/file_operations.rb
 - lib/file_pipeline/file_operations/captured_data_tags.rb
+- lib/file_pipeline/file_operations/default_operations/exif_recovery.rb
 - lib/file_pipeline/file_operations/default_operations/exif_redaction.rb
 - lib/file_pipeline/file_operations/default_operations/exif_restoration.rb
 - lib/file_pipeline/file_operations/default_operations/ptiff_conversion.rb
@@ -65,11 +67,14 @@ files:
 - lib/file_pipeline/file_operations/results.rb
 - lib/file_pipeline/pipeline.rb
 - lib/file_pipeline/versioned_file.rb
+- lib/file_pipeline/versions.rb
+- lib/file_pipeline/versions/history.rb
+- lib/file_pipeline/versions/validator.rb
 homepage: https://github.com/loveablelobster/file_pipeline
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -77,15 +82,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.6
-signing_key: 
+rubygems_version: 3.2.3
+signing_key:
 specification_version: 4
 summary: Nondestructive file processing with a defined batch
 test_files: []