jammit-core 0.1.0

data/lib/jammit-core/command_line.rb

@@ -0,0 +1,79 @@
+require 'optparse'
+require File.expand_path(File.dirname(__FILE__) + '/../jammit')
+
+module Jammit
+
+  # The @CommandLine@ is able to compress, pre-package, and pre-gzip all the
+  # assets specified in the configuration file, in order to avoid an initial
+  # round of slow requests after a fresh deployment.
+  class CommandLine
+
+    BANNER = <<-EOS
+
+Usage: jammit OPTIONS
+
+Run jammit inside a Rails application to compresses all JS, CSS,
+and JST according to config/assets.yml, saving the packaged
+files and corresponding gzipped versions.
+
+If you're using "embed_assets", and you wish to precompile the
+MHTML stylesheet variants, you must specify the "base-url".
+
+Options:
+    EOS
+
+    # The @Jammit::CommandLine@ runs from the contents of @ARGV@.
+    def initialize
+      parse_options
+      ensure_configuration_file
+      Jammit.load_configuration(@options[:config_path])
+      Jammit.packager.force = @options[:force]
+      Jammit.packager.precache_all(@options[:output_folder], @options[:base_url])
+    end
+
+
+    private
+
+    # Make sure that we have a readable configuration file. The @jammit@
+    # command can't run without one.
+    def ensure_configuration_file
+      config = @options[:config_path]
+      return true if File.exists?(config) && File.readable?(config)
+      puts "Could not find the asset configuration file \"#{config}\""
+      exit(1)
+    end
+
+    # Uses @OptionParser@ to grab the options: *--output*, *--config*, and
+    # *--base-url*...
+    def parse_options
+      @options = {
+        :config_path    => Jammit::DEFAULT_CONFIG_PATH,
+        :output_folder  => nil,
+        :base_url       => nil,
+        :force          => false
+      }
+      @option_parser = OptionParser.new do |opts|
+        opts.on('-o', '--output PATH', 'output folder for packages (default: "public/assets")') do |output_folder|
+          @options[:output_folder] = output_folder
+        end
+        opts.on('-c', '--config PATH', 'path to assets.yml (default: "config/assets.yml")') do |config_path|
+          @options[:config_path] = config_path
+        end
+        opts.on('-u', '--base-url URL', 'base URL for MHTML (ex: "http://example.com")') do |base_url|
+          @options[:base_url] = base_url
+        end
+        opts.on('-f', '--force', 'force a rebuild of all assets') do |force|
+          @options[:force] = force
+        end
+        opts.on_tail('-v', '--version', 'display Jammit version') do
+          puts "Jammit version #{Jammit::VERSION}"
+          exit
+        end
+      end
+      @option_parser.banner = BANNER
+      @option_parser.parse!(ARGV)
+    end
+
+  end
+
+end

data/lib/jammit-core/compressor.rb

