Class: Rake::Pipeline::Filter Abstract

Inherits:
Object
  • Object
show all
Defined in:
lib/rake-pipeline/filter.rb

Overview

This class is abstract.

A Filter is added to a pipeline and converts input files into output files.

Filters operate on FileWrappers, which abstract away the root directory of a file, providing a relative path and a mechanism for reading and writing.

For instance, a filter to wrap the contents of each file in a JavaScript closure would look like:

require "json"

class ClosureFilter < Rake::Pipeline::Filter
  def generate_output(inputs, output)
    inputs.each do |input|
      output.write "(function() { #{input.read.to_json} })()"
    end
  end
end

A filter’s files come from the input directory or the directory owned by the previous filter, but filters are insulated from this concern.

You can call path on a FileWrapper to get the file’s relative path, or ‘fullpath` to get its absolute path, but you should, in general, not use `fullpath` but instead use methods of FileWrapper like `read` and `write` that abstract the details from you.

See Also:

Direct Known Subclasses

ConcatFilter, GsubFilter

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(&block) ⇒ Filter

Returns a new instance of Filter.

Parameters:



81
82
83
84
85
 
# File 'lib/rake-pipeline/filter.rb', line 81

def initialize(&block)
  block ||= proc { |input| input }
  @output_name_generator = block
  @input_files = []
end

Instance Attribute Details

#file_wrapper_class ⇒ Class

Returns the class to use as the wrapper for output files.

Returns:

  • (Class) —

    the class to use as the wrapper for output files.



109
110
111
 
# File 'lib/rake-pipeline/filter.rb', line 109

def file_wrapper_class
  @file_wrapper_class ||= FileWrapper
end

#input_files ⇒ Array<FileWrapper>

Returns an Array of FileWrappers that represent the inputs of this filter. The Pipeline will usually set this up.

Returns:

  • (Array<FileWrapper>) —

    an Array of FileWrappers that represent the inputs of this filter. The Pipeline will usually set this up.



46
47
48
 
# File 'lib/rake-pipeline/filter.rb', line 46

def input_files
  @input_files
end

#last_manifest ⇒ Object 



94
95
96
 
# File 'lib/rake-pipeline/filter.rb', line 94

def last_manifest
  @last_manifest || pipeline.last_manifest
end

#manifest ⇒ Rake::Pipeline::Manifest

to generated rake tasks. Use the pipeline’s manifest if this is not set

Returns:



90
91
92
 
# File 'lib/rake-pipeline/filter.rb', line 90

def manifest
  @manifest || pipeline.manifest
end

#output_name_generator ⇒ Proc

Returns a block that returns the relative output filename for a particular input file. If the block accepts just one argument, it will be passed the input’s path. If it accepts two, it will also be passed the input itself.

Returns:

  • (Proc) —

    a block that returns the relative output filename for a particular input file. If the block accepts just one argument, it will be passed the input’s path. If it accepts two, it will also be passed the input itself.



52
53
54
 
# File 'lib/rake-pipeline/filter.rb', line 52

def output_name_generator
  @output_name_generator
end

#output_root ⇒ String

Returns the root directory to write output files to. For the last filter in a pipeline, the pipeline will set this to the pipeline’s output. For all other filters, the pipeline will create a temporary directory that it also uses when creating FileWrappers for the next filter’s inputs.

Returns:

  • (String) —

    the root directory to write output files to. For the last filter in a pipeline, the pipeline will set this to the pipeline’s output. For all other filters, the pipeline will create a temporary directory that it also uses when creating FileWrappers for the next filter’s inputs.



60
61
62
 
# File 'lib/rake-pipeline/filter.rb', line 60

def output_root
  @output_root
end

#pipeline ⇒ Rake::Pipeline

Returns the Rake::Pipeline that contains this filter.

Returns:



73
74
75
 
# File 'lib/rake-pipeline/filter.rb', line 73

def pipeline
  @pipeline
end

#rake_application ⇒ Rake::Application

The Rake::Application that the filter should define new tasks on.

Returns:

  • (Rake::Application) 


192
193
194
 
# File 'lib/rake-pipeline/filter.rb', line 192

def rake_application
  @rake_application || Rake.application
end

#rake_tasks ⇒ Array<Rake::Task> (readonly)

Returns an Array of Rake tasks created for this filter. Each unique output file will get a single task.

Returns:

  • (Array<Rake::Task>) —

    an Array of Rake tasks created for this filter. Each unique output file will get a single task.



65
66
67
 
# File 'lib/rake-pipeline/filter.rb', line 65

def rake_tasks
  @rake_tasks
end

Class Method Details

.processes_binary_files ⇒ void

This method returns an undefined value.

Invoke this method in a subclass of Filter to declare that it expects to work with BINARY data, and that data that is not valid UTF-8 should be allowed.



103
104
105
 
# File 'lib/rake-pipeline/filter.rb', line 103

def self.processes_binary_files
  define_method(:encoding) { "BINARY" }
end

Instance Method Details

#additional_dependencies(input) ⇒ Array<String>

Returns array of file paths within additional dependencies.

Parameters:

Returns:

  • (Array<String>) —

    array of file paths within additional dependencies



198
199
200
 
# File 'lib/rake-pipeline/filter.rb', line 198

def additional_dependencies(input)
  []
end

#generate_rake_tasks ⇒ void

This method returns an undefined value.

Generate the Rake tasks for the output files of this filter.

See Also:



206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
 
# File 'lib/rake-pipeline/filter.rb', line 206

def generate_rake_tasks
  @rake_tasks = outputs.map do |output, inputs|
    additional_paths = []
    inputs.each do |input|

      create_file_task(input.fullpath).dynamic do
        additional_paths += additional_dependencies(input)
      end
    end
    additional_paths.each { |path| create_file_task(path) }

    create_file_task(output.fullpath, inputs.map(&:fullpath)) do
      output.create { generate_output(inputs, output) }
    end
  end
end

#output_files ⇒ Array<FileWrapper>

An Array of the Rake::Pipeline::FileWrapper objects that rerepresent this filter’s output files. It is the same as outputs.keys.

Returns:

See Also:



185
186
187
 
# File 'lib/rake-pipeline/filter.rb', line 185

def output_files
  input_files.map { |file| output_wrappers(file) }.flatten.uniq
end

#outputs ⇒ Hash{FileWrapper => Array<FileWrapper>}

A hash of output files pointing at their associated input files. The output names are created by applying the #output_name_generator to each input file.

For exmaple, if you had the following input files:

javascripts/jquery.js
javascripts/sproutcore.js
stylesheets/sproutcore.css

And you had the following #output_name_generator:

filter.output_name_generator = proc do |filename|
  # javascripts/jquery.js becomes:
  # ["javascripts", "jquery", "js"]
  directory, file, ext = file.split(/[\.\/]/)

  "#{directory}.#{ext}"
end

You would end up with the following hash:

{
  #<FileWrapper path="javascripts.js" root="#{output_root}> => [
    #<FileWrapper path="javascripts/jquery.js" root="#{previous_filter.output_root}">,
    #<FileWrapper path="javascripts/sproutcore.js" root="#{previous_filter.output_root}">
  ],
  #<FileWrapper path="stylesheets.css" root="#{output_root}"> => [
    #<FileWrapper path="stylesheets/sproutcore.css" root=#{previous_filter.output_root}">
  ]
}

Each output file becomes a Rake task, which invokes the #generate_output method defined by the subclass of Rake::Pipeline::Filter with the Array of inputs and the output (all as Rake::Pipeline::FileWrappers).

Returns:



167
168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/rake-pipeline/filter.rb', line 167

def outputs
  hash = {}

  input_files.each do |file|
    output_wrappers(file).each do |output|
      hash[output] ||= []
      hash[output] << file
    end
  end

  hash
end