sprockets 2.3.2 → 3.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 196e262a4bc69c0989859f510f703ccf2b2c16ca
+  data.tar.gz: 8c511861fd25f35955e3f4c748bf97a1ef49dc6b
+SHA512:
+  metadata.gz: 78fed6b263b253262e03d814f7b1989da90e4c840a7be325a6bae7ff40d58dbc807ae9469f95400ef8fbf33f1ade9746757344a42da29c48dc0a228567337d71
+  data.tar.gz: 1798e1b5216d9c9ed70056b0a828f3ac7a119e0dd2773a590a80dec4b209f93c12eedc7ee7e49b00381df16d91891fc124ca7d0aa59253e9602dc34a398d79ed

data/LICENSE

@@ -1,5 +1,5 @@
-Copyright (c) 2011 Sam Stephenson
-Copyright (c) 2011 Joshua Peek
+Copyright (c) 2014 Sam Stephenson
+Copyright (c) 2014 Joshua Peek
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -3,22 +3,28 @@
 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.
+write assets in languages like CoffeeScript, Sass and SCSS.
 
-# Installation #
+
+## Installation
 
 Install Sprockets from RubyGems:
 
-    $ gem install sprockets
+``` sh
+$ gem install sprockets
+```
 
 Or include it in your project's `Gemfile` with Bundler:
 
-    gem 'sprockets', '~> 2.0'
+``` ruby
+gem 'sprockets', '~> 3.0'
+```
+
 
-# Understanding the Sprockets Environment #
+## 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
+access and serve assets from your application. Under Rails 4.0 and
 later, `YourApp::Application.assets` is a preconfigured
 `Sprockets::Environment` instance. For Rack-based applications, create
 an instance in `config.ru`.
@@ -28,7 +34,7 @@ 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
 
 The *load path* is an ordered list of directories that Sprockets uses
 to search for assets.
