rake-pipeline 0.5.0

data/lib/rake-pipeline/dsl.rb

@@ -0,0 +1,146 @@
+module Rake
+  class Pipeline
+    # This class exists purely to provide a convenient DSL for
+    # configuring a pipeline.
+    #
+    # All instance methods of {DSL} are available in the context
+    # the block passed to +Rake::Pipeline.+{Pipeline.build}.
+    #
+    # When configuring a pipeline, you *must* provide both a
+    # root, and a series of files using {#input}.
+    class DSL
+      # @return [Pipeline] the pipeline the DSL should configure
+      attr_reader :pipeline
+
+      # Configure a pipeline with a passed in block.
+      #
+      # @param [Pipeline] pipeline the pipeline that the DSL
+      #   should configure.
+      # @param [Proc] block the block describing the
+      #   configuration. This block will be evaluated in
+      #   the context of a new instance of {DSL}
+      # @return [void]
+      def self.evaluate(pipeline, &block)
+        new(pipeline).instance_eval(&block)
+        copy_filter = Rake::Pipeline::ConcatFilter.new
+        copy_filter.output_name_generator = proc { |input| input }
+        pipeline.add_filter(copy_filter)
+      end
+
+      # Create a new {DSL} to configure a pipeline.
+      #
+      # @param [Pipeline] pipeline the pipeline that the DSL
+      #   should configure.
+      # @return [void]
+      def initialize(pipeline)
+        @pipeline = pipeline
+      end
+
+      # Define the input location and files for the pipeline.
+      #
+      # @example
+      #   !!!ruby
+      #   Rake::Pipeline.build do
+      #     input "app/assets", "**/*.js"
+      #     # ...
+      #   end
+      #
+      # @param [String] root the root path where the pipeline
+      #   should find its input files.
+      # @param [String] glob a file pattern that represents
+      #   the list of all files that the pipeline should
+      #   process. The default is +"**/*"+.
+      # @return [void]
+      def input(root, glob="**/*")
+        pipeline.input_root = root
+        pipeline.input_glob = glob
+      end
+
+      # Add a filter to the pipeline.
+      #
+      # In addition to a filter class, {#filter} takes a
+      # block that describes how the filter should map
+      # input files to output files.
+      #
+      # By default, the block maps an input file into
+      # an output file with the same name.
+      #
+      # Any additional arguments passed to {#filter} will
+      # be passed on to the filter class's constructor.
+      #
+      # @see Filter#outputs Filter#output (for an example
+      #   of how a list of input files gets mapped to
+      #   its outputs)
+      #
+      # @param [Class] filter_class the class of the filter.
+      # @param [Array] ctor_args a list of arguments to pass
+      #   to the filter's constructor.
+      # @param [Proc] block an output file name generator.
+      # @return [void]
+      def filter(filter_class, *ctor_args, &block)
+        filter = filter_class.new(*ctor_args, &block)
+        pipeline.add_filter(filter)
+      end
+
+      # Apply a number of filters, but only to files matching
+      # a particular pattern.
+      #
+      # Inside the block passed to {#match match}, you may
+      # specify any number of filters that should be applied
+      # to files matching the pattern.
+      #
+      # @param [String] pattern a glob pattern to match
+      # @param [Proc] block a block that supplies filters
+      # @return [Matcher]
+      #
+      # @example
+      #   !!!ruby
+      #   Pipeline.build do
+      #     input "app/assets"
+      #     output "public"
+      #
+      #     # compile coffee files into JS files
+      #     match "*.coffee" do
+      #       filter CompileCoffee do |input|
+      #         input.sub(/coffee$/, "js")
+      #       end
+      #     end
+      #
+      #     # because the previous step converted coffeee
+      #     # into JS, the coffee files will be included here
+      #     match "*.js" do
+      #       filter MinifyFilter
+      #       filter Rake::Pipeline::ConcatFilter, "application.js"
+      #     end
+      #   end
+      def match(pattern, &block)
+        matcher = pipeline.copy(Matcher, &block)
+        matcher.glob = pattern
+        pipeline.add_filter matcher
+        matcher
+      end
+
+      # Specify the output directory for the pipeline.
+      #
+      # @param [String] root the output directory.
+      # @return [void]
+      def output(root)
+        pipeline.output_root = root
+      end
+
+      # Specify the location of the temporary directory.
+      # Filters will store intermediate build artifacts
+      # here.
+      #
+      # This defaults "tmp" in the current working directory.
+      #
+      # @param [String] root the temporary directory
+      # @return [void]
+      def tmpdir(root)
+        pipeline.tmpdir = root
+      end
+    end
+  end
+end
+
+

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,173 @@
+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 =~ /^\//
+        File.join(root, path)
+      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
+
+        if "".respond_to?(:encode) && !contents.valid_encoding?
+          raise EncodingError, "The file at the path #{fullpath} is not valid UTF-8. Please save it again as UTF-8."
+        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,209 @@
+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.
+      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
+
+      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
+      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 = output_wrapper(output_name_generator.call(file.path))
+
+          hash[output] ||= []
+          hash[output] << file
+        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.inject([]) do |array, file|
+          array |= [output_wrapper(output_name_generator.call(file.path))]
+        end
+      end
+
+      # The Rake::Application that the filter should define new tasks on.
+      #
+      # @return [Rake::Application]
+      def rake_application
+        @rake_application || Rake.application
+      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|
+          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
+
+    private
+      # @attr_reader
+      def encoding
+        "UTF-8"
+      end
+
+      def create_file_task(output, deps=[], &block)
+        rake_application.define_task(Rake::FileTask, output => deps, &block)
+      end
+
+      def output_wrapper(file)
+        file_wrapper_class.new(output_root, file, encoding)
+      end
+    end
+  end
+end