sprockets 3.0.0.beta.6 → 3.0.0.beta.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8efcdd68f447ff7e005fe4edd68eaae03f06f1d6
-  data.tar.gz: d0b92f39df358468d6039d3d1bb08970d271a733
+  metadata.gz: d55da847286c101c972d4726a09af4abb94d5580
+  data.tar.gz: 1a5ffd86bcfafcf7524efc61224b2e95a4bd2633
 SHA512:
-  metadata.gz: 6819d688dd19334c5f09ba24e3399fcb2a8cf5c233e6be75450d8fdeb909abfc356c68dc0a38203e07bc6a8aa636e6ccaa1868a1396fd346d5145405806ca580
-  data.tar.gz: c8d3438168908e7f72ca0f4fe68669ed3d91c237e4712be6c43970de7ccd87d5178acf7171abcbde28d448bcdf1a0c7cd73b52122abe299cbb53ddb274d7fc67
+  metadata.gz: 74bd05cb90faa8f43acbfaa7d68678d4dec71dda98a752c60a8889e3374881690aef1b414e86a3180fe843411185943339d3393d62d1e4d93c8effbb13bce094
+  data.tar.gz: c60422ed4c47b110be53585ffd66b7b8dc1080b3321585471c57cb38eedbc1d5c39272247cc4662888fa985559da2e3575bdeed9ca0b3fe404a54103802ac53f

data/README.md

@@ -5,20 +5,26 @@ 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 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', '~> 3.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,48 @@ 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
-
-    map '/' do
-      run YourRackApp
-    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
+```
 
-### 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
 `filename` 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*.
+## Using Processors
 
-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`.
+Asset source files can be written in another format, like SCSS or
+CoffeeScript, and automatically compiled to CSS or JavaScript by
+Sprockets. Processors that convert a file from one format to another are called *transformers*.
 
-## Minifying Assets ##
+### Minifying Assets
 
 Several JavaScript and CSS minifiers are available through shorthand.
 
@@ -148,7 +156,7 @@ environment.js_compressor  = :uglify
 environment.css_compressor = :scss
 ```
 
-## Styling with Sass and 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
@@ -158,10 +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`.
+whitespace-sensitive syntax, use the extension `.sass`. For the
+new SCSS syntax, use the extension `.scss`.
 
-## 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,9 +183,9 @@ 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`.
+`.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
@@ -188,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
@@ -210,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:
@@ -236,13 +241,8 @@ include:
 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
@@ -253,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
@@ -274,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.
@@ -297,7 +305,7 @@ 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
@@ -309,35 +317,35 @@ appear in the bundle only once.
 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` directives.
 
-### The `link` Directive ###
+#### 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
-need to be compiled along with the css file.
+needs to be compiled along with the css file.
 
 ``` css
-/* link "logo.png" */
+/*= link "logo.png" */
 .logo {
   background-image: url(logo.png)
 }
 ```
 
-However, if you use a `asset-path/url` SCSS helper, these links will
-automatically be setup for you.
+However, if you use a `asset-path` or `asset-url` SCSS helper, these links will
+automatically be defined for you.
 
 ``` css
 .logo {
@@ -345,33 +353,93 @@ automatically be setup for you.
 }
 ```
 
-### The `depend_on` Directive ###
+#### 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 `depend_on_asset` 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.
+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 ###
+#### 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. `stub` should only be used at the top level bundle, not
 within any subdependencies.
 
-# Development #
 
-## Contributing ##
+## Processor Interface
+
+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/sstephenson/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/sstephenson/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
 copy of the latest code using Git:
 
-    $ git clone https://github.com/sstephenson/sprockets.git
+    $ git clone https://github.com/sstephenson/sprockets
 
 If you've found a bug or have a question, please open an issue on the
 [Sprockets issue
@@ -379,25 +447,28 @@ 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 ##
+### 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.
+* 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.
+* 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
+* 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`
 
 **2.12.3** (October 28, 2014)
 
@@ -561,7 +632,7 @@ submit a pull request.
 
 * Initial public release.
 
-# License #
+## License
 
 Copyright &copy; 2014 Sam Stephenson <<sstephenson@gmail.com>>