@@ -42,29 +48,31 @@ 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.
+and images into a Ruby library or [Bower](http://bower.io) package and import them into your application.
 
-### Manipulating the Load Path ###
+#### 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'
+``` ruby
+environment = Sprockets::Environment.new
+environment.append_path 'app/assets/javascripts'
+environment.append_path 'lib/assets/javascripts'
+environment.append_path 'vendor/assets/bower_components'
+```
 
 In general, you should append to the path by default and reserve
 prepending for cases where you need to override existing assets.
 
-## Accessing 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 ###
+#### Logical Paths
 
 Assets in Sprockets are always referenced by their *logical path*.
 
@@ -90,7 +98,7 @@ contains the directory `app/assets/javascripts`:
 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 ###
+#### 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
@@ -98,48 +106,57 @@ 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
+Under Rails 4.0 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
+``` ruby
+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
+map '/' do
+  run YourRackApp
+end
+```
 
-### Accessing Assets Programmatically ###
+#### 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:
+get a `Sprockets::Asset` instance back:
 
-    environment['application.js']
-    # => #<Sprockets::BundledAsset ...>
+``` ruby
+environment['application.js']
+# => #<Sprockets::Asset ...>
+```
 
 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.
+`filename` to get its full path on the filesystem.
+
 
-# Using Engines #
+## Using Processors
 
-Asset source files can be written in another language, like SCSS or
+Asset source files can be written in another format, like SCSS or
 CoffeeScript, and automatically compiled to CSS or JavaScript by
-Sprockets. Compilers for these languages are called *engines*.
+Sprockets. Processors that convert a file from one format to another are called *transformers*.
 
-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`.
+### Minifying Assets
 
-## Styling with Sass and SCSS ##
+Several JavaScript and CSS minifiers are available through shorthand.
+
+``` ruby
+environment.js_compressor  = :uglify
+environment.css_compressor = :scss
+```
+
+### 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
@@ -149,23 +166,10 @@ 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 ##
+whitespace-sensitive syntax, use the extension `.sass`. For the
+new SCSS syntax, use the extension `.scss`.
 
-[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 ##
+### Scripting with CoffeeScript
 
 [CoffeeScript](http://jashkenas.github.com/coffee-script/) is a
 language that compiles to the "good parts" of JavaScript, featuring a
@@ -175,13 +179,13 @@ 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
+an [ExecJS](https://github.com/rails/execjs)-supported runtime
 on your system to invoke it.
 
 To write JavaScript assets with CoffeeScript, use the extension
-`.js.coffee`.
+`.coffee`.
 
-## JavaScript Templating with EJS and Eco ##
+### JavaScript Templating with EJS and Eco
 
 Sprockets supports *JavaScript templates* for client-side rendering of
 strings or markup. JavaScript templates have the special format
@@ -192,12 +196,14 @@ 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>
+```
+<!-- templates/hello.jst.ejs -->
+<div>Hello, <span><%= name %></span>!</div>
 
-    // application.js
-    //= require templates/hello
-    $("#hello").html(JST["templates/hello"]({ name: "Sam" }));
+// 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
@@ -214,17 +220,12 @@ 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 ##
+### 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:
@@ -237,16 +238,11 @@ include:
   database, in a JavaScript asset via JSON
 - embedding version constants loaded from another file
 
-See the [Helper Methods](#FIXME) section for more information about
+See the [Helper Methods](lib/sprockets/context.rb) 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 #
+## Managing and Bundling Dependencies
 
 You can create *asset bundles* -- ordered concatenations of asset
 source files -- by specifying dependencies in a special comment syntax
@@ -257,16 +253,18 @@ 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 ##
+### 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 .
+``` js
+//= 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
@@ -278,21 +276,27 @@ contain spaces, similar to commands in the Unix shell.
   processing. Sprockets will not look for directives in comment blocks
   that occur after the first line of code.
 
-### Supported Comment Types ###
+#### Supported Comment Types
 
 The directive processor understands comment blocks in three formats:
 
-    /* Multi-line comment blocks (CSS, SCSS, JavaScript)
-     *= require foo
-     */
+``` css
+/* Multi-line comment blocks (CSS, SCSS, JavaScript)
+ *= require foo
+ */
+```
 
-    // Single-line comment blocks (SCSS, JavaScript)
-    //= require foo
+``` js
+// Single-line comment blocks (SCSS, JavaScript)
+//= require foo
+```
 
-    # Single-line comment blocks (CoffeeScript)
-    #= require foo
+``` coffee
+# Single-line comment blocks (CoffeeScript)
+#= require foo
+```
 
-## Sprockets Directives ##
+### Sprockets Directives
 
 You can use the following directives to declare dependencies in asset
 source files.
@@ -301,65 +305,278 @@ 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 ###
+#### 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 ###
+#### 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 ###
+#### The `require_self` Directive
 
 `require_self` tells Sprockets to insert the body of the current
-source file before any subsequent `require` or `include` directives.
+source file before any subsequent `require` directives.
+
+#### The `link` Directive
+
+`link` *path* declares a dependency on the target *path* and adds it to a list
+of subdependencies to automatically be compiled when the asset is written out to
+disk.
+
+For an example, in a CSS file you might reference an external image that always
+needs to be compiled along with the css file.
+
+``` css
+/*= link "logo.png" */
+.logo {
+  background-image: url(logo.png)
+}
+```
 
-### The `depend_on` Directive ###
+However, if you use a `asset-path` or `asset-url` SCSS helper, these links will
+automatically be defined for you.
+
+``` css
+.logo {
+  background-image: asset-url("logo.png")
+}
+```
+
+#### 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.
 
-### The `stub` Directive ###
+#### The `depend_on_asset` Directive
+
+`depend_on_asset` *path* works like `depend_on`, but operates
+recursively reading the file and following the directives found. This is automatically implied if you use `link`, so consider if it just makes sense using `link` instead of `depend_on_asset`.
+
+#### The `stub` Directive
 
 `stub` *path* allows dependency to be excluded from the asset bundle.
 The *path* must be a valid asset and may or may not already be part
-of the bundle. Once stubbed, it is blacklisted and can't be brought
-back by any other `require`.
+of the bundle. `stub` should only be used at the top level bundle, not
+within any subdependencies.
+
 
-# Development #
+## Processor Interface
 
-## Contributing ##
+Sprockets 2.x was originally design around [Tilt](https://github.com/rtomayko/tilt)'s engine interface. However, starting with 3.x, a new interface has been introduced deprecating Tilt.
+
+Similar to Rack, a processor is a any "callable" (an object that responds to `call`). This maybe a simple Proc or a full class that defines a `def self.call(input)` method. The `call` method accepts an `input` Hash and returns a Hash of metadata.
+
+Also see [`Sprockets::ProcessorUtils`](https://github.com/rails/sprockets/blob/master/lib/sprockets/processor_utils.rb) for public helper methods.
+
+### input Hash
+
+The `input` Hash defines the following public fields.
+
+* `:data` - String asset contents
+* `:environment` - Current `Sprockets::Environment` instance.
+* `:cache` - A `Sprockets::Cache` instance. See [`Sprockets::Cache#fetch`](https://github.com/rails/sprockets/blob/master/lib/sprockets/cache.rb).
+* `:uri` - String Asset URI.
+* `:filename` - String full path to original file.
+* `:load_path` - String current load path for filename.
+* `:name` - String logical path for filename.
+* `:content_type` - String content type of the output asset.
+* `:metadata` - Hash of processor metadata.
+
+``` ruby
+def self.call(input)
+  input[:cache].fetch("my:cache:key:v1") do
+    # Remove all semicolons from source
+    input[:data].gsub(";", "")
+  end
+end
+```
+
+### return Hash
+
+The processor should return metadata `Hash`. With the exception of the `:data` key, the processor can store arbitrary JSON valid values in this Hash. The data will be stored and exposed on `Asset#metadata`.
+
+The returned `:data` replaces the assets `input[:data]` to the next processor in the chain. Returning a `String` is shorthand for returning `{ data: str }`. And returning `nil` is shorthand for a no-op where the input data is not transformed, `{ data: input[:data] }`.
+
+### metadata
+
+The metadata Hash provides an open format for processors to extend the pipeline processor. Internally, built-in processors use it for passing data to each other.
+
+* `:required` - A `Set` of String Asset URIs that the Bundle processor should concatenate together.
+* `:stubbed` - A `Set` of String Asset URIs that will be omitted from the `:required` set.
+* `:links` - A `Set` of String Asset URIs that should be compiled along with this asset.
+* `:dependencies` - A `Set` of String Cache URIs that should be monitored for caching.
+
+``` ruby
+def self.call(input)
+  # Any metadata may start off as nil, so initialize it the value
+  required = Set.new(input[:metadata][:required])
+
+  # Manually add "foo.js" asset uri to our bundle
+  required << input[:environment].resolve("foo.js")
+
+  { required: required }
+end
+```
+
+
+## Development
+
+### Contributing
 
 The Sprockets source code is [hosted on
-GitHub](https://github.com/sstephenson/sprockets). You can check out a
+GitHub](https://github.com/rails/sprockets). You can check out a
 copy of the latest code using Git:
 
-    $ git clone https://github.com/sstephenson/sprockets.git
+    $ git clone https://github.com/rails/sprockets
 
 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
+tracker](https://github.com/rails/sprockets/issues). Or, clone
 the Sprockets repository, write a failing test case, fix the bug and
 submit a pull request.
 
-## Version History ##
+### Version History
+
+**3.0.0**
+
+* New processor API. Tilt interface is deprecated.
+* Improved file store caching backend.
+* MIME Types now accept charset custom charset detecters. Improves support for UTF-16/32 files.
+* Environment#version no longer affects asset digests. Only used for busting the asset cache.
+* Removed builtin support for LESS.
+* Removed `//= include` directive support.
+* Deprecated `BundledAsset#to_a`. Use `BundledAsset#included` to access debugging subcomponents.
+* Support circular dependencies. For parity with ES6 modules.
+* Manifest compilation will no longer generate .gz files by default. [Mixing
+  Content-Encoding and ETags is just a bad
+  idea](https://issues.apache.org/bugzilla/show_bug.cgi?id=39727)
+* Added linked or referenced assets. When an asset is compiled, any of its links will be compiled as well.
+* Introduce some limitations around enumerating all logical paths. 4.x will deprecate it and favor linked manifests for compliation.
+* Add Asset integrity attribute for Subresource Integrity
+* Default digest changed to SHA256. Configuring `digest_class` is deprecated.
+* Rename `Asset#digest` to `Asset#hexdigest`. `Asset#digest` is deprecated and will
+  return a raw byte String in 4.x.
+* Added transitional compatibility flag to `Environment#resolve(path, compat: true)`. 2.x mode operates with `compat: true` and 4.x with `compat: false`
+* `manifest-abc123.json` renamed to `.sprockets-abc123.json`
+
+**2.12.3** (October 28, 2014)
+
+* Security: Fix directory traversal bug in development mode server.
+
+**2.12.2** (September 5, 2014)
+
+* Ensure internal asset lookups calls are still restricted to load paths within
+  asset compiles. Though, you should not depend on internal asset resolves to be
+  completely restricted for security reasons. Assets themselves should be
+  considered full scripting environments with filesystem access.
+
+**2.12.1** (April 17, 2014)
+
+* Fix making manifest target directory when its different than the output directory.
+
+**2.12.0** (March 13, 2014)
+
+* Avoid context reference in SassImporter hack so its Marshallable. Fixes
+ issues with Sass 3.3.x.
+
+**2.11.0** (February 19, 2014)
+
+* Cache store must now be an LRU implementation.
+* Default digest changed to SHA1. To continue using MD5.
+  `env.digest_class = Digest::MD5`.
+
+**2.10.0** (May 24, 2013)
+
+* Support for `bower.json`
+
+**2.9.3** (April 20, 2013)
+
+* Fixed sass caching bug
+
+**2.9.2** (April 8, 2013)
+
+* Improve file freshness check performance
+* Directive processor encoding fixes
+
+**2.9.1** (April 6, 2013)
+
+* Support for Uglifier 2.x
+
+**2.9.0** (February 25, 2013)
+
+* Write out gzipped variants of bundled assets.
+
+**2.8.2** (December 10, 2012)
+
+* Fixed top level Sass constant references
+* Fixed manifest logger when environment is disabled
+
+**2.8.1** (October 31, 2012)
+
+* Fixed Sass importer bug
+
+**2.8.0** (October 16, 2012)
+
+* Allow manifest location to be separated from output directory
+* Pass logical path and absolute path to each_logical_path iterator
+
+**2.7.0** (October 10, 2012)
+
+* Added --css-compressor and --js-compressor command line flags
+* Added css/js compressor shorthand
+* Change default manifest.json filename to be a randomized manifest-16HEXBYTES.json
+* Allow nil environment to be passed to manifest
+* Allow manifest instance to be set on rake task
+
+**2.6.0** (September 19, 2012)
+
+* Added bower component.json require support
+
+**2.5.0** (September 4, 2012)
+
+* Fixed Ruby 2.0 RegExp warning
+* Provide stubbed implementation of context *_path helpers
+* Add SassCompressor
+
+**2.4.5** (July 10, 2012)
+
+* Tweaked some logger levels
+
+**2.4.4** (July 2, 2012)
+
+* Canonicalize logical path extensions
+* Check absolute paths passed to depend_on
+
+**2.4.3** (May 16, 2012)
+
+* Exposed :sprockets in sass options
+* Include dependency paths in asset mtime
+
+**2.4.2** (May 7, 2012)
+
+* Fixed MultiJson feature detect
+
+**2.4.1** (April 26, 2012)
+
+* Fixed MultiJson API change
+* Fixed gzip mtime
+
+**2.4.0** (March 27, 2012)
+
+* Added global path registry
+* Added global processor registry
 
 **2.3.2** (March 26, 2012)
 
@@ -385,7 +602,7 @@ submit a pull request.
 
 **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.
+* Disabled If-Modified-Since server checks. Fixes some browser caching issues when serving the asset body only. If-None-Match caching is sufficient.
 
 **2.1.1** (November 18, 2011)
 
@@ -416,11 +633,11 @@ submit a pull request.
 
 * Initial public release.
 
-# License #
+## License
 
-Copyright &copy; 2011 Sam Stephenson <<sstephenson@gmail.com>>
+Copyright &copy; 2014 Sam Stephenson <<sstephenson@gmail.com>>
 
-Copyright &copy; 2011 Joshua Peek <<josh@joshpeek.com>>
+Copyright &copy; 2014 Joshua Peek <<josh@joshpeek.com>>
 
 Sprockets is distributed under an MIT-style license. See LICENSE for
 details.