Class: FilePipeline::FileOperations::FileOperation

Inherits:
Object
  • Object
show all
Defined in:
lib/file_pipeline/file_operations/file_operation.rb

Overview

This is an abstract class to be subclassed when file operations are implemented.

For the autoloading mechanism in FilePipeline.load to work, it is required that subclasses are in defined in the module FilePipeline::FileOperations.

The constructor (#initialze) must accept a doublesplat argument as the only argument and should call super.

Subclasses must implement an #operation method or override the #run method.

If the operation results in file type different than that of the file that is passed to #run or #operation as src_file, the subclass must have a #target_extension method that returns the appropriate extension.

Direct Known Subclasses

ExifRedaction, ExifRestoration, PtiffConversion, Scale

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(opts, defaults = {}) ⇒ FileOperation

Returns a new instance and sets #options.

This can be called from subclasses.

Arguments

  • defaults - Default options for the subclass (hash).

  • opts - Options passed to the sublass initializer (hash).



33
34
35
 
# File 'lib/file_pipeline/file_operations/file_operation.rb', line 33

def initialize(opts, defaults = {})
  @options = defaults.update(opts)
end

Instance Attribute Details

#options ⇒ Object (readonly)

A Hash; any options used when performing #operation.



23
24
25
 
# File 'lib/file_pipeline/file_operations/file_operation.rb', line 23

def options
  @options
end

Instance Method Details

#captured_data_tag ⇒ Object

Returns the NO_DATA tag.

If the results returned by a subclass contain data, override this methos to return the appropriate tag for the data. This tag can be used to filter data captured by operations.

Tags are defined in CapturedDataTags.



44
45
46
 
# File 'lib/file_pipeline/file_operations/file_operation.rb', line 44

def captured_data_tag
  CapturedDataTags::NO_DATA
end

#extension(file) ⇒ Object

Returns the extension for file (a string). This should be the extension for the type the file created by #operation will have.

If the #operation of a subclass will result in a different extension of predictable type, define a #target_extension method.



53
54
55
 
# File 'lib/file_pipeline/file_operations/file_operation.rb', line 53

def extension(file)
  target_extension || File.extname(file)
end

#failure(log_data = nil) ⇒ Object

Returns a Results object with the Results#success set to false and any information returned by the operation in log_data (a string error, array, or hash).



60
61
62
 
# File 'lib/file_pipeline/file_operations/file_operation.rb', line 60

def failure(log_data = nil)
  results false, log_data
end

#name ⇒ Object

Returns the class name (string) of self without the names of the modules that the class is nested in.



66
67
68
 
# File 'lib/file_pipeline/file_operations/file_operation.rb', line 66

def name
  self.class.name.split('::').last
end

#operation(*_) ⇒ Object

:args: src_file, out_file, original = nil

To be implemented in subclasses. Should return any logged errors or data produced (a string, error, array, or hash) or nil.

Arguments

  • src_file - Path for the file the operation will use as the basis for the new version it will create.

  • out_file - Path the file created by the operation will be written to.

  • original - Path to the original, unmodified, file (optional).



82
83
84
 
# File 'lib/file_pipeline/file_operations/file_operation.rb', line 82

def operation(*_)
  raise 'not implemented'
end

#results(success, log_data = nil) ⇒ Object

Returns a new Results object with the #descrip1tion of self, success, and any information returned by the operation as log_data (a string, error, array, or hash.)

Examples
error = StandardError.new
warning = 'a warning occurred'
log = [error, warning]
data = { mime_type: 'image/jpeg' }

my_op = MyOperation.new

my_op.results(false, error)
# => <Results @data=nil, @log=[error], ..., @success=false>

my_op.results(true, warning)
# => <Results @data=nil, @log=[warning], ..., @success=true>

my_op.results(true, data)
# => <Results @data=data, @log=[], ..., @success=true>

my_op.results(true, [warning, data])
# => <Results @data=data, @log=[warning], ..., @success=true>

my_op.results(false, log)
# => <Results @data=nil, @log=[error, warning], ..., @success=false>

my_op.results(false, [log, data])
# => <Results @data=data, @log=[error, warning], ..., @success=false>



117
118
119
 
# File 'lib/file_pipeline/file_operations/file_operation.rb', line 117

def results(success, log_data = nil)
  Results.new(self, success, log_data)
end

#run(src_file, directory, original = nil) ⇒ Object

Runs the operation on src_file and retunes an array with a path for the file created by the operation and a Results object.

Subclasses of FileOperation must either implement an #operation method, or override the #run method, making sure it has the same signature and kind of return value.

The method will create a new path for the file produced by #operation to be written to. This path will consist of directory and a new basename.

The optional original argument can be used to reference another file, e.g. when exif metadata tags missing in the src_file are to be copied over from another file.



134
135
136
137
138
139
140
141
 
# File 'lib/file_pipeline/file_operations/file_operation.rb', line 134

def run(src_file, directory, original = nil)
  out_file = target directory, extension(src_file)
  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
  [out_file, failure(e)]
end

#success(log_data = nil) ⇒ Object

Returns a Results object with the Results#success set to true and any information returned by the operation in log_data (a string error, array, or hash).



146
147
148
 
# File 'lib/file_pipeline/file_operations/file_operation.rb', line 146

def success(log_data = nil)
  results true, log_data
end

#target(directory, extension, kind = :timestamp) ⇒ Object

Returns a new path to which the file created by the operation can be written. The path will be in directory, with a new basename determined by kind and have the specified file extension.

There are two options for the kind of basename to be created:

  • :timestamp (default) - Creates a timestamp basename.

  • :random - Creates a UUID basename.

The timestamp format is YYYY-MM-DDTHH:MM:SS.NNNNNNNNN.

Examples
file_operation.target('path/to/dir', '.png', :timestamp)
# => 'path/to/dir/2019-07-24T09:30:12:638935761.png'

file_operation.target('path/to/dir', '.png', :random)
# => 'path/to/dir/123e4567-e89b-12d3-a456-426655440000.png'



167
168
169
170
 
# File 'lib/file_pipeline/file_operations/file_operation.rb', line 167

def target(directory, extension, kind = :timestamp)
  filename = FilePipeline.new_basename(kind) + extension
  File.join directory, filename
end

#target_extension ⇒ Object

Returns nil.

If the #operation of a subclass will result in a different extension of predictable type, override this method to return the appropriate type.

If, for instance, the operation will always create a TIFF file, the implementation could be:

# Returns '.tiff'
def target_extension
  '.tiff'
end



185
 
# File 'lib/file_pipeline/file_operations/file_operation.rb', line 185

def target_extension; end