sprockets 1.0.2 → 2.0.0

data/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2011 Sam Stephenson
+Copyright (c) 2011 Joshua Peek
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,356 @@
+# Sprockets: Rack-based asset packaging
+
+Sprockets is a Ruby library for compiling and serving web assets.
+It features declarative dependency management for JavaScript and CSS
+assets, as well as a powerful preprocessor pipeline that allows you to
+write assets in languages like CoffeeScript, Sass, SCSS and LESS.
+
+# Installation #
+
+Install Sprockets from RubyGems:
+
+    $ gem install sprockets
+
+Or include it in your project's `Gemfile` with Bundler:
+
+    gem 'sprockets', '~> 2.0'
+
+# Understanding the Sprockets Environment #
+
+You'll need an instance of the `Sprockets::Environment` class to
+access and serve assets from your application. Under Rails 3.1 and
+later, `YourApp::Application.assets` is a preconfigured
+`Sprockets::Environment` instance. For Rack-based applications, create
+an instance in `config.ru`.
+
+The Sprockets `Environment` has methods for retrieving and serving
+assets, manipulating the load path, and registering processors. It is
+also a Rack application that can be mounted at a URL to serve assets
+over HTTP.
+
+## The Load Path ##
+
+The *load path* is an ordered list of directories that Sprockets uses
+to search for assets.
+
+In the simplest case, a Sprockets environment's load path will consist
+of a single directory containing your application's asset source
+files. When mounted, the environment will serve assets from this
+directory as if they were static files in your public root.
+
+The power of the load path is that it lets you organize your source
+files into multiple directories -- even directories that live outside
+your application -- and combine those directories into a single
+virtual filesystem. That means you can easily bundle JavaScript, CSS
+and images into a Ruby library and import them into your application.
+
+### Manipulating the Load Path ###
+
+To add a directory to your environment's load path, use the
+`append_path` and `prepend_path` methods. Directories at the beginning
+of the load path have precedence over subsequent directories.
+
+    environment = Sprockets::Environment.new
+    environment.append_path 'app/assets/javascripts'
+    environment.append_path 'lib/assets/javascripts'
+    environment.append_path 'vendor/assets/jquery'
+
+In general, you should append to the path by default and reserve
+prepending for cases where you need to override existing assets.
+
+## Accessing Assets ##
+
+Once you've set up your environment's load path, you can mount the
+environment as a Rack server and request assets via HTTP. You can also
+access assets programmatically from within your application.
+
+### Logical Paths ###
+
+Assets in Sprockets are always referenced by their *logical path*.
+
+The logical path is the path of the asset source file relative to its
+containing directory in the load path. For example, if your load path
+contains the directory `app/assets/javascripts`:
+
+<table>
+  <tr>
+    <th>Asset source file</th>
+    <th>Logical path</th>
+  </tr>
+  <tr>
+    <td>app/assets/javascripts/application.js</td>
+    <td>application.js</td>
+  </tr>
+  <tr>
+    <td>app/assets/javascripts/models/project.js</td>
+    <td>models/project.js</td>
+  </tr>
+</table>
+
+In this way, all directories in the load path are merged to create a
+virtual filesystem whose entries are logical paths.
+
+### Serving Assets Over HTTP ###
+
+When you mount an environment, all of its assets are accessible as
+logical paths underneath the *mount point*. For example, if you mount
+your environment at `/assets` and request the URL
+`/assets/application.js`, Sprockets will search your load path for the
+file named `application.js` and serve it.
+
+Under Rails 3.1 and later, your Sprockets environment is automatically
+mounted at `/assets`. If you are using Sprockets with a Rack
+application, you will need to mount the environment yourself. A good
+way to do this is with the `map` method in `config.ru`:
+
+    require 'sprockets'
+    map '/assets' do
+      environment = Sprockets::Environment.new
+      environment.append_path 'app/assets/javascripts'
+      environment.append_path 'app/assets/stylesheets'
+      run environment
+    end
+
+### Accessing Assets Programmatically ###
+
+You can use the `find_asset` method (aliased as `[]`) to retrieve an
+asset from a Sprockets environment. Pass it a logical path and you'll
+get a `Sprockets::BundledAsset` instance back:
+
+    environment['application.js']
+    # => #<Sprockets::BundledAsset ...>
+
+Call `to_s` on the resulting asset to access its contents, `length` to
+get its length in bytes, `mtime` to query its last-modified time, and
+`pathname` to get its full path on the filesystem.
+
+# Using Engines #
+
+Asset source files can be written in another language, like SCSS or
+CoffeeScript, and automatically compiled to CSS or JavaScript by
+Sprockets. Compilers for these languages are called *engines*.
+
+Engines are specified by additional extensions on the asset source
+filename. For example, a CSS file written in SCSS might have the name
+`layout.css.scss`, while a JavaScript file written in CoffeeScript
+might have the name `dialog.js.coffee`.
+
+## Styling with Sass and SCSS ##
+
+[Sass](http://sass-lang.com/) is a language that compiles to CSS and
+adds features like nested rules, variables, mixins and selector
+inheritance.
+
+If the `sass` gem is available to your application, you can use Sass
+to write CSS assets in Sprockets.
+
+Sprockets supports both Sass syntaxes. For the original
+whitespace-sensitive syntax, use the extension `.css.sass`. For the
+new SCSS syntax, use the extension `.css.scss`.
+
+## Styling with LESS ##
+
+[LESS](http://lesscss.org/) extends CSS with dynamic behavior such as
+variables, mixins, operations and functions.
+
+If the `less` gem is available to your application, you can use LESS
+to write CSS assets in Sprockets. Note that the LESS compiler is
+written in JavaScript, and at the time of this writing, the `less` gem
+depends on `therubyracer` which embeds the V8 JavaScript runtime in
+Ruby.
+
+To write CSS assets with LESS, use the extension `.css.less`.
+
+## Scripting with CoffeeScript ##
+
+[CoffeeScript](http://jashkenas.github.com/coffee-script/) is a
+language that compiles to the "good parts" of JavaScript, featuring a
+cleaner syntax with array comprehensions, classes, and function
+binding.
+
+If the `coffee-script` gem is available to your application, you can
+use CoffeeScript to write JavaScript assets in Sprockets. Note that
+the CoffeeScript compiler is written in JavaScript, and you will need
+an [ExecJS](https://github.com/sstephenson/execjs)-supported runtime
+on your system to invoke it.
+
+To write JavaScript assets with CoffeeScript, use the extension
+`.js.coffee`.
+
+## JavaScript Templating with EJS and Eco ##
+
+Sprockets supports *JavaScript templates* for client-side rendering of
+strings or markup. JavaScript templates have the special format
+extension `.jst` and are compiled to JavaScript functions.
+
+When loaded, a JavaScript template function can be accessed by its
+logical path as a property on the global `JST` object. Invoke a
+template function to render the template as a string. The resulting
+string can then be inserted into the DOM.
+
+    <!-- templates/hello.jst.ejs -->
+    <div>Hello, <span><%= name %></span>!</div>
+
+    // application.js
+    //= require templates/hello
+    $("#hello").html(JST["templates/hello"]({ name: "Sam" }));
+
+Sprockets supports two JavaScript template languages:
+[EJS](https://github.com/sstephenson/ruby-ejs), for embedded
+JavaScript, and [Eco](https://github.com/sstephenson/ruby-eco), for
+embedded CoffeeScript. Both languages use the familiar `<% … %>`
+syntax for embedding logic in templates.
+
+If the `ejs` gem is available to your application, you can use EJS
+templates in Sprockets. EJS templates have the extension `.jst.ejs`.
+
+If the `eco` gem is available to your application, you can use [Eco
+templates](https://github.com/sstephenson/eco) in Sprockets. Eco
+templates have the extension `.jst.eco`. Note that the `eco` gem
+depends on the CoffeeScript compiler, so the same caveats apply as
+outlined above for the CoffeeScript engine.
+
+## Invoking Ruby with ERB ##
+
+Sprockets provides an ERB engine for preprocessing assets using
+embedded Ruby code. Append `.erb` to a CSS or JavaScript asset's
+filename to enable the ERB engine.
+
+**Note**: Sprockets processes multiple engine extensions in order from
+  right to left, so you can use multiple engines with a single
+  asset. For example, to have a CoffeeScript asset that is first
+  preprocessed with ERB, use the extension `.js.coffee.erb`.
+
+Ruby code embedded in an asset is evaluated in the context of a
+`Sprockets::Context` instance for the given asset. Common uses for ERB
+include:
+
+- embedding another asset as a Base64-encoded `data:` URI with the
+  `asset_data_uri` helper
+- inserting the URL to another asset, such as with the `asset_path`
+  helper provided by the Sprockets Rails plugin
+- embedding other application resources, such as a localized string
+  database, in a JavaScript asset via JSON
+- embedding version constants loaded from another file
+
+See the [Helper Methods](#FIXME) section for more information about
+interacting with `Sprockets::Context` instances via ERB.
+
+### String Interpolation Syntax ###
+
+If you need access to Ruby from an asset but cannot use ERB's `<% …
+%>` syntax, Sprockets also supports Ruby string interpolation syntax
+(`#{ … }`) with the `.str` engine extension.
+
+# Managing and Bundling Dependencies #
+
+You can create *asset bundles* -- ordered concatenations of asset
+source files -- by specifying dependencies in a special comment syntax
+at the top of each source file.
+
+Sprockets reads these comments, called *directives*, and processes
+them to recursively build a dependency graph. When you request an
+asset with dependencies, the dependencies will be included in order at
+the top of the file.
+
+## The Directive Processor ##
+
+Sprockets runs the *directive processor* on each CSS and JavaScript
+source file. The directive processor scans for comment lines beginning
+with `=` in comment blocks at the top of the file.
+
+    //= require jquery
+    //= require jquery-ui
+    //= require backbone
+    //= require_tree .
+
+The first word immediately following `=` specifies the directive
+name. Any words following the directive name are treated as
+arguments. Arguments may be placed in single or double quotes if they
+contain spaces, similar to commands in the Unix shell.
+
+**Note**: Non-directive comment lines will be preserved in the final
+  asset, but directive comments are stripped after
+  processing. Sprockets will not look for directives in comment blocks
+  that occur after the first line of code.
+
+### Supported Comment Types ###
+
+The directive processor understands comment blocks in three formats:
+
+    /* Multi-line comment blocks (CSS, SCSS, JavaScript)
+     *= require foo
+     */
+
+    // Single-line comment blocks (SCSS, JavaScript)
+    //= require foo
+
+    # Single-line comment blocks (CoffeeScript)
+    #= require foo
+
+## Sprockets Directives ##
+
+You can use the following directives to declare dependencies in asset
+source files.
+
+For directives that take a *path* argument, you may specify either a
+logical path or a relative path. Relative paths begin with `./` and
+reference files relative to the location of the current file.
+
+### The `require` Directive ###
+
+`require` *path* inserts the contents of the asset source file
+specified by *path*. If the file is required multiple times, it will
+appear in the bundle only once.
+
+### The `include` Directive ###
+
+`include` *path* works like `require`, but inserts the contents of the
+specified source file even if it has already been included or
+required.
+
+### The `require_directory` Directive ###
+
+`require_directory` *path* requires all source files of the same
+format in the directory specified by *path*. Files are required in
+alphabetical order.
+
+### The `require_tree` Directive ###
+
+`require_tree` *path* works like `require_directory`, but operates
+recursively to require all files in all subdirectories of the
+directory specified by *path*.
+
+### The `require_self` Directive ###
+
+`require_self` tells Sprockets to insert the body of the current
+source file before any subsequent `require` or `include` directives.
+
+### The `depend_on` Directive ###
+
+`depend_on` *path* declares a dependency on the given *path* without
+including it in the bundle. This is useful when you need to expire an
+asset's cache in response to a change in another file.
+
+# Contributing #
+
+The Sprockets source code is [hosted on
+GitHub](https://github.com/sstephenson/sprockets). You can check out a
+copy of the latest code using Git:
+
+    $ git clone https://github.com/sstephenson/sprockets.git
+
+If you've found a bug or have a question, please open an issue on the
+[Sprockets issue
+tracker](https://github.com/sstephenson/sprockets/issues). Or, clone
+the Sprockets repository, write a failing test case, fix the bug and
+submit a pull request.
+
+# License #
+
+Copyright &copy; 2011 Sam Stephenson <<sstephenson@gmail.com>>
+
+Copyright &copy; 2011 Joshua Peek <<josh@joshpeek.com>>
+
+Sprockets is distributed under an MIT-style license. See LICENSE for
+details.

data/lib/sprockets.rb

@@ -1,42 +1,31 @@
-$:.unshift File.dirname(__FILE__)
-
-require "yaml"
-require "fileutils"
+require 'sprockets/version'
 
 module Sprockets
-  class << self
-    def running_on_windows?
-      RUBY_PLATFORM =~ /(win|w)32$/
-    end
-  
-    def absolute?(location)
-      same_when_expanded?(location) || platform_absolute_path?(location)
-    end
-
-    protected
-      def same_when_expanded?(location)
-        location[0, 1] == File.expand_path(location)[0, 1]
-      end
-
-      def platform_absolute_path?(location)
-        false
-      end
+  autoload :ArgumentError,           "sprockets/errors"
+  autoload :Asset,                   "sprockets/asset"
+  autoload :AssetAttributes,         "sprockets/asset_attributes"
+  autoload :BundledAsset,            "sprockets/bundled_asset"
+  autoload :CharsetNormalizer,       "sprockets/charset_normalizer"
+  autoload :CircularDependencyError, "sprockets/errors"
+  autoload :ContentTypeMismatch,     "sprockets/errors"
+  autoload :Context,                 "sprockets/context"
+  autoload :DirectiveProcessor,      "sprockets/directive_processor"
+  autoload :EcoTemplate,             "sprockets/eco_template"
+  autoload :EjsTemplate,             "sprockets/ejs_template"
+  autoload :EngineError,             "sprockets/errors"
+  autoload :Engines,                 "sprockets/engines"
+  autoload :Environment,             "sprockets/environment"
+  autoload :Error,                   "sprockets/errors"
+  autoload :FileNotFound,            "sprockets/errors"
+  autoload :Index,                   "sprockets/index"
+  autoload :JstProcessor,            "sprockets/jst_processor"
+  autoload :Processing,              "sprockets/processing"
+  autoload :Processor,               "sprockets/processor"
+  autoload :Server,                  "sprockets/server"
+  autoload :StaticAsset,             "sprockets/static_asset"
+  autoload :Utils,                   "sprockets/utils"
 
-      if Sprockets.running_on_windows?
-        def platform_absolute_path?(location)
-          location[0, 1] == File::SEPARATOR && File.expand_path(location) =~ /[A-Za-z]:[\/\\]/
-        end
-      end
+  module Cache
+    autoload :FileStore, "sprockets/cache/file_store"
   end
 end
-
-require "sprockets/version"
-require "sprockets/error"
-require "sprockets/environment"
-require "sprockets/pathname"
-require "sprockets/source_line"
-require "sprockets/source_file"
-require "sprockets/concatenation"
-require "sprockets/preprocessor"
-require "sprockets/secretary"
-

data/lib/sprockets/asset.rb

@@ -0,0 +1,212 @@
+require 'time'
+
+module Sprockets
+  # `Asset` is the base class for `BundledAsset` and `StaticAsset`.
+  class Asset
+    # Internal initializer to load `Asset` from serialized `Hash`.
+    def self.from_hash(environment, hash)
+      asset = allocate
+      asset.init_with(environment, hash)
+      asset
+    end
+
+    # Define base set of attributes to be serialized.
+    def self.serialized_attributes
+      %w( id logical_path pathname )
+    end
+
+    attr_reader :environment
+    attr_reader :id, :logical_path, :pathname
+
+    def initialize(environment, logical_path, pathname)
+      @environment  = environment
+      @logical_path = logical_path.to_s
+      @pathname     = Pathname.new(pathname)
+      @id           = environment.digest.update(object_id.to_s).to_s
+    end
+
+    # Initialize `Asset` from serialized `Hash`.
+    def init_with(environment, coder)
+      @environment = environment
+      @pathname = @mtime = @length = nil
+
+      self.class.serialized_attributes.each do |attr|
+        instance_variable_set("@#{attr}", coder[attr].to_s) if coder[attr]
+      end
+
+      if @pathname && @pathname.is_a?(String)
+        # Expand `$root` placeholder and wrapper string in a `Pathname`
+        @pathname = Pathname.new(expand_root_path(@pathname))
+      end
+
+      if @mtime && @mtime.is_a?(String)
+        # Parse time string
+        @mtime = Time.parse(@mtime)
+      end
+
+      if @length && @length.is_a?(String)
+        # Convert length to an `Integer`
+        @length = Integer(@length)
+      end
+    end
+
+    # Copy serialized attributes to the coder object
+    def encode_with(coder)
+      coder['class'] = self.class.name.sub(/Sprockets::/, '')
+
+      self.class.serialized_attributes.each do |attr|
+        value = send(attr)
+        coder[attr] = case value
+          when Time
+            value.iso8601
+          else
+            value.to_s
+          end
+      end
+
+      coder['pathname'] = relativize_root_path(coder['pathname'])
+    end
+
+    # Returns `Content-Type` from pathname.
+    def content_type
+      @content_type ||= environment.content_type_of(pathname)
+    end
+
+    # Get mtime at the time the `Asset` is built.
+    def mtime
+      @mtime ||= environment.stat(pathname).mtime
+    end
+
+    # Get length at the time the `Asset` is built.
+    def length
+      @length ||= environment.stat(pathname).size
+    end
+
+    # Get content digest at the time the `Asset` is built.
+    def digest
+      @digest ||= environment.file_digest(pathname).hexdigest
+    end
+
+    # Return logical path with digest spliced in.
+    #
+    #   "foo/bar-37b51d194a7513e45b56f6524f2d51f2.js"
+    #
+    def digest_path
+      environment.attributes_for(logical_path).path_with_fingerprint(digest)
+    end
+
+    # Return an `Array` of `Asset` files that are declared dependencies.
+    def dependencies
+      []
+    end
+
+    # Expand asset into an `Array` of parts.
+    #
+    # Appending all of an assets body parts together should give you
+    # the asset's contents as a whole.
+    #
+    # This allows you to link to individual files for debugging
+    # purposes.
+    def to_a
+      [self]
+    end
+
+    # Add enumerator to allow `Asset` instances to be used as Rack
+    # compatible body objects.
+    def each
+      yield to_s
+    end
+
+    # Checks if Asset is fresh by comparing the actual mtime and
+    # digest to the inmemory model.
+    #
+    # Used to test if cached models need to be rebuilt.
+    #
+    # Subclass must override `fresh?` or `stale?`.
+    def fresh?
+      !stale?
+    end
+
+    # Checks if Asset is stale by comparing the actual mtime and
+    # digest to the inmemory model.
+    #
+    # Subclass must override `fresh?` or `stale?`.
+    def stale?
+      !fresh?
+    end
+
+    # Pretty inspect
+    def inspect
+      "#<#{self.class}:0x#{object_id.to_s(16)} " +
+        "pathname=#{pathname.to_s.inspect}, " +
+        "mtime=#{mtime.inspect}, " +
+        "digest=#{digest.inspect}" +
+        ">"
+    end
+
+    # Assets are equal if they share the same path, mtime and digest.
+    def eql?(other)
+      other.class == self.class &&
+        other.relative_pathname == self.relative_pathname &&
+        other.mtime.to_i == self.mtime.to_i &&
+        other.digest == self.digest
+    end
+    alias_method :==, :eql?
+
+    protected
+      # Get pathname with its root stripped.
+      def relative_pathname
+        Pathname.new(relativize_root_path(pathname))
+      end
+
+      # Replace `$root` placeholder with actual environment root.
+      def expand_root_path(path)
+        environment.attributes_for(path).expand_root
+      end
+
+      # Replace actual environment root with `$root` placeholder.
+      def relativize_root_path(path)
+        environment.attributes_for(path).relativize_root
+      end
+
+      # Check if dependency is fresh.
+      #
+      # `dep` is a `Hash` with `path`, `mtime` and `hexdigest` keys.
+      #
+      # A `Hash` is used rather than other `Asset` object because we
+      # want to test non-asset files and directories.
+      def dependency_fresh?(dep = {})
+        path, mtime, hexdigest = dep.values_at('path', 'mtime', 'hexdigest')
+
+        stat = environment.stat(path)
+
+        # If path no longer exists, its definitely stale.
+        if stat.nil?
+          return false
+        end
+
+        # Compare dependency mime to the actual mtime. If the
+        # dependency mtime is newer than the actual mtime, the file
+        # hasn't changed since we created this `Asset` instance.
+        #
+        # However, if the mtime is newer it doesn't mean the asset is
+        # stale. Many deployment environments may recopy or recheckout
+        # assets on each deploy. In this case the mtime would be the
+        # time of deploy rather than modified time.
+        if mtime >= stat.mtime
+          return true
+        end
+
+        digest = environment.file_digest(path)
+
+        # If the mtime is newer, do a full digest comparsion. Return
+        # fresh if the digests match.
+        if hexdigest == digest.hexdigest
+          return true
+        end
+
+        # Otherwise, its stale.
+        false
+      end
+  end
+end