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

- (Filter) initialize(file_wrapper_class = FileWrapper)

Returns a new instance of Filter



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

def initialize(file_wrapper_class=FileWrapper)
  @file_wrapper_class = file_wrapper_class
end

Instance Attribute Details

- (Object) file_wrapper_class=(value) (writeonly)

Sets the attribute file_wrapper_class

Parameters:

  • value

    the value to set the attribute file_wrapper_class to.



69
70
71
# File 'lib/rake-pipeline/filter.rb', line 69

def file_wrapper_class=(value)
  @file_wrapper_class = value
end

- (Array<FileWrapper>) input_files

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

- (Proc) output_name_generator

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

- (String) output_root

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)


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

def rake_application
  @rake_application || Rake.application
end

- (Array<Rake::Task>) rake_tasks (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

+ (void) processes_binary_files

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.



76
77
78
# File 'lib/rake-pipeline/filter.rb', line 76

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

Instance Method Details

- (void) generate_rake_tasks

This method returns an undefined value.

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



173
174
175
176
177
178
179
180
181
182
183
# File 'lib/rake-pipeline/filter.rb', line 173

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

- (Array<FileWrapper>) output_files

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:



156
157
158
159
160
# File 'lib/rake-pipeline/filter.rb', line 156

def output_files
  input_files.inject([]) do |array, file|
    array |= [output_wrapper(output_name_generator.call(file.path))]
  end
end

- (Hash{FileWrapper => Array<FileWrapper>}) outputs

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:



138
139
140
141
142
143
144
145
146
147
148
149
# File 'lib/rake-pipeline/filter.rb', line 138

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