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:



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

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.



96
97
98
 
# File 'lib/rake-pipeline/filter.rb', line 96

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. 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) 


179
180
181
 
# File 'lib/rake-pipeline/filter.rb', line 179

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.



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

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



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

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:



193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
 
# File 'lib/rake-pipeline/filter.rb', line 193

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:



172
173
174
 
# File 'lib/rake-pipeline/filter.rb', line 172

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:



154
155
156
157
158
159
160
161
162
163
164
165
 
# File 'lib/rake-pipeline/filter.rb', line 154

def outputs
  hash = {}

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

  hash
end