file_pipeline 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe1107c14a49c1372b1d3f62c76db36b262311113d3661b4be3ac3b7275f97b8
-  data.tar.gz: f01ab4be7e0eb246a7da41fa734a2e88491dc90ce01033b3b7a125c012029525
+  metadata.gz: cda1036fc126999807374257bd750430e152b18e401af8a0acb8087a47e92951
+  data.tar.gz: b9acc95e3f3a4cdbdd70d61ebbb1a9bd8c41614cd390455f12ecc18156ceb586
 SHA512:
-  metadata.gz: bc53dff7ae7c5a9955f72e83ee2be935f59db398093b555531b5bdbd619faf4637d6bf5effa1842fcf8b3906a90c1626394b892aa6fd24042063b7e78c2f86fb
-  data.tar.gz: 14f493a7bf76fc55c4e60df8d2f999ae66b5770a064c3cbf03b46e52b8a03602629e399cfb6d395109cbf87d89f7dfc459d3f9911c7b1bdc959fc8b9e49c7881
+  metadata.gz: 2bb410c9ed6ec2d7a1d9eaa57012d1f48521311f930ab3ffd96c2ce249498d0e7cc164a9676fd0d6f66b3060d89fec7a1347680eaf1107c9433ea899ad5615e5
+  data.tar.gz: 41bd9a73cfc94b6c378a21d2eee38cf6badbd59ab29c55faa2a3668a43db01dd0cf5e31e9cd431d2492bc1d854900140844e77014ed0fbfd5bd92bc7d4848100

data/README.rdoc

