challah 0.5.4 → 0.6.0

data/vendor/bundle/gems/sprockets-2.1.3/README.md

@@ -0,0 +1,397 @@
+# 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
+
+    map '/' do
+      run YourRackApp
+    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.
+
+# Development #
+
+## 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.
+
+## Version History ##
+
+**2.1.2** (November 20, 2011)
+
+* Disabled If-Modified-Since server checks. Fixes some browser caching issues when serving the asset body only. If-None-Match caching is sufficent.
+
+**2.1.1** (November 18, 2011)
+
+* Fix windows absolute path check bug.
+
+**2.1.0** (November 11, 2011)
+
+* Directive comment lines are now turned into empty lines instead of removed. This way line numbers in
+  CoffeeScript syntax errors are correct.
+* Performance and caching bug fixes.
+
+**2.0.3** (October 17, 2011)
+
+* Detect format extensions from right to left.
+* Make JST namespace configurable.
+
+**2.0.2** (October 4, 2011)
+
+* Fixed loading stale cache from bundler gems.
+
+**2.0.1** (September 30, 2011)
+
+* Fixed bug with fingerprinting file names with multiple dots.
+* Decode URIs as default internal.
+* Fix symlinked asset directories.
+
+**2.0.0** (August 29, 2011)
+
+* Initial public release.
+
+# 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/vendor/bundle/gems/sprockets-2.1.3/lib/sprockets/asset.rb

@@ -0,0 +1,258 @@
+require 'time'
+require 'set'
+
+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)
+      return unless hash.is_a?(Hash)
+
+      klass = case hash['class']
+        when 'BundledAsset'
+          BundledAsset
+        when 'ProcessedAsset'
+          ProcessedAsset
+        when 'StaticAsset'
+          StaticAsset
+        else
+          nil
+        end
+
+      if klass
+        asset = klass.allocate
+        asset.init_with(environment, hash)
+        asset
+      end
+    rescue UnserializeError
+      nil
+    end
+
+    attr_reader :logical_path, :pathname
+    attr_reader :content_type, :mtime, :length, :digest
+
+    def initialize(environment, logical_path, pathname)
+      @root         = environment.root
+      @logical_path = logical_path.to_s
+      @pathname     = Pathname.new(pathname)
+      @content_type = environment.content_type_of(pathname)
+      @mtime        = environment.stat(pathname).mtime
+      @length       = environment.stat(pathname).size
+      @digest       = environment.file_digest(pathname).hexdigest
+    end
+
+    # Initialize `Asset` from serialized `Hash`.
+    def init_with(environment, coder)
+      @root = environment.root
+
+      @logical_path = coder['logical_path']
+      @content_type = coder['content_type']
+      @digest       = coder['digest']
+
+      if pathname = coder['pathname']
+        # Expand `$root` placeholder and wrapper string in a `Pathname`
+        @pathname = Pathname.new(expand_root_path(pathname))
+      end
+
+      if mtime = coder['mtime']
+        # Parse time string
+        @mtime = Time.parse(mtime)
+      end
+
+      if length = coder['length']
+        # 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::/, '')
+      coder['logical_path'] = logical_path
+      coder['pathname']     = relativize_root_path(pathname).to_s
+      coder['content_type'] = content_type
+      coder['mtime']        = mtime.iso8601
+      coder['length']       = length
+      coder['digest']       = digest
+    end
+
+    # Return logical path with digest spliced in.
+    #
+    #   "foo/bar-37b51d194a7513e45b56f6524f2d51f2.js"
+    #
+    def digest_path
+      logical_path.sub(/\.(\w+)$/) { |ext| "-#{digest}#{ext}" }
+    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
+
+    # `body` is aliased to source by default if it can't have any dependencies.
+    def body
+      source
+    end
+
+    # Return `String` of concatenated source.
+    def to_s
+      source
+    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.
+    def fresh?(environment)
+      # Check current mtime and digest
+      dependency_fresh?(environment, self)
+    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?(environment)
+      !fresh?(environment)
+    end
+
+    # Save asset to disk.
+    def write_to(filename, options = {})
+      # Gzip contents if filename has '.gz'
+      options[:compress] ||= File.extname(filename) == '.gz'
+
+      File.open("#{filename}+", 'wb') do |f|
+        if options[:compress]
+          # Run contents through `Zlib`
+          gz = Zlib::GzipWriter.new(f, Zlib::BEST_COMPRESSION)
+          gz.write to_s
+          gz.close
+        else
+          # Write out as is
+          f.write to_s
+          f.close
+        end
+      end
+
+      # Atomic write
+      FileUtils.mv("#{filename}+", filename)
+
+      # Set mtime correctly
+      File.utime(mtime, mtime, filename)
+
+      nil
+    ensure
+      # Ensure tmp file gets cleaned up
+      FileUtils.rm("#{filename}+") if File.exist?("#{filename}+")
+    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
+
+    def hash
+      digest.hash
+    end
+
+    # Assets are equal if they share the same path, mtime and digest.
+    def eql?(other)
+      other.class == self.class &&
+        other.logical_path == self.logical_path &&
+        other.mtime.to_i == self.mtime.to_i &&
+        other.digest == self.digest
+    end
+    alias_method :==, :eql?
+
+    protected
+      # Internal: String paths that are marked as dependencies after processing.
+      #
+      # Default to an empty `Array`.
+      def dependency_paths
+        @dependency_paths ||= []
+      end
+
+      # Internal: `ProccessedAsset`s that are required after processing.
+      #
+      # Default to an empty `Array`.
+      def required_assets
+        @required_assets ||= []
+      end
+
+      # Get pathname with its root stripped.
+      def relative_pathname
+        @relative_pathname ||= Pathname.new(relativize_root_path(pathname))
+      end
+
+      # Replace `$root` placeholder with actual environment root.
+      def expand_root_path(path)
+        path.to_s.sub(/^\$root/, @root)
+      end
+
+      # Replace actual environment root with `$root` placeholder.
+      def relativize_root_path(path)
+        path.to_s.sub(/^#{Regexp.escape(@root)}/, '$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?(environment, dep)
+        path, mtime, hexdigest = dep.pathname.to_s, dep.mtime, dep.digest
+
+        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