rake-pipeline-fork 0.8.0

data/lib/rake-pipeline/error.rb

@@ -0,0 +1,17 @@
+module Rake
+  class Pipeline
+    # The general Rake::Pipeline error class
+    class Error < ::StandardError
+    end
+
+    # The error that Rake::Pipeline uses when it detects
+    # that a file uses an improper encoding.
+    class EncodingError < Error
+    end
+
+    # The error that Rake::Pipeline uses if you try to
+    # write to a FileWrapper before creating it.
+    class UnopenedFile < Error
+    end
+  end
+end

data/lib/rake-pipeline/file_wrapper.rb

@@ -0,0 +1,182 @@
+module Rake
+  class Pipeline
+    # This class wraps a file for consumption inside of filters. It is
+    # initialized with a root and path, and filters usually use the
+    # {#read} and {#write} methods to work with these files.
+    #
+    # The {#root} and +path+ parameters are provided by the {Filter}
+    # class' internal implementation. Individual filters do not need
+    # to worry about them.
+    #
+    # The root of a {FileWrapper} is always an absolute path.
+    class FileWrapper
+      # @return [String] an absolute path representing this {FileWrapper}'s
+      #   root directory.
+      attr_accessor :root
+
+      # @return [String] the path to the file represented by the {FileWrapper},
+      #   relative to its {#root}.
+      attr_accessor :path
+
+      # @return [String] the encoding that the file represented by this
+      #   {FileWrapper} is encoded in. Filters set the {#encoding} to
+      #   +BINARY+ if they are declared as processing binary data.
+      attr_accessor :encoding
+
+      # Create a new {FileWrapper}, passing in optional root, path, and
+      # encoding. Any of the parameters can be ommitted and supplied later.
+      #
+      # @return [void]
+      def initialize(root=nil, path=nil, encoding="UTF-8")
+        @root, @path, @encoding = root, path, encoding
+        @created_file = nil
+      end
+
+      # Create a new {FileWrapper FileWrapper} with the same root and
+      # path as this {FileWrapper FileWrapper}, but with a specified
+      # encoding.
+      #
+      # @param [String] encoding the encoding for the new object
+      # @return [FileWrapper]
+      def with_encoding(encoding)
+        self.class.new(@root, @path, encoding)
+      end
+
+      # A {FileWrapper} is equal to another {FileWrapper} for hashing purposes
+      # if they have the same {#root} and {#path}
+      #
+      # @param [FileWrapper] other another {FileWrapper} to compare.
+      # @return [true,false]
+      def eql?(other)
+        return false unless other.is_a?(self.class)
+        root == other.root && path == other.path
+      end
+      alias == eql?
+
+      # Similar to {#eql?}, generate a {FileWrapper}'s {#hash} from its {#root}
+      # and {#path}
+      #
+      # @see #eql?
+      # @return [Fixnum] a hash code
+      def hash
+        [root, path].hash
+      end
+
+      # The full path of a FileWrapper is its root joined with its path
+      #
+      # @return [String] the {FileWrapper}'s full path
+      def fullpath
+        raise "#{root}, #{path}" unless root =~ /^(\/|[a-zA-Z]:[\\\/])/
+        File.join(root, path)
+      end
+
+      # Check to see if this file is inside the given directory
+      #
+      # @return [Boolean]
+      def in_directory?(directory)
+        !!(fullpath =~ %r{^#{Regexp.escape(directory)}/})
+      end
+
+      # Make FileWrappers sortable
+      #
+      # @param [FileWrapper] other {FileWrapper FileWrapper}
+      # @return [Fixnum] -1, 0, or 1
+      def <=>(other)
+        [root, path, encoding] <=> [other.root, other.path, other.encoding]
+      end
+
+      # Does the file represented by the {FileWrapper} exist in the file system?
+      #
+      # @return [true,false]
+      def exists?
+        File.exists?(fullpath)
+      end
+
+      # Read the contents of the file represented by the {FileWrapper}.
+      #
+      # Read the file using the {FileWrapper}'s encoding, which will result in
+      # this method returning a +String+ tagged with the {FileWrapper}'s encoding.
+      #
+      # @return [String] the contents of the file
+      # @raise [EncodingError] when the contents of the file are not valid in the
+      #   expected encoding specified in {#encoding}.
+      def read
+        contents = if "".respond_to?(:encode)
+          File.read(fullpath, :encoding => encoding)
+        else
+          File.read(fullpath)
+        end
+
+        # In our unit tests Rubinius returns false when the encoding is BINARY
+        # The encoding type check bypasses the problem and is probably acceptable, but isn't ideal
+        if encoding != "BINARY" && "".respond_to?(:encode) && !contents.valid_encoding?
+          raise EncodingError, "The file at the path #{fullpath} is not valid #{encoding}. Please save it again as #{encoding}."
+        end
+
+        contents
+      end
+
+      # Create a new file at the {FileWrapper}'s {#fullpath}. If the file already
+      # exists, it will be overwritten.
+      #
+      # @api private
+      # @yieldparam [File] file the newly created file
+      # @return [File] if a block was not given
+      def create
+        FileUtils.mkdir_p(File.dirname(fullpath))
+
+        @created_file = if "".respond_to?(:encode)
+          File.open(fullpath, "w:#{encoding}")
+        else
+          File.open(fullpath, "w")
+        end
+
+        if block_given?
+          yield @created_file
+        end
+
+        @created_file
+      ensure
+        if block_given?
+          @created_file.close
+          @created_file = nil
+        end
+      end
+
+      # Close the file represented by the {FileWrapper} if it was previously opened.
+      #
+      # @api private
+      # @return [void]
+      def close
+        raise IOError, "closed stream" unless @created_file
+        @created_file.close
+        @created_file = nil
+      end
+
+      # Check to see whether the file represented by the {FileWrapper} is open.
+      #
+      # @api private
+      # @return [true,false]
+      def closed?
+        @created_file.nil?
+      end
+
+      # Write a String to a previously opened file. This method is called repeatedly
+      # by a {Filter}'s +#generate_output+ method and does not create a brand new
+      # file for each invocation.
+      #
+      # @raise [UnopenedFile] if the file is not already opened.
+      def write(string)
+        raise UnopenedFile unless @created_file
+        @created_file.write(string)
+      end
+
+      # @return [String] A pretty representation of the {FileWrapper}.
+      def inspect
+        "#<FileWrapper root=#{root.inspect} path=#{path.inspect} encoding=#{encoding.inspect}>"
+      end
+
+      alias to_s inspect
+    end
+  end
+end

data/lib/rake-pipeline/filter.rb

@@ -0,0 +1,249 @@
+require "rake"
+
+module Rake
+  class Pipeline
+
+    # 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:
+    #
+    #   !!!ruby
+    #   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 ConcatFilter Rake::Pipeline::ConcatFilter for another
+    #   example filter implementation.
+    #
+    # @abstract
+    class Filter
+      # @return [Array<FileWrapper>] an Array of FileWrappers that
+      #   represent the inputs of this filter. The Pipeline will
+      #   usually set this up.
+      attr_accessor :input_files
+
+      # @return [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.
+      attr_accessor :output_name_generator
+
+      # @return [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.
+      attr_accessor :output_root
+
+      # @return [Array<Rake::Task>] an Array of Rake tasks created
+      #   for this filter. Each unique output file will get a
+      #   single task.
+      attr_reader :rake_tasks
+
+      # @return [Rake::Application] the Rake::Application that the
+      #   filter should define new rake tasks on.
+      attr_writer :rake_application
+
+      # @return [Rake::Pipeline] the Rake::Pipeline that contains
+      #   this filter.
+      attr_accessor :pipeline
+
+      attr_writer :manifest, :last_manifest
+
+      attr_writer :file_wrapper_class
+
+      # @param [Proc] block a block to use as the Filter's
+      #   {#output_name_generator}.
+      def initialize(&block)
+        block ||= proc { |input| input }
+        @output_name_generator = block
+        @input_files = []
+      end
+
+      # @return [Rake::Pipeline::Manifest] the manifest passed
+      # to generated rake tasks. Use the pipeline's manifest
+      # if this is not set
+      def manifest
+        @manifest || pipeline.manifest
+      end
+
+      def last_manifest
+        @last_manifest || pipeline.last_manifest
+      end
+
+      # 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.
+      #
+      # @return [void]
+      def self.processes_binary_files
+        define_method(:encoding) { "BINARY" }
+      end
+
+      # @return [Class] the class to use as the wrapper for output
+      #   files.
+      def file_wrapper_class
+        @file_wrapper_class ||= FileWrapper
+      end
+
+      # Set the input files to a list of FileWrappers. The filter
+      # will map these into equivalent FileWrappers with the
+      # filter's encoding applied.
+      #
+      # By default, a filter's encoding is +UTF-8+, unless
+      # it calls #processes_binary_files, which changes it to
+      # +BINARY+.
+      #
+      # @param [Array<FileWrapper>] a list of FileWrapper objects
+      def input_files=(files)
+        @input_files = files.map do |file|
+          file.with_encoding(encoding)
+        end
+      end
+
+      # 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}:
+      #
+      #     !!!ruby
+      #     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:
+      #
+      #     !!!ruby
+      #     {
+      #       #<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 {Filter} with the Array of inputs and
+      # the output (all as {FileWrapper}s).
+      #
+      # @return [Hash{FileWrapper => Array<FileWrapper>}]
+      def outputs
+        hash = {}
+
+        input_files.each do |file|
+          output_wrappers(file).each do |output|
+            hash[output] ||= []
+            hash[output] << file
+          end
+        end
+
+        hash
+      end
+
+      # An Array of the {FileWrapper} objects that rerepresent this filter's
+      # output files. It is the same as +outputs.keys+.
+      #
+      # @see #outputs
+      # @return [Array<FileWrapper>]
+      def output_files
+        input_files.map { |file| output_wrappers(file) }.flatten.uniq
+      end
+
+      # The Rake::Application that the filter should define new tasks on.
+      #
+      # @return [Rake::Application]
+      def rake_application
+        @rake_application || Rake.application
+      end
+
+      # @param [FileWrapper] file wrapper to get paths for
+      # @return [Array<String>] array of file paths within additional dependencies
+      def additional_dependencies(input)
+        []
+      end
+
+      # Generate the Rake tasks for the output files of this filter.
+      #
+      # @see #outputs #outputs (for information on how the output files are determined)
+      # @return [void]
+      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
+
+    private
+      # @attr_reader
+      def encoding
+        "UTF-8"
+      end
+
+      def create_file_task(output, deps=[], &block)
+        task = rake_application.define_task(Rake::Pipeline::DynamicFileTask, output => deps, &block)
+        task.manifest = manifest
+        task.last_manifest = last_manifest
+        task
+      end
+
+      def output_wrappers(input)
+        output_paths(input).map do |path|
+          file_wrapper_class.new(output_root, path, encoding)
+        end
+      end
+
+      def output_paths(input)
+        args = [ input.path ]
+        args << input if output_name_generator.arity == 2
+        Array(output_name_generator.call(*args))
+      end
+    end
+  end
+end

data/lib/rake-pipeline/filters.rb

@@ -0,0 +1,4 @@
+require "rake-pipeline/filters/concat_filter"
+require "rake-pipeline/filters/ordering_concat_filter"
+require "rake-pipeline/filters/pipeline_finalizing_filter"
+require "rake-pipeline/filters/gsub_filter"