juicer 0.2.6 → 1.0.0

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/bin/juicer

@@ -1,8 +1,6 @@
 #!/usr/bin/env ruby
 require "rubygems"
-dir = File.dirname(File.symlink?(__FILE__) ? File.readlink(__FILE__) : __FILE__)
-base = File.expand_path(File.join(dir, %w[.. lib juicer]))
-require base
-require File.join(base, "cli")
+require "juicer"
+require "juicer/cli"
 
 Juicer::Cli.run(ARGV)

data/lib/juicer.rb

@@ -3,7 +3,7 @@ require "logger"
 module Juicer
 
   # :stopdoc:
-  VERSION = '0.2.6'
+  VERSION = '1.0.0'
   LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
   PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
   LOGGER = Logger.new(STDOUT)
@@ -51,20 +51,19 @@ module Juicer
   end
 
   # Utility method used to require all files ending in .rb that lie in the
-  # directory below this file that has the same name as the filename passed
-  # in. Optionally, a specific _directory_ name can be passed in such that
-  # the _filename_ does not have to be equivalent to the directory.
-  #
-  def self.require_all_libs_relative_to( fname, dir = nil )
-    dir ||= ::File.basename(fname, '.*')
-    search_me = ::File.expand_path(::File.join(::File.dirname(fname), dir, '**', '*.rb'))
+  # directory below this file.
+  def self.require_all_libs
+    dir  = File.dirname(File.expand_path(__FILE__))
+    glob = File.join(dir, "juicer", '**', '*.rb')
 
-    Dir.glob(search_me).sort.each { |rb| require rb }
+    # Unexpand paths (avoids requiring the same file twice)
+    paths = Dir.glob(glob).map { |path| path.sub("#{dir}/", '').sub(/\.rb$/, "") }
+    paths.each { |rb| require rb }
   end
 
 end
 
-Juicer.require_all_libs_relative_to(__FILE__)
+Juicer.require_all_libs
 
 class FileNotFoundError < Exception
 end

data/lib/juicer/asset/path.rb

