patch-asset_library 0.5.0.1

data/README.rdoc

@@ -0,0 +1,220 @@
+= asset_library
+
+Bundles your JavaScript and CSS, so your development environment is simple to
+code and your production environment is as fast as possible.
+
+== Installation
+
+First, install the gem:
+
+  sudo gem install alegscogs-asset_library --source http://gems.github.com
+
+Next, add the gem into your Rails project's config/environment.rb:
+
+  config.gem 'alegscogs-asset_library', :lib => 'asset_library', :source => 'http://gems.github.com'
+
+Finally, include the Rake tasks in your project:
+
+  echo "begin; require 'asset_library/rake_tasks'; rescue LoadError; end" > lib/tasks/asset_library.rake
+
+== Usage
+
+In your Rails project, edit <tt>config/asset_library.yml</tt> as described
+in the following section.
+
+Once configured, asset_library provides two helper methods for your views:
+
+  <%# outputs library.js (production) or its files (development) %>
+  <%= asset_library_javascript_tags(:javascripts) %>
+
+  <%# outputs library.css (production) or its files (development) %>
+  <%= asset_library_stylesheet_tags(:stylesheets) %>
+
+  <%# outputs library.ie6.css (production) or its files (development) %>
+  <!--[if lte IE 6]>
+    <%= asset_library_stylesheet_tags(:stylesheets, :ie6) %>
+  <![endif]-->
+
+Both helpers behave differently depending on whether
+<tt>ActionController::Base.perform_caching</tt> is true (that is, whether you
+are in <tt>development</tt> environment or not). When caching is disabled, each
+file in the module will be included. (Internet Explorer only allows 30
+<tt>style</tt> and <tt>link</tt> stylesheet tags; in development mode,
+<tt>import</tt> rules are used to work around the bug.) When caching is
+enabled, a single tag is output.
+
+When caching is enabled, the modules to include must be generated using:
+
+  rake asset_library:write
+
+These moduels can be removed using:
+
+  rake asset_library:clean
+
+A cached module is simply the concatenation of its constituent files.
+
+== Configuration
+
+A typical configuration (Yaml) file might look like this. In Rails, this
+should be in <tt>config/asset_library.yml</tt>.
+
+  modules:
+    javascripts:
+      cache: library
+      optional_suffix: compressed
+      base: javascripts
+      suffix: js
+      files:
+        - vendor/jquery
+
+        # jQuery UI parts we need
+        - vendor/jquery-ui/ui.core
+        - vendor/jquery-ui/ui.draggable
+        - vendor/jquery-ui/ui.droppable
+        - vendor/jquery-ui/ui.sortable
+        - vendor/jquery-ui/effects.core
+
+        - lib
+        - plugins/*
+        - application
+        - initializers/*
+
+    tiny_mce_javascripts:
+      # TinyMCE doesn't give us a choice on cache name
+      cache: vendor/tiny_mce/tiny_mce_gzip
+      optional_suffix: compressed
+      base: javascripts
+      suffix: js
+      files:
+        - vendor/tiny_mce/tiny_mce
+        # ... it's possible to bundle all of TinyMCE together with a bit of magic
+
+    stylesheets:
+      cache: library
+      base: stylesheets
+      suffix: css
+      formats:
+        - ie6: [null, ie8, ie7, ie6]
+        - ie7: [null, ie8, ie7]
+        - ie8: [null, ie8]
+      files:
+        - reset
+        - application
+        - layout
+        - views/**/*
+
+  # in general...
+  # modules:
+  #   module_name:
+  #     cache: cache_file
+  #     base: base_path_of_assets_in_web_root
+  #     suffix: suffix ("css" or "js")
+  #     formats:
+  #       format1: ["extra_suffix_1", "extra_suffix_2"]
+  #       format2: [null, "extra_suffix3"]
+  #     optional_suffix: optional_suffix
+  #     files:
+  #       - file1_relative_to_base
+  #       - file2_relative_to_base
+  #       - ...
+  #   ...
+
+Here are what the various configuration elements mean:
+
+<tt>module_name</tt> is the name of the module. It is passed as the first
+parameter to <tt>asset_library_javascript_tags</tt> or
+<tt>asset_library_stylesheet_tags</tt>.
+
+<tt>cache</tt> is a filename, without suffix, relative to <tt>base</tt>, where
+the module will be bundled when caching is enabled. (Ensure that <tt>files</tt>
+does not include <tt>cache_file</tt>, even with globbing.)
+
+<tt>base</tt> is the base path of the assets in URLs. For instance, in Rails,
+where stylesheets are usually served under <tt>/stylesheets</tt>, <tt>base</tt>
+should be <tt>stylesheets</tt>.
+
+<tt>suffix</tt> is either "js" or "css", depending on whether you are including
+JavaScript or CSS files.
+
+<tt>formats</tt> allows construction of parallel modules. By default, for a
+module named <tt>styles</tt> will use <tt>*.css</tt> (where <tt>*</tt> is
+specified by the <tt>files</tt> option) to generate <tt>styles.css</tt>; but
+filenames of the format <tt>*.suffix.css</tt> will be ignored in that search.
+If a <tt>format</tt> called <tt>format1</tt> is specified as
+<tt>[suffix1, suffix2]</tt>, then <tt>*.suffix1.css</tt> and
+<tt>*.suffix2.css</tt> will be included, but not <tt>*.css</tt>. (To specify
+<tt>*.css</tt>, put <tt>null</tt> in the format list.)
+
+<tt>optional_suffix</tt> will cause asset_library to check for the existence of
+files with <tt>optional_suffix</tt> suffixes, falling back to files without
+<tt>optional_suffix</tt> if necessary. For instance, if you run all your
+JavaScript files through
+{YUI Compressor}[http://developer.yahoo.com/yui/compressor/] and output the
+compressed version of <tt>file1.js</tt> as <tt>file1.compressed.js</tt>, then
+set <tt>optional_suffix</tt> to <tt>compressed</tt>. In your development
+environment, where <tt>compressed</tt> javascripts are missing,
+<tt>file1.js</tt> will be included and you can debug your JavaScript. In your
+production environment, create the <tt>compressed</tt> JavaScripts in the same
+directory, and they will be included instead, for optimal download speed.
+
+<tt>files</tt> is a list of files, relative to <tt>base</tt>. File globbing is
+allowed; <tt>**</tt> expands to "any nesting of directories". Files which do
+not exist will be excluded; globbing will include/exclude files with
+<tt>formats</tt> as appropriate; and files without <tt>optional_suffix</tt>
+will not be output alongside files with the same name endowed with the suffix.
+
+== Compilers
+
+If you would like asset library to do more than just concatenate the
+files to produce your modules, then you need to specify a compiler.
+Asset Library currently ships with support for one compiler: Closure
+Compiler, and has an extendable framework to add more.
+
+To specify that a module is to be compiled with the Closure Compiler,
+use the <tt>compiler</tt> key for that module.  You may pass
+additional flags with the <tt>compiler_flags</tt> option:
+
+    modules:
+      javascripts:
+        cache: library
+        compiler: closure
+        compiler_flags: --warning_level QUIET
+        base: javascripts
+        suffix: js
+        files:
+          - javascripts/**/*
+
+You also need to configure the compiler by using a
+<tt>compilers.closure</tt> key:
+
+    compilers:
+      closure:
+        path: /path/to/closure.jar
+        flags: --warning_level QUIET
+
+The full list of Closure Compiler settings are:
+
+<tt>path</tt>: The path to the Closure Compiler jar.  This is
+mandatory.
+
+<tt>flags</tt>: Flags to pass to Closure Compiler.  These are combined
+with any per-module flags given via the <tt>compiler_flags</tt> option
+in the individual modules.  Default: no flags.
+
+<tt>java</tt>: The java command to use.  This will be searched for in
+the <tt>PATH</tt> unless it is an absolute filename.  Default:
+<tt>java</tt>.
+
+<tt>java_flags</tt>: Flags to pass to the java interpreter.  Default:
+no flags.
+
+== Copyright
+
+I believe in software freedom, not any abomination thereof. This project is
+released under the Public Domain, meaning I relinquish my copyright (to any
+extend the law allows) and grant you all rights to use, modify, sell, or
+otherwise take advantage of my software.
+
+However, I do kindly request that, as a favor, you refrain from using my
+software as part of an evil plan involving velociraptors and mind-controlling
+robots (even though I would not be legally entitled to sue you for doing so). 

data/lib/asset_library.rb

@@ -0,0 +1,121 @@
+begin
+  require 'glob_fu'
+rescue LoadError
+  require 'rubygems'
+  require 'glob_fu'
+end
+
+require 'yaml'
+require File.dirname(__FILE__) + '/asset_library/compiler'
+require File.dirname(__FILE__) + '/asset_library/asset_module'
+require File.dirname(__FILE__) + '/asset_library/util'
+
+class AssetLibrary
+  ConfigurationError = Class.new(RuntimeError)
+
+  class << self
+    def config_path
+      @config_path
+    end
+
+    def config_path=(config_path)
+      @config_path = config_path
+    end
+
+    #
+    # Root of your application.
+    #
+    # Paths of external programs (if required) are resolved relative
+    # to this path.
+    #
+    attr_accessor :app_root
+
+    #
+    # Root directory of your output files.
+    #
+    # Output files are resolved relative to this path.
+    #
+    attr_accessor :root
+
+    def cache
+      return true if @cache.nil?
+      @cache
+    end
+
+    def cache=(cache)
+      reset!
+      @cache = cache
+    end
+
+    def cache_vars
+      # We store cache_vars even if not caching--this is our "globals"
+      @cache_vars ||= {}
+    end
+
+    def config
+      return @config if cache && @config
+      ret = if File.exist?(config_path)
+        yaml = YAML.load_file(config_path) || {}
+        Util::symbolize_hash_keys(yaml)
+      else
+        {}
+      end
+      if !ret[:modules] && ret.values.any?{|value| value.is_a?(Hash) && value[:files]}
+        warn <<-EOS.gsub(/^ *\|/, '')
+          |  WARNING: Your asset library configuration follows a
+          |  deprecated format.  Please move all your asset modules
+          |  under a "modules:" key, as described in the
+          |  documentation.
+        EOS
+        ret = { :modules => ret }
+      end
+      ret[:modules] ||= {}
+      ret[:compilers] ||= {}
+      @config = cache ? ret : nil
+      ret
+    end
+
+    def compilers
+      @compilers ||= {}
+    end
+
+    def asset_module(key)
+      module_config = config[:modules][key.to_sym]
+      if module_config
+        AssetModule.new(key, module_config)
+      end
+    end
+
+    def compiler(asset_module)
+      type = asset_module.compiler_type
+      config = self.config[:compilers][type] || {}
+      compilers[type] ||= Compiler.create(type, config)
+    end
+
+    def write_all_caches
+      config[:modules].keys.each do |key|
+        m = asset_module(key)
+        c = compiler(m)
+        c.add_asset_module(m)
+      end
+
+      compilers.values.each do |compiler|
+        compiler.write_all_caches
+      end
+    end
+
+    def delete_all_caches
+      asset_modules = config[:modules].keys.collect{|k| AssetLibrary.asset_module(k)}
+      asset_modules.each do |m|
+        FileUtils.rm_f(m.cache_asset.absolute_path)
+      end
+    end
+
+    def reset!
+      @config = nil
+      @cache_vars = nil
+      @compilers = nil
+      Compiler.reset!
+    end
+  end
+end

data/lib/asset_library/asset.rb

@@ -0,0 +1,35 @@
+class AssetLibrary
+  class Asset
+    attr_reader(:absolute_path)
+
+    def initialize(absolute_path)
+      @absolute_path = absolute_path
+    end
+
+    def eql?(other)
+      self.class === other && absolute_path == other.absolute_path
+    end
+
+    def hash
+      self.absolute_path.hash
+    end
+
+    def relative_path
+      if AssetLibrary.root == '/'
+        absolute_path
+      else
+        absolute_path[AssetLibrary.root.length..-1]
+      end
+    end
+
+    def timestamp
+      File.mtime(absolute_path)
+    rescue Errno::ENOENT
+      nil
+    end
+
+    def relative_url
+      "#{relative_path}?#{timestamp.to_i.to_s}"
+    end
+  end
+end

data/lib/asset_library/asset_module.rb

@@ -0,0 +1,94 @@
+require File.dirname(__FILE__) + '/asset'
+
+class AssetLibrary
+  class AssetModule
+    attr_reader(:config)
+
+    def initialize(name, config)
+      @name = name.to_s
+      @config = config
+      add_default_format
+    end
+
+    attr_reader :name
+
+    # Returns the type of compiler to use for this asset module.
+    def compiler_type
+      (config[:compiler] || :default).to_sym
+    end
+
+    # Returns the Array of compiler flags to use.
+    def compiler_flags
+      Util.normalize_flags(config[:compiler_flags])
+    end
+
+    # Returns an Array of Assets to include.
+    #
+    # Arguments:
+    #   extra_suffix: if set, finds files with the given extra suffix
+    def assets(format = nil)
+      if format
+        assets_with_format(format)
+      else
+        assets_with_extra_suffix(nil)
+      end
+    end
+
+    # Returns an Array of Assets to include.
+    #
+    # Arguments:
+    #   extra_suffix: if set, finds files with the given extra suffix
+    def assets_with_extra_suffix(extra_suffix)
+      return nil unless config
+
+      GlobFu.find(
+        config[:files],
+        :suffix => config[:suffix],
+        :extra_suffix => extra_suffix,
+        :root => File.join(*([AssetLibrary.root, config[:base]].compact)),
+        :optional_suffix => config[:optional_suffix]
+      ).collect { |f| Asset.new(f) }
+    end
+
+    # Returns an Array of Assets to include.
+    #
+    # Calls assets_with_extra_suffix for each suffix in the given format
+    #
+    # Arguments:
+    #   format: format specified in the config
+    def assets_with_format(format)
+      return nil unless config
+
+      extra_suffixes = config[:formats][format.to_sym]
+      extra_suffixes.inject([]) { |r, s| r.concat(assets_with_extra_suffix(s)) }
+    end
+
+    # Returns an Asset representing the cache file
+    def cache_asset(format = nil)
+      extra = format ? ".#{format}" : ''
+      Asset.new(File.join(AssetLibrary.root, config[:base], "#{config[:cache]}#{extra}.#{config[:suffix]}"))
+    end
+
+    # Return the formats to generate.
+    def formats
+      (config[:formats] || {}).keys.sort_by{|sym| sym.to_s}
+    end
+
+    # Yield each set of input paths with their output path.  All paths
+    # are absolute.
+    def each_compilation
+      formats.each do |format|
+        inputs = assets(format).map { |asset| asset.absolute_path }
+        output = cache_asset(format).absolute_path
+        yield inputs, output
+      end
+    end
+
+    private
+
+    def add_default_format
+      config[:formats] ||= {}
+      config[:formats][nil] = [nil]
+    end
+  end
+end