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

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(&block) ⇒ Filter

Returns a new instance of Filter.

Parameters:



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

def initialize(&block)
  block ||= proc { |input| input }
  @output_name_generator = block
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.



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

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

#output_name_generator ⇒ Proc

Returns a block that returns the relative output filename for a particular input file.

Returns:

  • (Proc) —

    a block that returns the relative output filename for a particular input file.



50
51
52
 
# File 'lib/rake-pipeline/filter.rb', line 50

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.



58
59
60
 
# File 'lib/rake-pipeline/filter.rb', line 58

def output_root
  @output_root
end

#rake_application ⇒ Rake::Application

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

Returns:

  • (Rake::Application) 


174
175
176
 
# File 'lib/rake-pipeline/filter.rb', line 174

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.



63
64
65
 
# File 'lib/rake-pipeline/filter.rb', line 63

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.



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

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

Instance Method Details

#generate_rake_tasks ⇒ void

This method returns an undefined value.

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

See Also:



182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/rake-pipeline/filter.rb', line 182

def generate_rake_tasks
  @rake_tasks = outputs.map do |output, inputs|
    dependencies = inputs.map(&:fullpath)

    dependencies.each { |path| create_file_task(path) }

    create_file_task(output.fullpath, dependencies) 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:



165
166
167
168
169
 
# File 'lib/rake-pipeline/filter.rb', line 165

def output_files
  input_files.inject([]) do |array, file|
    array |= [output_wrapper(output_name_generator.call(file.path))]
  end
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:



147
148
149
150
151
152
153
154
155
156
157
158
 
# File 'lib/rake-pipeline/filter.rb', line 147

def outputs
  hash = {}

  input_files.each do |file|
    output = output_wrapper(output_name_generator.call(file.path))

    hash[output] ||= []
    hash[output] << file
  end

  hash
end