@@ -0,0 +1,275 @@
+# -*- coding: utf-8 -*-
+
+require "pathname"
+require "juicer/cache_buster"
+
+module Juicer
+  module Asset
+    #
+    # Assets are files used by CSS and JavaScript files. The Asset class provides
+    # tools for manipulating asset paths, such as rebasing, adding cache busters,
+    # and cycling asset hosts.
+    #
+    # Asset::Path objects are most commonly created by <tt>Juicer::Asset::PathResolver#resolve</tt>
+    # which resolves include paths to file names. It is possible, however, to use
+    # the asset class directly:
+    #
+    #   Dir.pwd
+    #   #=> "/home/christian/projects/mysite/design/css"
+    #   
+    #   asset = Juicer::Asset::Path.new "../images/logo.png"
+    #   asset.path
+    #   #=> "../images/logo.png"
+    #   
+    #   asset.rebase("~/projects/mysite/design").path
+    #   #=> "images/logo.png"
+    #   
+    #   asset.filename
+    #   #=> "/home/christian/projects/mysite/design/images/logo.png"
+    #   
+    #   asset.path(:cache_buster_type => :soft)
+    #   #=> "../images/logo.png?jcb=1234567890"
+    #   
+    #   asset.path(:cache_buster_type => :soft, :cache_buster => nil)
+    #   #=> "../images/logo.png?1234567890"
+    #   
+    #   asset.path(:cache_buster => "bustIT")
+    #   #=> "../images/logo.png?bustIT=1234567890"
+    #   
+    #   asset = Juicer::Asset::Path.new "../images/logo.png", :document_root
+    #   #=> "/home/christian/projects/mysite"
+    #   
+    #   asset.absolute_path(:cache_buster_type => :hard)
+    #   #=> "/images/logo-jcb1234567890.png"
+    #   
+    #   asset.absolute_path(:host => "http://localhost")
+    #   #=> "http://localhost/images/logo.png"
+    #   
+    #   asset.absolute_path(:host => "http://localhost", :cache_buster_type => :hard)
+    #   #=> "http://localhost/images/logo-jcb1234567890.png"
+    #
+    #
+    # Author::    Christian Johansen (christian@cjohansen.no)
+    # Copyright:: Copyright (c) 2009 Christian Johansen
+    # License::   BSD
+    #
+    class Path
+      # Base directory to resolve relative path from, see Juicer::Asset::Path#initialize
+      attr_reader :base
+
+      # Hosts served from <tt>:document_root</tt>, see Juicer::Asset::Path#initialize
+      attr_reader :hosts
+
+      # Directory served as root through a web server, see Juicer::Asset::Path#initialize
+      attr_reader :document_root
+
+      @@scheme_pattern = %r{^[a-zA-Z]{3,5}://}
+
+      #
+      # Initialize asset at <tt>path</tt>. Accepts an optional hash of options:
+      #
+      # [<tt>:base</tt>]
+      #     Base context from which asset is required. Given a <tt>path</tt> of
+      #     <tt>../images/logo.png</tt> and a <tt>:base</tt> of <tt>/project/design/css</tt>,
+      #     the asset file will be assumed to live in <tt>/project/design/images/logo.png</tt>
+      #     Defaults to the current directory.
+      # [<tt>:hosts</tt>]
+      #     Array of host names that are served from <tt>:document_root</tt>. May also
+      #     include scheme/protocol. If not, http is assumed.
+      # [<tt>:document_root</tt>]
+      #     The root directory for absolute URLs (ie, the server's document root). This
+      #     option is needed when resolving absolute URLs that include a hostname as well
+      #     as when generating absolute paths.
+      #
+      def initialize(path, options = {})
+        @path = path
+        @filename = nil
+        @absolute_path = nil
+        @relative_path = nil
+        @path_has_host = @path =~ @@scheme_pattern
+        @path_is_absolute = @path_has_host || @path =~ /^\//
+
+        # Options
+        @base = options[:base] || Dir.pwd
+        @document_root = options[:document_root]
+        @hosts = Juicer::Asset::Path.hosts_with_scheme(options[:hosts])
+      end
+
+      #
+      # Returns absolute path calculated using the <tt>#document_root</tt>.
+      # Optionally accepts a hash of options:
+      #
+      # [<tt>:host</tt>] Return fully qualified URL with this host name. May include
+      #                  scheme/protocol. Default scheme is http.
+      # [<tt>:cache_buster</tt>] The parameter name for the cache buster.
+      # [<tt>:cache_buster_type</tt>] The kind of cache buster to add, <tt>:soft</tt>
+      #                               or <tt>:hard</tt>.
+      #
+      # A cache buster will be added if either (or both) of the <tt>:cache_buster</tt>
+      # or <tt>:cache_buster_type</tt> options are provided. The default cache buster
+      # type is <tt>:soft</tt>.
+      #
+      # Raises an ArgumentException if no <tt>document_root</tt> has been set.
+      #
+      def absolute_path(options = {})
+        if !@absolute_path
+          # Pre-conditions
+          raise ArgumentError.new("No document root set") if @document_root.nil?
+
+          @absolute_path = filename.sub(%r{^#@document_root}, '').sub(/^\/?/, '/')
+          @absolute_path = "#{Juicer::Asset::Path.host_with_scheme(options[:host])}#@absolute_path"
+        end
+
+        path_with_cache_buster(@absolute_path, options)
+      end
+
+      #
+      # Return path relative to <tt>#base</tt>
+      #
+      # Accepts an optional hash of options for cache busters:
+      #
+      # [<tt>:cache_buster</tt>] The parameter name for the cache buster.
+      # [<tt>:cache_buster_type</tt>] The kind of cache buster to add, <tt>:soft</tt>
+      #                               or <tt>:hard</tt>.
+      #
+      # A cache buster will be added if either (or both) of the <tt>:cache_buster</tt>
+      # or <tt>:cache_buster_type</tt> options are provided. The default cache buster
+      # type is <tt>:soft</tt>.
+      #
+      def relative_path(options = {})
+        @relative_path ||= Pathname.new(filename).relative_path_from(Pathname.new(base)).to_s
+        path_with_cache_buster(@relative_path, options)
+      end
+
+      #
+      # Returns the original path.
+      #
+      # Accepts an optional hash of options for cache busters:
+      #
+      # [<tt>:cache_buster</tt>] The parameter name for the cache buster.
+      # [<tt>:cache_buster_type</tt>] The kind of cache buster to add, <tt>:soft</tt>
+      #                               or <tt>:hard</tt>.
+      #
+      # A cache buster will be added if either (or both) of the <tt>:cache_buster</tt>
+      # or <tt>:cache_buster_type</tt> options are provided. The default cache buster
+      # type is <tt>:soft</tt>.
+      #
+      def path(options = {})
+        path_with_cache_buster(@path, options)
+      end
+
+      #
+      # Return filename on disk. Requires the <tt>#document_root</tt> to be set if
+      # original path was an absolute one.
+      #
+      # If asset path includes scheme/protocol and host, it can only be resolved if
+      # a match is found in <tt>#hosts</tt>. Otherwise, an exeception is raised.
+      #
+      def filename
+        return @filename if @filename
+
+        # Pre-conditions
+        raise ArgumentError.new("No document root set") if @path_is_absolute && @document_root.nil?
+        raise ArgumentError.new("No hosts served from document root") if @path_has_host && @hosts.empty?
+
+        path = strip_host(@path)
+        raise ArgumentError.new("No matching host found for #{@path}") if path =~ @@scheme_pattern
+
+        dir = @path_is_absolute ? document_root : base
+        @filename = File.expand_path(File.join(dir, path))
+      end
+
+      #
+      # Rebase path and return a new Asset::Path object.
+      #
+      #   asset = Juicer::Asset::Path.new "../images/logo.png", :base => "/var/www/public/stylesheets"
+      #   asset2 = asset.rebase("/var/www/public")
+      #   asset2.relative_path #=> "images/logo.png"
+      #
+      def rebase(base_path)
+        path = Pathname.new(filename).relative_path_from(Pathname.new(base_path)).to_s
+
+        Juicer::Asset::Path.new(path,
+                                :base => base_path,
+                                :hosts => hosts,
+                                :document_root => document_root)
+      end
+
+      #
+      # Returns basename of filename on disk
+      #
+      def basename
+        File.basename(filename)
+      end
+
+      #
+      # Returns basename of filename on disk
+      #
+      def dirname
+        File.dirname(filename)
+      end
+
+      #
+      # Returns <tt>true</tt> if file exists on disk
+      #
+      def exists?
+        File.exists?(filename)
+      end
+
+      #
+      # Accepts a single host, or an array of hosts and returns an array of hosts
+      # that include scheme/protocol, and don't have trailing slash.
+      #
+      def self.hosts_with_scheme(hosts)
+        hosts.nil? ? [] : [hosts].flatten.collect { |host| self.host_with_scheme(host) }
+      end
+
+      #
+      # Assures that a host has scheme/protocol and no trailing slash
+      #
+      def self.host_with_scheme(host)
+        return host if host.nil?
+        (host !~ @@scheme_pattern ? "http://#{host}" : host).sub(/\/$/, '')
+      end
+
+      def <=>(other)
+        filename <=> other.filename
+      end
+
+      private
+      #
+      # Adds cache buster to paths if :cache_buster_type and :cache_buster indicates
+      # they should be added.
+      #
+      def path_with_cache_buster(path, options = {})
+        return path if !options.key?(:cache_buster) && options[:cache_buster_type].nil?
+
+        buster_path = nil
+        type = options[:cache_buster_type] || :soft
+
+        if options.key?(:cache_buster)
+          # Pass :cache_buster even if it's nil
+          buster_path = Juicer::CacheBuster.send(type, filename, options[:cache_buster])
+        else
+          # If :cache_buster wasn't specified, rely on default value
+          buster_path = Juicer::CacheBuster.send(type, filename)
+        end
+
+        path.sub(File.basename(path), File.basename(buster_path))
+      end
+
+      #
+      # Strip known hosts from path
+      #
+      def strip_host(path)
+        hosts.each do |host|
+          return path if path !~ @@scheme_pattern
+
+          path.sub!(%r{^#{host}}, '')
+        end
+
+        return path
+      end
+    end
+  end
+end

data/lib/juicer/asset/path_resolver.rb

@@ -0,0 +1,79 @@
+# -*- coding: utf-8 -*-
+
+require "juicer/asset/path"
+
+module Juicer
+  module Asset
+    #
+    # Factory class that creates <tt>Juicer::Asset::Path</tt> objects from a common set of
+    # options. Also facilitates asset host cycling on a set of asset paths.
+    #
+    #   path_resolver = Juicer::Asset::PathResolver.new(
+    #                     :document_root => "/var/www",
+    #                     :hosts => ["assets1.mysite.com", "assets2.mysite.com"]
+    #                   )
+    #
+    #   asset = path_resolver.resolve("../images/logo.png")
+    #   asset.document_root
+    #   #=> "/var/www"
+    #   
+    #   asset.absolute_path(path_resolver.cycle_hosts)
+    #   #=> "http://assets1.mysite.com/images/logo.png"
+    #   
+    #   asset = path_resolver.resolve("/favicon.ico")
+    #   asset.absolute_path(path_resolver.cycle_hosts)
+    #   #=> "http://assets2.mysite.com/favicon.ico"
+    #
+    # Author::    Christian Johansen (christian@cjohansen.no)
+    # Copyright:: Copyright (c) 2009 Christian Johansen
+    # License::   BSD
+    #
+    class PathResolver
+      attr_reader :hosts, :document_root, :base
+
+      #
+      # Initialize resolver. All options set on the resolver will be carried on to the
+      # resolved assets.
+      #
+      def initialize(options = {})
+        options[:base] ||= Dir.pwd
+        @options = options
+        @base = options[:base]
+        @hosts = Juicer::Asset::Path.hosts_with_scheme(options[:hosts]) || []
+        @current_host = 0
+        @document_root = @options[:document_root]
+      end
+
+      #
+      # Returns a <tt>Juicer::Asset::Path</tt> object for the given path, and the options
+      # set on the resolver.
+      #
+      def resolve(path)
+        Juicer::Asset::Path.new(path, @options)
+      end
+
+      #
+      # Set new base directory. Will affect any assets resolved from here, but any
+      # assets previously resolved will not be changed
+      #
+      def base=(base)
+        @base = base
+        @options[:base] = base
+      end
+
+      #
+      # Cycle asset hosts. Returns an asset host
+      #
+      def cycle_hosts
+        return nil if @hosts.length == 0
+
+        host = @hosts[@current_host % @hosts.length]
+        @current_host += 1
+
+        host
+      end
+
+      alias host cycle_hosts
+    end
+  end
+end

data/lib/juicer/binary.rb

@@ -1,4 +1,4 @@
-require File.expand_path(File.join(File.dirname(__FILE__), "chainable"))
+require "juicer/chainable"
 
 module Juicer
 
@@ -12,12 +12,11 @@ module Juicer
   # allowed to set on the binary.
   #
   module Binary
-
     # Initialize binary with options
     # options = Hash of options, optional
     #
     def initialize(binary, options = {})
-      @options = self.respond_to?(:defualt_options) ? default_options.merge(options) : options
+      @options = self.respond_to?(:default_options) ? default_options.merge(options) : options
       @opt_set = false
       @command = nil
       @binary = binary
@@ -31,7 +30,6 @@ module Juicer
     # Run command
     #
     def execute(params = nil)
-      #puts "#{self.command} #{params}"
       cmd = IO.popen("#{self.command} #{params}", "r")
       results = cmd.gets(nil)
       cmd.close
@@ -131,7 +129,7 @@ module Juicer
     #
     def locate(bin_glob, env = nil)
       path << ENV[env] if env && ENV.key?(env) && File.exist?(ENV[env])
-
+      
       (path << Dir.pwd).each do |path|
         files = Dir.glob(File.expand_path(File.join(path, bin_glob)))
         return files unless files.empty?

data/lib/juicer/cache_buster.rb

@@ -1,45 +1,130 @@
+# -*- coding: utf-8 -*-
+
 module Juicer
   #
-  # Tool that assists in creating filenames that update everytime the file
-  # contents change. There's two ways of generating filenames, soft and hard.
-  # The point of all this is to facilitate configuring web servers to send
-  # static assets with a far future expires header - improving end user
-  # performance through caching.
+  # Assists in creating filenames that reflect the last change to the file. These
+  # kinds of filenames are useful when serving static content through a web server.
+  # If the filename changes everytime the file is modified, you can safely configure
+  # the web server to cache files indefinately, and know that the updated filename
+  # will cause the file to be downloaded again - only once - when it has changed.
+  #
+  # = Types of cache busters
   #
-  # Soft cache busters require no web server configuration, but will not work
-  # as intended with older default configurations for popular proxy server
-  # Squid. The soft busters use query parameters to create unique file names,
-  # and these may not force an update in some cases. The soft cache busters
-  # transforms /images/logo.png to /images/logo.png?cb=1232923789
+  # == Query string / "soft" cache busters
+  # Soft cache busters require no web server configuration. However, it is not
+  # guaranteed to work in all settings. For example, older default
+  # configurations for popular proxy server Squid does not consider a known URL
+  # with a new query string a new URL, and thus will not download the file over.
   #
+  # The soft cache busters transforms
+  # <tt>/images/logo.png</tt> to <tt>/images/logo.png?cb=1232923789</tt>
+  #
+  # == Filename change / "hard" cache busters
   # Hard cache busters change the file name itself, and thus requires either
   # the web server to (internally) rewrite requests for these files to the
   # original ones, or the file names to actually change. Hard cache busters
-  # transforms /images/logo.png to /images/logo-1232923789.png
+  # transforms <tt>/images/logo.png</tt> to <tt>/images/logo-1232923789.png</tt>
+  #
+  # Hard cache busters are guaranteed to work, and is the recommended variant.
+  # An example configuration for the Apache web server that does not require
+  # you to actually change the filenames can be seen below.
+  #
+  #   <VirtualHost *>
+  #       # Application/website configuration
+  #
+  #       # Cache static resources for a year
+  #       <FilesMatch "\.(ico|pdf|flv|jpg|jpeg|png|gif|js|css|swf)$">
+  #           ExpiresActive On
+  #           ExpiresDefault "access plus 1 year"
+  #       </FilesMatch>
+  #
+  #       # Rewrite URLs like /images/logo-cb1234567890.png to /images/logo.png
+  #       RewriteEngine On
+  #       RewriteRule (.*)-cb\d+\.(.*)$ $1.$2 [L]
+  #   </VirtualHost>])
+  #
+  # = Consecutive calls
+  #
+  # Consecutive calls to add a cache buster to a path will replace the existing
+  # cache buster *as long as the parameter name is the same*. Consider this:
+  #
+  #   file = Juicer::CacheBuster.hard("/home/file.png") #=> "/home/file-cb1234567890.png"
+  #   Juicer::CacheBuster.hard(file)                    #=> "/home/file-cb1234567891.png"
+  #
+  #   # Changing the parameter name breaks this
+  #   Juicer::CacheBuster.hard(file, :juicer)           #=> "/home/file-cb1234567891-juicer1234567892.png"
+  #
+  # Avoid this type of trouble simply be cleaning the URL with the old name first:
+  #
+  #   Juicer::CacheBuster.clean(file)                   #=> "/home/file.png"
+  #   file = Juicer::CacheBuster.hard(file, :juicer)    #=> "/home/file-juicer1234567892.png"
+  #   Juicer::CacheBuster.clean(file, :juicer)          #=> "/home/file.png"
+  #
+  # Author::    Christian Johansen (christian@cjohansen.no)
+  # Copyright:: Copyright (c) 2009 Christian Johansen
+  # License::   BSD
   #
   module CacheBuster
+    DEFAULT_PARAMETER = "jcb"
+
     #
     # Creates a unique file name for every revision to the files contents.
-    # Default parameter name for soft cache busters is cb (ie ?cb=<timestamp>)
-    # while default parameter names for hard cache busters is none (ie
-    # file-<timestamp>.png).
+    # Raises an <tt>ArgumentError</tt> if the file can not be found.
+    #
+    # The type indicates which type of cache buster you want, <tt>:soft</tt>
+    # or <tt>:hard</tt>. Default is <tt>:soft</tt>. If an unsupported value
+    # is specified, <tt>:soft</tt> will be used.
     #
-    def self.path(file, type = :soft, param = :undef)
-      param = (type == :soft ? "jcb" : nil) if param == :undef
-      f = File.new(file.split("?").first)
-      mtime = f.mtime.to_i
-      f.close
+    # See <tt>#hard</tt> and <tt>#soft</tt> for explanation of the parameter
+    # argument.
+    #
+    def self.path(file, type = :soft, parameter = DEFAULT_PARAMETER)
+      file = self.clean(file, parameter)
+      filename = file.split("?").first
+      raise ArgumentError.new("#{file} could not be found") unless File.exists?(filename)
+      mtime = File.mtime(filename).to_i
+      type = [:soft, :hard].include?(type) ? type : :soft
 
       if type == :soft
-        param = "#{param}".length == 0 ? "" : "#{param}="
-        file = file.sub(/#{param}\d+/, "").sub(/(\?|\&)$/, "")
-        "#{file}#{file.index('?') ? '&' : '?'}#{param}#{mtime}"
-      else
-        parts = file.split(".")
-        suffix = parts.pop
-        file = parts.join.sub(/-#{param}\d+/, "")
-        "#{parts.join('.')}-#{param}#{mtime}.#{suffix}"
+        parameter = "#{parameter}=".sub(/^=$/, '')
+        return "#{file}#{file.index('?') ? '&' : '?'}#{parameter}#{mtime}"
       end
+
+      file.sub(/(\.[^\.]+$)/, "-#{parameter}#{mtime}" + '\1')
+    end
+
+    #
+    # Add a hard cache buster to a filename. The parameter is an optional prefix
+    # that is added before the mtime timestamp. It results in filenames of the form:
+    # <tt>file-[parameter name][timestamp].suffix</tt>, ie
+    # <tt>images/logo-cb1234567890.png</tt> which is the case for the default
+    # parameter name "cb" (as in *c*ache *b*uster).
+    #
+    def self.hard(file, parameter = DEFAULT_PARAMETER)
+      self.path(file, :hard, parameter)
+    end
+
+    #
+    # Add a soft cache buster to a filename. The parameter is an optional name
+    # for the mtime timestamp value. It results in filenames of the form:
+    # <tt>file.suffix?[parameter name]=[timestamp]</tt>, ie
+    # <tt>images/logo.png?cb=1234567890</tt> which is the case for the default
+    # parameter name "cb" (as in *c*ache *b*uster).
+    #
+    def self.soft(file, parameter = DEFAULT_PARAMETER)
+      self.path(file, :soft, parameter)
+    end
+
+    #
+    # Remove cache buster from a URL for a given parameter name. Parameter name is
+    # "cb" by default.
+    #
+    def self.clean(file, parameter = DEFAULT_PARAMETER)
+      query_param = "#{parameter}".length == 0 ? "" : "#{parameter}="
+      new_file = file.sub(/#{query_param}\d+&?/, "").sub(/(\?|&)$/, "")
+      return new_file unless new_file == file
+
+      file.sub(/-#{parameter}\d+(\.\w+)($|\?)/, '\1\2')
     end
   end
 end