@@ -0,0 +1,214 @@
+module Jammit
+
+  # Uses the YUI Compressor or Closure Compiler to compress JavaScript.
+  # Always uses YUI to compress CSS (Which means that Java must be installed.)
+  # Also knows how to create a concatenated JST file.
+  # If "embed_assets" is turned on, creates "mhtml" and "datauri" versions of
+  # all stylesheets, with all enabled assets inlined into the css.
+  class Compressor
+
+    # Mapping from extension to mime-type of all embeddable assets.
+    EMBED_MIME_TYPES = {
+      '.png'  => 'image/png',
+      '.jpg'  => 'image/jpeg',
+      '.jpeg' => 'image/jpeg',
+      '.gif'  => 'image/gif',
+      '.tif'  => 'image/tiff',
+      '.tiff' => 'image/tiff',
+      '.ttf'  => 'font/truetype',
+      '.otf'  => 'font/opentype'
+    }
+
+    # Font extensions for which we allow embedding:
+    EMBED_EXTS      = EMBED_MIME_TYPES.keys
+    EMBED_FONTS     = ['.ttf', '.otf']
+
+    # Maximum size for embeddable images (an IE8 limitation).
+    MAX_IMAGE_SIZE  = 32 * 1024
+
+    # CSS asset-embedding regexes for URL rewriting.
+    EMBED_DETECTOR  = /url\(['"]?([^\s)]+\.[a-z]+)(\?\d+)?['"]?\)/
+    EMBEDDABLE      = /[\A\/]embed\//
+    EMBED_REPLACER  = /url\(__EMBED__([^\s)]+)(\?\d+)?\)/
+
+    # MHTML file constants.
+    MHTML_START     = "/*\r\nContent-Type: multipart/related; boundary=\"JAMMIT_MHTML_SEPARATOR\"\r\n\r\n"
+    MHTML_SEPARATOR = "--JAMMIT_MHTML_SEPARATOR\r\n"
+    MHTML_END       = "*/\r\n"
+
+    # JST file constants.
+    JST_START       = "(function(){"
+    JST_END         = "})();"
+
+    COMPRESSORS = {
+      :yui     => YUI::JavaScriptCompressor,
+      :closure => Closure::Compiler
+    }
+
+    DEFAULT_OPTIONS = {
+      :yui     => {:munge => true},
+      :closure => {}
+    }
+
+    # Creating a compressor initializes the internal YUI Compressor from
+    # the "yui-compressor" gem, or the internal Closure Compiler from the
+    # "closure-compiler" gem.
+    def initialize
+      @css_compressor = YUI::CssCompressor.new(Jammit.config[:css_compressor_options] || {})
+      flavor          = Jammit.config[:javascript_compressor] || Jammit::DEFAULT_COMPRESSOR
+      @options        = DEFAULT_OPTIONS[flavor].merge(Jammit.config[:compressor_options] || {})
+      @js_compressor  = COMPRESSORS[flavor].new(@options)
+    end
+
+    # Concatenate together a list of JavaScript paths, and pass them through the
+    # YUI Compressor (with munging enabled).
+    def compress_js(paths)
+      js = concatenate(paths)
+      Jammit.config[:compress_assets] ? @js_compressor.compress(js) : js
+    end
+
+    # Concatenate and compress a list of CSS stylesheets. When compressing a
+    # :datauri or :mhtml variant, post-processes the result to embed
+    # referenced assets.
+    def compress_css(paths, variant=nil, asset_url=nil)
+      css = concatenate_and_tag_assets(paths, variant)
+      css = @css_compressor.compress(css) if Jammit.compress_assets
+      case variant
+      when nil      then return css
+      when :datauri then return with_data_uris(css)
+      when :mhtml   then return with_mhtml(css, asset_url)
+      else raise PackageNotFound, "\"#{variant}\" is not a valid stylesheet variant"
+      end
+    end
+
+    # Compiles a single JST file by writing out a javascript that adds
+    # template properties to a top-level template namespace object. Adds a
+    # JST-compilation function to the top of the package, unless you've
+    # specified your own preferred function, or turned it off.
+    # JST templates are named with the basename of their file.
+    def compile_jst(paths)
+      namespace = Jammit.template_namespace
+      compiled = paths.map do |path|
+        template_name = File.basename(path, File.extname(path))
+        contents      = File.read(path).gsub(/\n/, '').gsub("'", '\\\\\'')
+        "#{namespace}.#{template_name} = #{Jammit.template_function}('#{contents}');"
+      end
+      compiler = Jammit.config[:include_jst_script] ? File.read(Jammit::DEFAULT_JST_SCRIPT) : '';
+      setup_namespace = "#{namespace} = #{namespace} || {};"
+      [JST_START, setup_namespace, compiler, compiled, JST_END].flatten.join("\n")
+    end
+
+
+    private
+
+    # In order to support embedded assets from relative paths, we need to
+    # expand the paths before contatenating the CSS together and losing the
+    # location of the original stylesheet path. Validate the assets while we're
+    # at it.
+    def concatenate_and_tag_assets(paths, variant=nil)
+      stylesheets = [paths].flatten.map do |css_path|
+        File.read(css_path).gsub(EMBED_DETECTOR) do |url|
+          ipath, cpath = Pathname.new($1), Pathname.new(File.expand_path(css_path))
+          is_url = URI.parse($1).absolute?
+          is_url ? url : "url(#{construct_asset_path(ipath, cpath, variant)})"
+        end
+      end
+      stylesheets.join("\n")
+    end
+
+    # Re-write all enabled asset URLs in a stylesheet with their corresponding
+    # Data-URI Base-64 encoded asset contents.
+    def with_data_uris(css)
+      css.gsub(EMBED_REPLACER) do |url|
+        "url(\"data:#{mime_type($1)};charset=utf-8;base64,#{encoded_contents($1)}\")"
+      end
+    end
+
+    # Re-write all enabled asset URLs in a stylesheet with the MHTML equivalent.
+    # The newlines ("\r\n") in the following method are critical. Without them
+    # your MHTML will look identical, but won't work.
+    def with_mhtml(css, asset_url)
+      paths, index = {}, 0
+      css = css.gsub(EMBED_REPLACER) do |url|
+        i = paths[$1] ||= "#{index += 1}-#{File.basename($1)}"
+        "url(mhtml:#{asset_url}!#{i})"
+      end
+      mhtml = paths.sort.map do |path, identifier|
+        mime, contents = mime_type(path), encoded_contents(path)
+        [MHTML_SEPARATOR, "Content-Location: #{identifier}\r\n", "Content-Type: #{mime}\r\n", "Content-Transfer-Encoding: base64\r\n\r\n", contents, "\r\n"]
+      end
+      [MHTML_START, mhtml, MHTML_END, css].flatten.join('')
+    end
+
+    # Return a rewritten asset URL for a new stylesheet -- the asset should
+    # be tagged for embedding if embeddable, and referenced at the correct level
+    # if relative.
+    def construct_asset_path(asset_path, css_path, variant)
+      public_path = absolute_path(asset_path, css_path)
+      return "__EMBED__#{public_path}" if embeddable?(public_path, variant)
+      source = asset_path.absolute? ? asset_path.to_s : relative_path(public_path)
+      rewrite_asset_path(source, public_path)
+    end
+
+    # Get the site-absolute public path for an asset file path that may or may
+    # not be relative, given the path of the stylesheet that contains it.
+    def absolute_path(asset_pathname, css_pathname)
+      (asset_pathname.absolute? ?
+        Pathname.new(File.join(PUBLIC_ROOT, asset_pathname)) :
+        css_pathname.dirname + asset_pathname).cleanpath
+    end
+
+    # CSS assets that are referenced by relative paths, and are *not* being
+    # embedded, must be rewritten relative to the newly-merged stylesheet path.
+    def relative_path(absolute_path)
+      File.join('../', absolute_path.sub(PUBLIC_ROOT, ''))
+    end
+
+    # Similar to the AssetTagHelper's method of the same name, this will
+    # append the RAILS_ASSET_ID cache-buster to URLs, if it's defined.
+    def rewrite_asset_path(path, file_path)
+      asset_id = rails_asset_id(file_path)
+      asset_id.blank? ? path : "#{path}?#{asset_id}"
+    end
+
+    # Similar to the AssetTagHelper's method of the same name, this will
+    # determine the correct asset id for a file.
+    def rails_asset_id(path)
+      asset_id = ENV["RAILS_ASSET_ID"]
+      return asset_id if asset_id
+      File.exists?(path) ? File.mtime(path).to_i.to_s : ''
+    end
+
+    # An asset is valid for embedding if it exists, is less than 32K, and is
+    # stored somewhere inside of a folder named "embed".
+    # IE does not support Data-URIs larger than 32K, and you probably shouldn't
+    # be embedding assets that large in any case.
+    def embeddable?(asset_path, variant)
+      font = EMBED_FONTS.include?(asset_path.extname)
+      return false unless variant
+      return false unless asset_path.to_s.match(EMBEDDABLE) && asset_path.exist?
+      return false unless EMBED_EXTS.include?(asset_path.extname)
+      return false unless font || asset_path.size < MAX_IMAGE_SIZE
+      return false if font && variant == :mhtml
+      true
+    end
+
+    # Return the Base64-encoded contents of an asset on a single line.
+    def encoded_contents(asset_path)
+      data = File.open(asset_path, 'rb'){|f| f.read }
+      Base64.encode64(data).gsub(/\n/, '')
+    end
+
+    # Grab the mime-type of an asset, by filename.
+    def mime_type(asset_path)
+      EMBED_MIME_TYPES[File.extname(asset_path)]
+    end
+
+    # Concatenate together a list of asset files.
+    def concatenate(paths)
+      [paths].flatten.map {|p| File.read(p) }.join("\n")
+    end
+
+  end
+
+end

data/lib/jammit-core/config.rb

@@ -0,0 +1,82 @@
+module Jammit
+  module Config
+    
+    CONFIG_TEMPLATE = Jammit::ROOT + '/assets.example.yml'
+    
+    class << self
+      
+      def dispatch(command, *params)        
+        case command
+        when :create
+          create
+        when :set
+          set(params.shift, params.shift)
+        end
+      end
+      
+      ##
+      # load configuration file
+      # @param {String} path
+      # @param {Boolean} force reloading of config file
+      #
+      def load(force=false)        
+        raise Jammit::ConfigurationNotFound, "could not find the \"#{Jammit.config_path}\" configuration file" unless File.exists?(Jammit.config_path) && File.readable?(Jammit.config_path)        
+        if !@config || force == true
+          @config = YAML.load(ERB.new(File.read(Jammit.config_path)).result)
+        end
+        @config
+      end
+      
+  private
+      
+      ##
+      # Write config to file
+      #
+      def write(config)
+        File.open(Jammit.config_path, "w") {|f| 
+          f << config.to_yaml
+        }  
+      end
+      
+      ##
+      # If a config path is given, use that as the root, otherwise use DEFAULT_CONFIG_PATH
+      #
+      def create        
+        if File.exists?(Jammit.config_path)
+          raise Jammit::AlreadyConfigured.new(" Config file #{Jammit.config_path} already exists.")
+        end
+        FileUtils.mkdir_p(File.dirname(Jammit.config_path))
+        FileUtils.cp(CONFIG_TEMPLATE, Jammit.config_path)
+        
+        parts = Jammit.config_path.split('/')
+        name = parts.pop
+        dir  = parts.pop
+        Jammit.ui.confirm(" create #{dir}/#{name}")
+      end
+      
+      ##
+      # Set a config property in file
+      # @param {String} name
+      # @param {String} value
+      #
+      def set(name, value)
+        value = (value == "true") ? true : (value == "false") ? false : value
+        
+        config = load(true)
+        option = config[name]
+        
+        # careful not to clobber raexisting values if updating a hash
+        if value.kind_of?(Hash) && option.kind_of?(Hash)
+          value.keys.each do |k|
+            option[k] = value[k]
+          end
+          config.update(name => option)
+        else
+          config.update(name => value)
+        end
+        write(config)
+        Jammit.ui.confirm(" set #{name}")
+      end
+    end
+  end
+end

data/lib/jammit-core/dependencies.rb

@@ -0,0 +1,23 @@
+# Standard Library Dependencies:
+require 'uri'
+require 'erb'
+require 'zlib'
+require 'base64'
+require 'pathname'
+require 'fileutils'
+require 'json'
+
+# Pull in some extlib goodies
+require 'extlib/class'
+require 'extlib/hash'
+require 'extlib/mash'
+require 'extlib/inflection'
+
+# Gem Dependencies:
+require 'rubygems'
+require 'yui/compressor'
+require 'closure-compiler'
+
+# Jammit Core:
+require 'jammit-core/compressor'
+require 'jammit-core/packager'

data/lib/jammit-core/helper.rb

@@ -0,0 +1,77 @@
+module Jammit
+
+  # The Jammit::Helper module, which is made available to every view, provides
+  # helpers for writing out HTML tags for asset packages. In development you
+  # get the ordered list of source files -- in any other environment, a link
+  # to the cached packages.
+  module Helper
+
+    DATA_URI_START = "<!--[if (!IE)|(gte IE 8)]><!-->"
+    DATA_URI_END   = "<!--<![endif]-->"
+    MHTML_START    = "<!--[if lte IE 7]>"
+    MHTML_END      = "<![endif]-->"
+
+    # If embed_assets is turned on, writes out links to the Data-URI and MHTML
+    # versions of the stylesheet package, otherwise the package is regular
+    # compressed CSS, and in development the stylesheet URLs are passed verbatim.
+    def include_stylesheets(*packages)
+      options = packages.extract_options!
+      return individual_stylesheets(packages, options) unless Jammit.package_assets
+      disabled = (options.delete(:embed_assets) == false) || (options.delete(:embed_images) == false)
+      return packaged_stylesheets(packages, options) if disabled || !Jammit.embed_assets
+      return embedded_image_stylesheets(packages, options)
+    end
+
+    # Writes out the URL to the bundled and compressed javascript package,
+    # except in development, where it references the individual scripts.
+    def include_javascripts(*packages)
+      tags = packages.map do |pack|
+        Jammit.package_assets ? Jammit.asset_url(pack, :js) : Jammit.packager.individual_urls(pack.to_sym, :js)
+      end
+      javascript_include_tag(tags.flatten)
+    end
+
+    # Writes out the URL to the concatenated and compiled JST file -- we always
+    # have to pre-process it, even in development.
+    def include_templates(*packages)
+      javascript_include_tag(packages.map {|pack| Jammit.asset_url(pack, :jst) })
+    end
+
+
+    private
+
+    # HTML tags, in order, for all of the individual stylesheets.
+    def individual_stylesheets(packages, options)
+      tags_with_options(packages, options) {|p| Jammit.packager.individual_urls(p.to_sym, :css) }
+    end
+
+    # HTML tags for the stylesheet packages.
+    def packaged_stylesheets(packages, options)
+      tags_with_options(packages, options) {|p| Jammit.asset_url(p, :css) }
+    end
+
+    # HTML tags for the 'datauri', and 'mhtml' versions of the packaged
+    # stylesheets, using conditional comments to load the correct variant.
+    def embedded_image_stylesheets(packages, options)
+      datauri_tags = tags_with_options(packages, options) {|p| Jammit.asset_url(p, :css, :datauri) }
+      ie_tags = Jammit.mhtml_enabled ?
+                tags_with_options(packages, options) {|p| Jammit.asset_url(p, :css, :mhtml) } :
+                packaged_stylesheets(packages, options)
+      [DATA_URI_START, datauri_tags, DATA_URI_END, MHTML_START, ie_tags, MHTML_END].join("\n")
+    end
+
+    # Generate the stylesheet tags for a batch of packages, with options, by
+    # yielding each package to a block.
+    def tags_with_options(packages, options)
+      packages = packages.dup
+      packages.map! {|package| yield package }.flatten!
+      packages.push(options) unless options.empty?
+      stylesheet_link_tag(*packages)
+    end
+
+  end
+
+end
+
+# Include the Jammit asset helpers in all views, a-la ApplicationHelper.
+::ActionView::Base.send(:include, Jammit::Helper)