@@ -0,0 +1,513 @@
+= file_pipeline
+
+The <tt>file_pipeline</tt> gem provides a framework for nondestructive 
+application of file operation batches to files.
+
+== Installation
+
+  gem install file_pipeline
+
+== Dependencies
+
+The file operations included in the gem require 
+{ruby-vips}[https://github.com/libvips/ruby-vips] for image manipulation and
+{multi_exiftool}[https://github.com/janfri/multi_exiftool] for image file
+metdata extraction and manipulation.
+
+While these dependencies should be installed automatically with the gem, 
+ruby-vips depends on {libvips}[https://libvips.github.io/libvips/], and
+multi_exiftool depends on
+{Exiftool}[https://www.sno.phy.queensu.ca/~phil/exiftool/], which will not be
+installed automatically.
+
+== Usage
+
+The basic usage is to create a new FilePipeline::Pipeline object and define any
+file operations that are to be performed, apply it to a 
+FilePipeline::VersionedFile object initialized with the image to be processed,
+then finalize the versioned file.
+
+  require 'file_pipeline'
+
+  # create a new instance of Pipeline
+  my_pipeline = FilePipeline::Pipeline.new
+
+  # configure an operation to scale an image to 1280 x 960 pixels
+  my_pipeline.define_operation('scale', :width => 1280, :height => 960)
+
+  # create an instance of VersionedFile for the file '~/image.jpg'
+  image = FilePipeline::VersionedFile.new('~/image.jpg')
+
+  # apply the pipeline to the versioned file
+  my_pipeline.apply_to(image)
+
+  # finalize the versioned file, replacing the original
+  image.finalize(:overwrite => true)
+
+=== Setting up a Pipeline
+
+Pipeline objects can be set up to contain default file operations included in
+the gem or with custom file operations (see
+{Custom file operations}[rdoc-label:label-Custom+file+operations] for
+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
+{#define_operation}[rdoc-ref:FilePipeline::Pipeline#define_operation].
+
+The example below adds an instance of 
+PtiffConversion[rdoc-ref:FilePipeline::FileOperations::PtiffConversion] with
+the <tt>:tile_width</tt> and <tt>:tile_height</tt> options each set to 64
+pixels.
+
+  my_pipeline = FilePipeline::Pipeline.new
+  my_pipeline.define_operation('ptiff_conversion',
+                               :tile_width => 64, :tile_height => 64)
+
+Chaining is possible
+
+  my_pipeline = FilePipeline::Pipeline.new
+  my_pipeline.define_operation('scale', :width => 1280, :height => 1024)
+             .define_operation('exif_restoration')
+
+Alternatively, operations can be defined during initialization by passing a
+block to {#new}[rdoc-ref:FilePipeline::Pipeline.new].
+
+  my_pipeline = FilePipeline::Pipeline.new do |pipeline|
+    pipeline.define_operation('scale', :width => 1280, :height => 1024)
+    pipeline.define_operation('exif_restoration')
+  end
+
+When using the default operations included in the gem, it is sufficient to
+call <tt>#define_operation</tt> with the desired operations and options.
+
+==== Using custom file operations
+
+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].
+
+Directories are added to the source directories in reverse order, so that
+directories added later will have precedence when searching source files. The
+default operations directory included in the gem will be searched last. This
+allows overriding of operations without changing the code in existing classes.
+
+If, for example, there are two directories with custom file operation classes,
+<tt>'~/custom_operations'</tt> and <tt>'~/other_operations'</tt>, the new
+instance of Pipeline can be set up to look for source files first in
+<tt>'~/other_operations'</tt>, then in <tt>'~/custom_operations'</tt>, and
+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>'my_operation.rb'</tt>
+
+  my_pipeline = FilePipeline::Pipeline.new('~/custom_operations',
+                                           '~/other_operations')
+  my_pipeline.define_operation('my_operation')
+
+See {Custom file operations}[rdoc-label:label-Custom+file+operations] for 
+instructions for how to write file operations.
+
+=== Nondestructive application to files
+
+Pipelines[rdoc-ref:FilePipeline::Pipeline] work on 
+{versioned files}[rdoc-ref:FilePipeline::VersionedFile], which allow for
+non-destructive application of all file operations.
+
+To create a versioned file, initialize an instance with the path to the 
+original file:
+
+  # create an instance of VersionedFile for the file '~/image.jpg'
+  image = FilePipeline::VersionedFile.new('~/image.jpg')
+
+As long as no operations have been applied, this will have no effect in the
+file system. Only when the first operation is applied will VersionedFile
+create a {working directory}[rdoc-ref:FilePipeline::VersionedFile#directory] in
+the same directory as the original file. The working directory will have the
+name of the file basename without extension and the suffix <tt>'_versions'</tt>
+added.
+
+Pipelines can be applied to a singe versioned file with the
+the {#apply_to}[rdoc-ref:FilePipeline::Pipeline#apply_to] method of the pipeline
+instance, or to an array of versioned files with the
+{#batch_apply}[rdoc-ref:FilePipeline::Pipeline#batch_apply] method of the 
+pipeline instance.
+
+=== Accessing file metadata and captured data.
+
+*Limitations*: this currently only works for _Exif_ metadata of image files.
+
+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
+be accessed:
+
+  image = FilePipeline::VersionedFile.new('~/image.jpg')
+
+  # access the metadata for the current version
+  image.metadata
+
+Note that if no file operations have been applied by a pipeline object, this
+will return the metadata for the original, which in that case is the current
+(latest) version.
+
+To explicitly get the metadata for the original file even if there are newer
+versions available, pass the <tt>:for_version</tt> option with the symbol
+<tt>:original</tt>:
+
+  # access the metadata for the original file
+  image.metadata(:for_version => :original)
+
+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 
+{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.
+
+Likewise, if the 
+{ExifRedaction}[rdoc-ref:FilePipeline::FileOperations::ExifRedaction] is applied
+to delete sensitive tags (e.g. GPS location data), it will return all deleted 
+exif tags and their values as captured data.
+
+The
+{#recovered_metadata}[rdoc-ref:FilePipeline::VersionedFile#recovered_metadata]
+of the versioned file instance will return a hash with all metadata that was
+deleted or could not be restored by operations:
+
+  delete_tags = ['CreatorTool', 'Software']
+
+  my_pipeline = FilePipeline::Pipeline.new do |pipeline|
+    pipeline.define_operation('scale', width: 1280, height: 1024)
+    pipeline.define_operation('exif_restoration')
+    Pipeline.define_operation('exif_redaction', :redact_tags => delete_tags)
+  end
+
+  image = FilePipeline::VersionedFile.new('~/image.jpg')
+  my_pipeline.apply_to(image)
+
+  image.recovered_metadata
+
+For information on retrieving other kinds of captured data, refer to
+the versioned file instance methods
+{#captured_data}[rdoc-ref:FilePipeline::VersionedFile#captured_data],
+{#captured_data_for}[rdoc-ref:FilePipeline::VersionedFile#captured_data_for], 
+and
+{#captured_data_with}[rdoc-ref:FilePipeline::VersionedFile#captured_data_with].
+
+=== Finalizing files
+
+Once all file operations of a pipeline object have been applied to a
+versioned file object, it can be finalized by calling the
+{#finalize}[rdoc-ref:FilePipeline::VersionedFile#finalize] method of the
+instance.
+
+Finalization will write the current version to the same directory that
+contains the original. It will by default preserve the original by adding
+a suffix to the basename of the final version. If the <tt>:overwrite</tt>
+option for the method is passed with +true+, it will delete the original and
+write the final version to the same basename as the original.
+
+  image = FilePipeline::VersionedFile.new('~/image.jpg')
+
+  # finalize the versioned file, preserving the original
+  image.finalize
+
+  # finalize the versioned file, replacing the original
+  image.finalize(:overwrite => true)
+
+The work directory with all other versions will be deleted after the final
+version has been written.
+
+== Custom file operations
+
+=== Module nesting
+
+File operation classes _must_ be defined in the FilePipeline::FileOperations
+module for {automatic requiring}[rdoc-ref:FilePipeline.load] of source files to
+work.
+
+=== Implementing from scratch
+
+==== Initializer
+
+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.
+
+This requirement is imposed by the 
+{#define_operation}[rdoc-ref:FilePipeline::Pipeline#define_operation] instance
+method of Pipeline, which will automatically load and initialize an instance of
+the file operation with any options provided as a hash.
+
+===== Examples
+
+  class MyOperation
+    attr_reader :options
+
+    # initializer with a default
+    def initialize(options = {})
+      @options = options
+    end
+  end
+
+  class MyOperation
+    attr_reader :options
+
+    # initializer with a double splat
+    def initialize(**options)
+      @options = options
+    end
+  end
+
+Consider a file operation +CopyrightNotice+ that whill add copyright
+information to an image file's _Exif_ metadata, the value for the copyright
+tag could be passed as an option.
+
+ copyright_notice = CopyrightNotice.new(:copyright => 'The Photographer')
+
+==== The <tt>run</tt> method
+
+File operations _must_ implement a <tt>#run</tt> method that takes three
+arguments (or a _splat_) in order to be used in a Pipeline.
+
+===== Arguments
+
+The three arguments required for implementations of <tt>#run</tt> are:
+* the path to the <em>file to be modified</em>
+* the path to the _directory_ to which new files will be saved.
+* the path to the <em>original file</em>, from which the first version in a
+  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.
+
+===== 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 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.
+
+===== Example
+
+  def run(src_file, directory, original)
+    # make a path to which the created file will be written
+    out_file = File.join(directory, 'new_file_name.extension')
+
+    # create a Results object reporting success with no logs or data
+    results = Results.new(self, true, nil)
+
+    # create a new out_file based on src_file in directory
+    # ...
+
+    # return the path to the new file and the results object
+    [out_file, results]
+  end
+
+==== Captured data tags
+
+Captured data tags can be used to
+{filter captured data}[rdoc-ref:FilePipeline::VersionedFile#captured_data_with] 
+accumulated during successive file operations.
+
+Operations that return data as part of the results _should_ respond to
+<tt>:captured_data_tag</tt> and return one of the 
+{tag constants}[rdoc-ref:FilePipeline::FileOperations::CapturedDataTags].
+
+===== Example
+
+  # returns NO_DATA
+  def captured_data_tag
+    CapturedDataTags::NO_DATA
+  end
+
+=== Subclassing FileOperation
+
+The {FileOperation}[rdoc-ref:FilePipeline::FileOperations::FileOperation] class
+is an abstract superclass that provides a scaffold to facilitate the creation of
+file operations that conform to the requirements.
+
+It implements a 
+{#run}[rdoc-ref:FilePipeline::FileOperations::FileOperation#run] method, that
+takes the required three arguments and returns the path to the newly created
+file and a Results object.
+
+When the operation was successful,
+{success}[rdoc-ref:FilePipeline::FileOperations::Results#success] will be
++true+. When an exception was raised, that exeption will be rescued and returned
+as the {log}[rdoc-ref:FilePipeline::FileOperations::Results#log], and
+{success}[rdoc-ref:FilePipeline::FileOperations::Results#success] will be 
++false+.
+
+The standard <tt>#run</tt> method of the FileOperation class does not contain
+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]).
+
+==== Initializer
+
+The +initialize+ method _must_ take an +options+ argument (a hash with a
+default value or a <em>double splat</em>).
+
+===== Options and defaults
+
+The initializer can call +super+ and pass the +options+ hash and any
+defaults (a hash with default options). This will update the defaults with
+the actual options passed to +initialize+ and assign them to the
+{#options}[rdoc-ref:FilePipeline::FileOperations::FileOperation#options] 
+attribute.
+
+If the initializer does not call +super+, it _must_ assign the options to
+the <tt>@options</tt> instance variable or expose them through an
+<tt>#options</tt> getter method.
+
+If it calls +super+ but must ensure some options are always set to a
+specific value, those should be set after the call to +super+.
+
+===== Examples
+
+  # initializer without defaults callings super
+  def initialize(**options)
+    super(options)
+  end
+
+  # initializer with defaults calling super
+  def initialize(**options)
+    defaults = { :option_a => true, :option_b => false }
+    super(options, defaults)
+  end
+
+  # initializer with defaults calling super, ensures :option_c => true
+  def initialize(**options)
+    defaults = { :option_a => true, :option_b => false }
+    super(options, defaults)
+    @options[:option_c] = true
+  end
+
+  # initilizer that does not call super
+  def initialize(**options)
+    @options = options
+  end
+
+==== The <tt>operation</tt> method
+
+The <tt>#operation</tt> method contains the logic specific to a given
+subclass of FileOperation and must be defined in that subclass unless the
+<tt>#run</tt> method is overwritten.
+
+===== Arguments
+
+The <tt>#operation</tt> method must accept three arguments:
+
+* the path to the <em>file to be modified</em>
+* the path for the <em>file to be created</em> by the operation.
+* the path to the <em>original file</em>, from which the first version in a
+  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.
+
+===== Return Value
+
+The method _can_ return anything that can be interpreted by
+{LogDataParser}[rdoc-ref:FilePipeline::FileOperations::LogDataParser],
+including nothing.
+
+It will usually return any log outpout that the logic of <tt>#operation</tt>
+has generated, and/or data captured. If data is captured that is to be used
+later, the subclass should override the <tt>#captured_data_tag</tt> method to
+return the appropriate 
+{tag constant}[rdoc-ref:FilePipeline::FileOperations::CapturedDataTags].
+
+===== Examples
+
+  # creates out_file based on src_file, captures metadata differences
+  # between out_file and original, returns log messages and captured data
+  def operation(src_file, out_file, original)
+    captured_data = {}
+    log_messages = []
+
+    # write the new version based on src_file to out_file
+    # compare metadata of out_file with original, store any differences
+    # in captures_data and append any log messages to log_messages
+
+    [log_messages, captured_data]
+  end
+
+  # takes the third argument for the original file but does not use it
+  # creates out_file based on src_file, returns log messages
+  def operation(src_file, out_file, _)
+    src_file, out_file = args
+    log_messages = []
+
+    # write the new version based on src_file to out_file
+
+    log_messages
+  end
+
+  # takes arguments as a splat and destructures them to avoid having the
+  # unused thirs argumen
+  # creates out_file based on src_file, returns nothing
+  def operation(*args)
+    src_file, out_file = args
+
+    # write the new version based on src_file to out_file
+
+    return
+  end
+
+==== Target file extensions
+
+If the file that the operation creates is of a different type than the file
+the version is based upon, the class _must_ define the
+<tt>#target_extension</tt> method that returns the appropriate file type
+extension.
+
+In most cases, the resulting file type will be predictable (static), and in
+such cases, the method can just return a string with the extension.
+
+An alternative would be to provide the expected extension as an #option
+to the initializer.
+
+===== Examples
+
+  # returns always '.tiff.
+  def target_extension
+    '.tiff'
+  end
+
+  # returns the extension specified in #options +:extension+
+  # my_operation = MyOperation(:extension => '.dng')
+  def target_extension
+    options[:extension]
+  end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: file_pipeline
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Martin Stein
@@ -38,227 +38,15 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 2.0.14
-description: "= file_pipeline\n\nThe <tt>file_pipeline</tt> gem provides a framework
-  for nondestructive \napplication of file operation batches to files.\n\n== Installation\n\n
-  \ gem install file_pipeline\n\n== Dependencies\n\nThe file operations included in
-  the gem require \n{ruby-vips}[https://github.com/libvips/ruby-vips] for image manipulation
-  and\n{multi_exiftool}[https://github.com/janfri/multi_exiftool] for image file\nmetdata
-  extraction and manipulation.\n\nWhile these dependencies should be installed automatically
-  with the gem, \nruby-vips depends on {libvips}[https://libvips.github.io/libvips/],
-  and\nmulti_exiftool depends on\n{Exiftool}[https://www.sno.phy.queensu.ca/~phil/exiftool/],
-  which will not be\ninstalled automatically.\n\n== Usage\n\nThe basic usage is to
-  create a new FilePipeline::Pipeline object and define any\nfile operations that
-  are to be performed, apply it to a \nFilePipeline::VersionedFile object initialized
-  with the image to be processed,\nthen finalize the versioned file.\n\n  require
-  'file_pipeline'\n\n  # create a new instance of Pipeline\n  my_pipeline = FilePipeline::Pipeline.new\n\n
-  \ # configure an operation to scale an image to 1280 x 960 pixels\n  my_pipeline.define_operation('scale',
-  :width => 1280, :height => 960)\n\n  # create an instance of VersionedFile for the
-  file '~/image.jpg'\n  image = FilePipeline::VersionedFile.new('~/image.jpg')\n\n
-  \ # apply the pipeline to the versioned file\n  my_pipeline.apply_to(image)\n\n
-  \ # finalize the versioned file, replacing the original\n  image.finalize(:overwrite
-  => true)\n\n=== Setting up a Pipeline\n\nPipeline objects can be set up to contain
-  default file operations included in\nthe gem or with custom file operations (see\n{Custom
-  file operations}[rdoc-label:label-Custom+file+operations] for\ninstructions on how
-  to create custom operations).\n\n==== Basic set up with default operations\n\nTo
-  define an operation, pass the class name of the operation in underscore\nnotation
-  and without the containing module name, and any options to\n{#define_operation}[rdoc-ref:FilePipeline::Pipeline#define_operation].\n\nThe
-  example below adds an instance of \nPtiffConversion[rdoc-ref:FilePipeline::FileOperations::PtiffConversion]
-  with\nthe <tt>:tile_width</tt> and <tt>:tile_height</tt> options each set to 64\npixels.\n\n
-  \ my_pipeline = FilePipeline::Pipeline.new\n  my_pipeline.define_operation('ptiff_conversion',\n
-  \                              :tile_width => 64, :tile_height => 64)\n\nChaining
-  is possible\n\n  my_pipeline = FilePipeline::Pipeline.new\n  my_pipeline.define_operation('scale',
-  :width => 1280, :height => 1024)\n             .define_operation('exif_restoration')\n\nAlternatively,
-  operations can be defined during initialization by passing a\nblock to {#new}[rdoc-ref:FilePipeline::Pipeline.new].\n\n
-  \ my_pipeline = FilePipeline::Pipeline.new do |pipeline|\n    pipeline.define_operation('scale',
-  :width => 1280, :height => 1024)\n    pipeline.define_operation('exif_restoration')\n
-  \ end\n\nWhen using the default operations included in the gem, it is sufficient
-  to\ncall <tt>#define_operation</tt> with the desired operations and options.\n\n====
-  Using custom file operations\n\nWhen file operations are to be used that are not
-  included in the gem, place\nthe source files for the class definitions in one or
-  more directories and\ninitialize the Pipeline object with the directory paths. The
-  directories will\nbe added to the {source directories}[rdoc-ref:FilePipeline.source_directories].\n\nDirectories
-  are added to the source directories in reverse order, so that\ndirectories added
-  later will have precedence when searching source files. The\ndefault operations
-  directory included in the gem will be searched last. This\nallows overriding of
-  operations without changing the code in existing classes.\n\nIf, for example, there
-  are two directories with custom file operation classes,\n<tt>'~/custom_operations'</tt>
-  and <tt>'~/other_operations'</tt>, the new\ninstance of Pipeline can be set up to
-  look for source files first in\n<tt>'~/other_operations'</tt>, then in <tt>'~/custom_operations'</tt>,
-  and\nfinally in the included default operations.\n\nThe basename for source files
-  _must_ be the class name in underscore notation\nwithout the containing module name.
-  If, for example, the operation is\n<tt>FileOperations::MyOperation</tt>, the source
-  file basename should be\n<tt>'my_operation.rb'</tt>\n\n  my_pipeline = FilePipeline::Pipeline.new('~/custom_operations',\n
-  \                                          '~/other_operations')\n  my_pipeline.define_operation('my_operation')\n\nSee
-  {Custom file operations}[rdoc-label:label-Custom+file+operations] for \ninstructions
-  for how to write file operations.\n\n=== Nondestructive application to files\n\nPipelines[rdoc-ref:FilePipeline::Pipeline]
-  work on \n{versioned files}[rdoc-ref:FilePipeline::VersionedFile], which allow for\nnon-destructive
-  application of all file operations.\n\nTo create a versioned file, initialize an
-  instance with the path to the \noriginal file:\n\n  # create an instance of VersionedFile
-  for the file '~/image.jpg'\n  image = FilePipeline::VersionedFile.new('~/image.jpg')\n\nAs
-  long as no operations have been applied, this will have no effect in the\nfile system.
-  Only when the first operation is applied will VersionedFile\ncreate a {working directory}[rdoc-ref:FilePipeline::VersionedFile#directory]
-  in\nthe same directory as the original file. The working directory will have the\nname
-  of the file basename without extension and the suffix <tt>'_versions'</tt>\nadded.\n\nPipelines
-  can be applied to a singe versioned file with the\nthe {#apply_to}[rdoc-ref:FilePipeline::Pipeline#apply_to]
-  method of the pipeline\ninstance, or to an array of versioned files with the\n{#batch_apply}[rdoc-ref:FilePipeline::Pipeline#batch_apply]
-  method of the \npipeline instance.\n\n=== Accessing file metadata and captured data.\n\n*Limitations*:
-  this currently only works for _Exif_ metadata of image files.\n\nVersionedFile provides
-  access to a files metadata via the\n{#metadata}[rdoc-ref:FilePipeline::VersionedFile#metadata]
-  method of the \nversioned file instance.\n\nBoth the metadata for the original file
-  and the current (latest) version can\nbe accessed:\n\n  image = FilePipeline::VersionedFile.new('~/image.jpg')\n\n
-  \ # access the metadata for the current version\n  image.metadata\n\nNote that if
-  no file operations have been applied by a pipeline object, this\nwill return the
-  metadata for the original, which in that case is the current\n(latest) version.\n\nTo
-  explicitly get the metadata for the original file even if there are newer\nversions
-  available, pass the <tt>:for_version</tt> option with the symbol\n<tt>:original</tt>:\n\n
-  \ # access the metadata for the original file\n  image.metadata(:for_version =>
-  :original)\n\nSome file operations can comprise metadata; many image processing
-  libraries\nwill not preserve all _Exif_ tags and their values when converting images
-  to\na different format, but only write a small subset of tags to the file they\ncreate.
-  In these cases, the \n{ExifRestoration}[rdoc-ref:FilePipeline::FileOperations::ExifRestoration]\noperation
-  can be used to try to restore the tags that have been discarded, but\nit can not
-  write all tags. It will store all tags and their values that it could \nnot write
-  back to the file and return them as captured data.\n\nLikewise, if the \n{ExifRedaction}[rdoc-ref:FilePipeline::FileOperations::ExifRedaction]
-  is applied\nto delete sensitive tags (e.g. GPS location data), it will return all
-  deleted \nexif tags and their values as captured data.\n\nThe\n{#recovered_metadata}[rdoc-ref:FilePipeline::VersionedFile#recovered_metadata]\nof
-  the versioned file instance will return a hash with all metadata that was\ndeleted
-  or could not be restored by operations:\n\n  delete_tags = ['CreatorTool', 'Software']\n\n
-  \ my_pipeline = FilePipeline::Pipeline.new do |pipeline|\n    pipeline.define_operation('scale',
-  width: 1280, height: 1024)\n    pipeline.define_operation('exif_restoration')\n
-  \   Pipeline.define_operation('exif_redaction', :redact_tags => delete_tags)\n  end\n\n
-  \ image = FilePipeline::VersionedFile.new('~/image.jpg')\n  my_pipeline.apply_to(image)\n\n
-  \ image.recovered_metadata\n\nFor information on retrieving other kinds of captured
-  data, refer to\nthe versioned file instance methods\n{#captured_data}[rdoc-ref:FilePipeline::VersionedFile#captured_data],\n{#captured_data_for}[rdoc-ref:FilePipeline::VersionedFile#captured_data_for],
-  \nand\n{#captured_data_with}[rdoc-ref:FilePipeline::VersionedFile#captured_data_with].\n\n===
-  Finalizing files\n\nOnce all file operations of a pipeline object have been applied
-  to a\nversioned file object, it can be finalized by calling the\n{#finalize}[rdoc-ref:FilePipeline::VersionedFile#finalize]
-  method of the\ninstance.\n\nFinalization will write the current version to the same
-  directory that\ncontains the original. It will by default preserve the original
-  by adding\na suffix to the basename of the final version. If the <tt>:overwrite</tt>\noption
-  for the method is passed with +true+, it will delete the original and\nwrite the
-  final version to the same basename as the original.\n\n  image = FilePipeline::VersionedFile.new('~/image.jpg')\n\n
-  \ # finalize the versioned file, preserving the original\n  image.finalize\n\n  #
-  finalize the versioned file, replacing the original\n  image.finalize(:overwrite
-  => true)\n\nThe work directory with all other versions will be deleted after the
-  final\nversion has been written.\n\n== Custom file operations\n\n=== Module nesting\n\nFile
-  operation classes _must_ be defined in the FilePipeline::FileOperations\nmodule
-  for {automatic requiring}[rdoc-ref:FilePipeline.load] of source files to\nwork.\n\n===
-  Implementing from scratch\n\n==== Initializer\n\nThe <tt>#initialize</tt> method
-  _must_ take an +options+ argument (a hash\nwith a default value, or a <em>double
-  splat</em>) and _must_ be exposed\nthrough an <tt>#options</tt> getter method.\n\nThe
-  options passed can be any for the file operation to properly configure\na specific
-  instance of a method.\n\nThis requirement is imposed by the \n{#define_operation}[rdoc-ref:FilePipeline::Pipeline#define_operation]
-  instance\nmethod of Pipeline, which will automatically load and initialize an instance
-  of\nthe file operation with any options provided as a hash.\n\n===== Examples\n\n
-  \ class MyOperation\n    attr_reader :options\n\n    # initializer with a default\n
-  \   def initialize(options = {})\n      @options = options\n    end\n  end\n\n  class
-  MyOperation\n    attr_reader :options\n\n    # initializer with a double splat\n
-  \   def initialize(**options)\n      @options = options\n    end\n  end\n\nConsider
-  a file operation +CopyrightNotice+ that whill add copyright\ninformation to an image
-  file's _Exif_ metadata, the value for the copyright\ntag could be passed as an option.\n\n
-  copyright_notice = CopyrightNotice.new(:copyright => 'The Photographer')\n\n====
-  The <tt>run</tt> method\n\nFile operations _must_ implement a <tt>#run</tt> method
-  that takes three\narguments (or a _splat_) in order to be used in a Pipeline.\n\n=====
-  Arguments\n\nThe three arguments required for implementations of <tt>#run</tt> are:\n*
-  the path to the <em>file to be modified</em>\n* the path to the _directory_ to which
-  new files will be saved.\n* the path to the <em>original file</em>, from which the
-  first version in a\n  succession of modified versions has been created.\n\nThe <em>original
-  file</em> will only be used by file operations that require\nit for reference, e.g.
-  to restore file metadata that was compromised by\nother file operations.\n\n=====
-  Return value\n\nThe method _must_ return the path to the file that was created by
-  the\noperation (perferrably in the _directory_). It _may_ also return a \n{Results}[rdoc-ref:FilePipeline::FileOperations::Results]
-  object, containing the\noperation itself, a _success_ flag (+true+ or +false+),
-  and any logs or data\nreturned by the operation.\n\nIf results are returned with
-  the path to the created file, both values must\nbe wrapped in an array, with the
-  path as the first element, the results as\nthe second.\n\n===== Example\n\n  def
-  run(src_file, directory, original)\n    # make a path to which the created file
-  will be written\n    out_file = File.join(directory, 'new_file_name.extension')\n\n
-  \   # create a Results object reporting success with no logs or data\n    results
-  = Results.new(self, true, nil)\n\n    # create a new out_file based on src_file
-  in directory\n    # ...\n\n    # return the path to the new file and the results
-  object\n    [out_file, results]\n  end\n\n==== Captured data tags\n\nCaptured data
-  tags can be used to\n{filter captured data}[rdoc-ref:FilePipeline::VersionedFile#captured_data_with]
-  \naccumulated during successive file operations.\n\nOperations that return data
-  as part of the results _should_ respond to\n<tt>:captured_data_tag</tt> and return
-  one of the \n{tag constants}[rdoc-ref:FilePipeline::FileOperations::CapturedDataTags].\n\n=====
-  Example\n\n  # returns NO_DATA\n  def captured_data_tag\n    CapturedDataTags::NO_DATA\n
-  \ end\n\n=== Subclassing FileOperation\n\nThe {FileOperation}[rdoc-ref:FilePipeline::FileOperations::FileOperation]
-  class\nis an abstract superclass that provides a scaffold to facilitate the creation
-  of\nfile operations that conform to the requirements.\n\nIt implements a \n{#run}[rdoc-ref:FilePipeline::FileOperations::FileOperation#run]
-  method, that\ntakes the required three arguments and returns the path to the newly
-  created\nfile and a Results object.\n\nWhen the operation was successful,\n{success}[rdoc-ref:FilePipeline::FileOperations::Results#success]
-  will be\n+true+. When an exception was raised, that exeption will be rescued and
-  returned\nas the {log}[rdoc-ref:FilePipeline::FileOperations::Results#log], and\n{success}[rdoc-ref:FilePipeline::FileOperations::Results#success]
-  will be \n+false+.\n\nThe standard <tt>#run</tt> method of the FileOperation class
-  does not contain\nlogic to perform the actual file operation, but will call an \n{#operation
-  method}[rdoc-label:label-The+operation+method] that _must_ be\ndefined in the subclass
-  unless the subclass overrides the <tt>#run</tt> method.\n\nThe <tt>#run</tt> method
-  will generate the new path that is passed to the\n<tt>#operation</tt> method, and
-  to which the latter will write the new\nversion of the file. The new file path will
-  need an appropriate file type\nextension. The default behavior is to assume that
-  the extension will be the\nsame as for the file that was passed in as the basis
-  from which the new\nversion will be created. If the operation will result in a different
-  file\ntype, the subclass _should_ define a <tt>#target_extension</tt> method that\nreturns
-  the appropriate file extension (see\n{Target file extensions}[rdoc-label:label-Target+file+extensions]).\n\n====
-  Initializer\n\nThe +initialize+ method _must_ take an +options+ argument (a hash
-  with a\ndefault value or a <em>double splat</em>).\n\n===== Options and defaults\n\nThe
-  initializer can call +super+ and pass the +options+ hash and any\ndefaults (a hash
-  with default options). This will update the defaults with\nthe actual options passed
-  to +initialize+ and assign them to the\n{#options}[rdoc-ref:FilePipeline::FileOperations::FileOperation#options]
-  \nattribute.\n\nIf the initializer does not call +super+, it _must_ assign the options
-  to\nthe <tt>@options</tt> instance variable or expose them through an\n<tt>#options</tt>
-  getter method.\n\nIf it calls +super+ but must ensure some options are always set
-  to a\nspecific value, those should be set after the call to +super+.\n\n===== Examples\n\n
-  \ # initializer without defaults callings super\n  def initialize(**options)\n    super(options)\n
-  \ end\n\n  # initializer with defaults calling super\n  def initialize(**options)\n
-  \   defaults = { :option_a => true, :option_b => false }\n    super(options, defaults)\n
-  \ end\n\n  # initializer with defaults calling super, ensures :option_c => true\n
-  \ def initialize(**options)\n    defaults = { :option_a => true, :option_b => false
-  }\n    super(options, defaults)\n    @options[:option_c] = true\n  end\n\n  # initilizer
-  that does not call super\n  def initialize(**options)\n    @options = options\n
-  \ end\n\n==== The <tt>operation</tt> method\n\nThe <tt>#operation</tt> method contains
-  the logic specific to a given\nsubclass of FileOperation and must be defined in
-  that subclass unless the\n<tt>#run</tt> method is overwritten.\n\n===== Arguments\n\nThe
-  <tt>#operation</tt> method must accept three arguments:\n\n* the path to the <em>file
-  to be modified</em>\n* the path for the <em>file to be created</em> by the operation.\n*
-  the path to the <em>original file</em>, from which the first version in a\n  succession
-  of modified versions has been created.\n\nThe <em>original file</em> will only be
-  used by file operations that require\nit for reference, e.g. to restore file metadata
-  that was compromised by\nother file operations.\n\n===== Return Value\n\nThe method
-  _can_ return anything that can be interpreted by\n{LogDataParser}[rdoc-ref:FilePipeline::FileOperations::LogDataParser],\nincluding
-  nothing.\n\nIt will usually return any log outpout that the logic of <tt>#operation</tt>\nhas
-  generated, and/or data captured. If data is captured that is to be used\nlater,
-  the subclass should override the <tt>#captured_data_tag</tt> method to\nreturn the
-  appropriate \n{tag constant}[rdoc-ref:FilePipeline::FileOperations::CapturedDataTags].\n\n=====
-  Examples\n\n  # creates out_file based on src_file, captures metadata differences\n
-  \ # between out_file and original, returns log messages and captured data\n  def
-  operation(src_file, out_file, original)\n    captured_data = {}\n    log_messages
-  = []\n\n    # write the new version based on src_file to out_file\n    # compare
-  metadata of out_file with original, store any differences\n    # in captures_data
-  and append any log messages to log_messages\n\n    [log_messages, captured_data]\n
-  \ end\n\n  # takes the third argument for the original file but does not use it\n
-  \ # creates out_file based on src_file, returns log messages\n  def operation(src_file,
-  out_file, _)\n    src_file, out_file = args\n    log_messages = []\n\n    # write
-  the new version based on src_file to out_file\n\n    log_messages\n  end\n\n  #
-  takes arguments as a splat and destructures them to avoid having the\n  # unused
-  thirs argumen\n  # creates out_file based on src_file, returns nothing\n  def operation(*args)\n
-  \   src_file, out_file = args\n\n    # write the new version based on src_file to
-  out_file\n\n    return\n  end\n\n==== Target file extensions\n\nIf the file that
-  the operation creates is of a different type than the file\nthe version is based
-  upon, the class _must_ define the\n<tt>#target_extension</tt> method that returns
-  the appropriate file type\nextension.\n\nIn most cases, the resulting file type
-  will be predictable (static), and in\nsuch cases, the method can just return a string
-  with the extension.\n\nAn alternative would be to provide the expected extension
-  as an #option\nto the initializer.\n\n===== Examples\n\n  # returns always '.tiff.\n
-  \ def target_extension\n    '.tiff'\n  end\n\n  # returns the extension specified
-  in #options +:extension+\n  # my_operation = MyOperation(:extension => '.dng')\n
-  \ def target_extension\n    options[:extension]\n  end\n"
+description: The <tt>file_pipeline</tt> gem provides a framework fornondestructive
+  application of file operation batches to files.
 email: loveablelobster@fastmail.fm
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE
+- README.rdoc
 - lib/file_pipeline.rb
 - lib/file_pipeline/errors.rb
 - lib/file_pipeline/errors/failed_modification_error.rb