file_pipeline 0.0.7 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b25bf4205819b6d0df2fcbb9a879c7855fc2b0a3cb973774049f44a7d6965b8
-  data.tar.gz: 1191020063c4bb7669e9dfd88a03d539c7b081cd2f422decd87ac6bca288c86e
+  metadata.gz: d91b7a6c23d1882671966e17afc994e18ccb2d5aa26105d9759e8b37ee393109
+  data.tar.gz: adeea178ac4e331b837a014b91572b1e498f215f3d81b854b1744dc8738eb113
 SHA512:
-  metadata.gz: 8ccb8dabb09322d7c3b6b258c8e4e06edb3a7774e36c1fc26421794b8c53915b219a85c8c9bf07da2bf203cd949a8fc484a1db1cb8ddf6d8443a5c2ba724d4ff
-  data.tar.gz: 3e5a2ec367ab3a2d7280c9d6daaa41f6e3cadcba9b1b73bfdb891d4fef781bade2e4e5ffe970aee76e175ce43ea3ae82d967367f18b29f59dbffec180825262e
+  metadata.gz: f5671985f69f7600efd16bbc4ad9ff56c815268deb0ef3f4f76dacc9de56c422a3e8f8a35b1d4c1b52c707144b8287ef64c7b91d773b3d4d6be8c0dd235ffb93
+  data.tar.gz: ba7d56495aca8c56cce1bea10f27467703f4c1121632ce34de07b6f7e693c3b0648e6b4fb4c7c213d07ff1649c1248c29f6eae971b813c2c78655d766af6387d

data/README.rdoc

@@ -248,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
@@ -296,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
 
@@ -367,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
 
@@ -490,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/errors/failed_modification_error.rb

@@ -12,7 +12,7 @@ module FilePipeline
       #
       # ===== Arguments
       #
-      # * +msg+ - error message for the exception. If none provided, the 
+      # * +msg+ - error message for the exception. If none provided, the
       #   instance will be initialized with the #default_message.
       #
       # ===== Options
@@ -38,7 +38,7 @@ module FilePipeline
 
       private
 
-      # Appends the backtrace of the error that caused the exception to the 
+      # Appends the backtrace of the error that caused the exception to the
       # #default_message.
       def append_backtrace(str)
         return str + "\n" unless original_backtrace
@@ -46,7 +46,7 @@ module FilePipeline
         str + " Backtrace:\n#{original_backtrace}"
       end
 
-      # Appends the message of the error that caused the exception to the 
+      # Appends the message of the error that caused the exception to the
       # #default_message.
       def append_error(str)
         return str unless original_error

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/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]

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/versioned_file.rb

@@ -198,6 +198,7 @@ module FilePipeline
     # 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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: file_pipeline
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.0.8
 platform: ruby
 authors:
 - Martin Stein
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-12-09 00:00:00.000000000 Z
+date: 2019-12-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: multi_exiftool
@@ -55,6 +55,7 @@ files:
 - 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