sass4 4.0.0

data/CONTRIBUTING.md

@@ -0,0 +1,148 @@
+Contributions are welcomed. Please see the following site for guidelines:
+
+[https://sass-lang.com/community#Contribute](https://sass-lang.com/community#Contribute)
+
+* [Branches](#main-development-branches)
+  * [Feature Branches](#feature-branches)
+  * [Experimental Branches](#experimental-branches)
+  * [Old Stable Branches](#old-stable-branches)
+* [Versioning](#versioning)
+  * [Making Breaking Changes](#making-breaking-changes)
+  * [Exceptional Breakages](#exceptional-breakages)
+
+## Branches
+
+The Sass repository has three primary development branches, each of which tracks
+a different line of releases (see [versioning](#versioning) below). Each branch
+is regularly merged into the one below: `stable` into `next`, `next` into
+`master`.
+
+* The `stable` branch is the default—it's what GitHub shows if you go to
+  [sass/ruby-sass](https://github.com/sass/ruby-sass), and it's the default place for pull
+  requests to go. This branch is where we work on the next patch release. Bug
+  fixes and documentation improvements belong here, but not new features.
+
+* The `next` branch is where we work on the next minor release. It's where most
+  new features go, as long as they're not breaking changes. Very occasionally
+  breaking changes will go here as well—see
+  [exceptional breakages](#exceptional-breakages) below for details.
+
+* The `master` branch is where we work on the next major release. It's where
+  breaking changes go. We also occasionally decide that a non-breaking feature
+  is big enough to warrant saving until the next major release, in which case it
+  will also be developed here.
+
+Ideally, pull requests would be made against the appropriate
+branch, but don't worry about it too much; if you make a request against the
+wrong branch, the maintainer will take responsibility for rebasing it before
+merging.
+
+### Testing
+
+Tests for changes to the Sass language go in
+[sass-spec](https://github.com/sass/sass-spec) so that other
+implementations (E.g. libSass) can be tested against the same test
+suite. The sass-spec repo follows a "trunk development" model in that
+the tests there test against different version of the Sass language (as
+opposed to having branches that track different Sass versions). When
+contributing changes to Sass, update the Gemfile to use sass-spec from a
+branch or fork that has the new tests. When the feature lands in Sass,
+the committer will also merge the corresponding sass-spec changes.
+
+The [documentation of
+sass-spec](https://github.com/sass/sass-spec/blob/master/README.md)
+explains how to run sass-spec and contribute changes. In development,
+Change the Gemfile(s) to use the `:path` option against the sass-spec gem
+to link your local checkout of sass and sass-spec together in one or
+both directions.
+
+Changes to Sass internals or Ruby Sass specific features (E.g.
+the `sass-convert` tool) should always have tests in the Sass `test`
+directory following the conventions you see there.
+
+### Feature Branches
+
+Sometimes it won't be possible to merge a new feature into `next` or `master`
+immediately. It may require longer-term work before it's complete, or we may not
+want to release it as part of any alpha releases of the branch in question.
+Branches like this are labeled `feature.#{name}` and stay on GitHub until
+they're ready to be merged.
+
+### Experimental Branches
+
+Not all features pan out, and not all code is a good fit for merging into the
+main codebase. Usually when this happens the code is just discarded, but every
+so often it's interesting or promising enough that it's worth keeping around.
+This is what experimental branches (labeled `experimental.#{name}`) are for.
+While they're not currently in use, they contain code that might be useful in
+the future.
+
+### Old Stable Branches
+
+Usually Sass doesn't have the development time to do long-term maintenance of
+old release. But occasionally, very rarely, it becomes necessary. In cases like
+that, a branch named `stable_#{version}` will be created, starting from the last
+tag in that version series.
+
+## Versioning
+
+Starting with version 3.5.0, Sass uses [semantic versioning](http://semver.org/)
+to indicate the evolution of its language semantics as much as possible. This
+means that patch releases (such as 3.5.3) contain only bug fixes, minor releases
+(such as 3.6.0) contain backwards-compatible features, and only major releases
+(such as 4.0.0) are allowed to have backwards-incompatible behavior. There are
+[exceptions](#exceptional-breakages), but we try to follow this rule as closely
+as possible.
+
+Note, however, that the semantic versioning applies only to the language's
+semantics, not to the Ruby APIs. Although we try hard to keep widely-used APIs
+like [`Sass::Engine`][Sass::Engine] stable, we don't have a strong distinction
+between public and private APIs and we need to be able to freely refactor our
+code.
+
+[Sass::Engine]: https://sass-lang.com/documentation/Sass/Engine.html
+
+### Making Breaking Changes
+
+Sometimes the old way of doing something just isn't going to work anymore, and
+the new way just can't be made backwards-compatible. In that case, a breaking
+change is necessary. These changes are rarely pleasant, but they contribute to
+making the language better in the long term.
+
+Our breaking change process tries to make such changes as clear to users and as
+easy to adapt to as possible. We want to ensure that there's a clear path
+forward for users using functionality that will no longer exist, and that they
+are able to understand what's changing and what they need to do. We've developed
+the following process for this:
+
+1. Deprecate the old behavior [in `stable`](#branches). At minimum, deprecating
+   some behavior involves printing a warning when that behavior is used
+   explaining that it's going to go away in the future. Ideally, this message
+   will also include code that will do the same thing in a non-deprecated way.
+   If there's a thorough prose explanation of the change available online, the
+   message should link to that as well.
+
+2. If possible, make `sass-convert` (also in `stable`) convert the deprecated
+   behavior into a non-deprecated form. This allows users to run `sass-convert
+   -R -i` to automatically update their stylesheets.
+
+3. Implement the new behavior in `master`. The sooner this happens, the better:
+   it may be unclear exactly what needs to be deprecated until the new
+   implementation exists.
+
+4. Release an alpha version of `master` that includes the new behavior. This
+   allows users who are dissatisfied with the workaround to use the new
+   behavior early. Normally a maintainer will take care of this.
+
+### Exceptional Breakages
+
+Because Sass's syntax and semantics are closely tied to those of CSS, there are
+occasionally times when CSS syntax is introduced that overlaps with
+previously-valid Sass. In this case in particular, we may introduce a breaking
+change in a minor version to get back to CSS compatibility as soon as possible.
+
+Exceptional breakages still require the full deprecation process; the only
+change is that the new behavior is implemented in `next` rather than `master`.
+Because there are no minor releases between the deprecation and the removal of
+the old behavior, the deprecation warning should be introduced soon as it
+becomes clear that an exceptional breakage is necessary.

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2006-2016 Hampton Catlin, Natalie Weizenbaum, and Chris Eppstein
+
+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,242 @@
+## Ruby Sass Has Reached End-of-Life
+
+Ruby Sass should no longer be used, and will no longer be receiving any updates.
+See [the Sass blog][], and consider switching to the [`sassc` gem].
+
+[the Sass blog]: https://sass-lang.com/blog/posts/7828841
+[`sassc` gem]: https://rubygems.org/gems/sassc
+
+## Requirements
+
+- **Ruby**: >= 3.0.0 (recommended: Ruby 3.1.2+)
+- **Bundler**: For dependency management
+
+This project has been updated for compatibility with modern Ruby versions.
+
+# Sass [![Travis Build Status](https://travis-ci.org/sass/ruby-sass.svg?branch=next)](https://travis-ci.org/sass/ruby-sass) [![Gem Version](https://badge.fury.io/rb/sass.svg)](http://badge.fury.io/rb/sass) [![Inline docs](http://inch-ci.org/github/sass/sass.svg)](http://inch-ci.org/github/sass/sass)
+
+**Sass makes CSS fun again**. Sass is an extension of CSS,
+adding nested rules, variables, mixins, selector inheritance, and more.
+It's translated to well-formatted, standard CSS
+using the command line tool or a web-framework plugin.
+
+Sass has two syntaxes. The new main syntax (as of Sass 3)
+is known as "SCSS" (for "Sassy CSS"),
+and is a superset of CSS's syntax.
+This means that every valid CSS stylesheet is valid SCSS as well.
+SCSS files use the extension `.scss`.
+
+The second, older syntax is known as the indented syntax (or just "Sass").
+Inspired by Haml's terseness, it's intended for people
+who prefer conciseness over similarity to CSS.
+Instead of brackets and semicolons,
+it uses the indentation of lines to specify blocks.
+Although no longer the primary syntax,
+the indented syntax will continue to be supported.
+Files in the indented syntax use the extension `.sass`.
+
+## Using
+
+Sass can be used from the command line
+or as part of a web framework.
+The first step is to install the gem:
+
+    gem install sass
+
+After you convert some CSS to Sass, you can run
+
+    sass style.scss
+
+to compile it back to CSS.
+For more information on these commands, check out
+
+    sass --help
+
+To install Sass in Rails 2,
+just add `config.gem "sass"` to `config/environment.rb`.
+In Rails 3, add `gem "sass"` to your Gemfile instead.
+`.sass` or `.scss` files should be placed in `public/stylesheets/sass`,
+where they'll be automatically compiled
+to corresponding CSS files in `public/stylesheets` when needed
+(the Sass template directory is customizable...
+see [the Sass reference](https://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#template_location-option) for details).
+
+Sass can also be used with any Rack-enabled web framework.
+To do so, just add
+
+```ruby
+require 'sass/plugin/rack'
+use Sass::Plugin::Rack
+```
+
+to `config.ru`.
+Then any Sass files in `public/stylesheets/sass`
+will be compiled into CSS files in `public/stylesheets` on every request.
+
+To use Sass programmatically,
+check out the [YARD documentation](https://sass-lang.com/documentation/file.SASS_REFERENCE.html#using_sass).
+
+## Formatting
+
+Sass is an extension of CSS
+that adds power and elegance to the basic language.
+It allows you to use [variables][vars], [nested rules][nested],
+[mixins][mixins], [inline imports][imports],
+and more, all with a fully CSS-compatible syntax.
+Sass helps keep large stylesheets well-organized,
+and get small stylesheets up and running quickly,
+particularly with the help of
+[the Compass style library](http://compass-style.org).
+
+[vars]:    https://sass-lang.com/documentation/file.SASS_REFERENCE.html#variables_
+[nested]:  https://sass-lang.com/documentation/file.SASS_REFERENCE.html#nested_rules
+[mixins]:  https://sass-lang.com/documentation/file.SASS_REFERENCE.html#mixins
+[imports]: https://sass-lang.com/documentation/file.SASS_REFERENCE.html#import
+
+Sass has two syntaxes.
+The one presented here, known as "SCSS" (for "Sassy CSS"),
+is fully CSS-compatible.
+The other (older) syntax, known as the indented syntax or just "Sass",
+is whitespace-sensitive and indentation-based.
+For more information, see the [reference documentation][syntax].
+
+[syntax]: https://sass-lang.com/documentation/file.SASS_REFERENCE.html#syntax
+
+To run the following examples and see the CSS they produce,
+put them in a file called `test.scss` and run `sass test.scss`.
+
+### Nesting
+
+Sass avoids repetition by nesting selectors within one another.
+The same thing works for properties.
+
+```scss
+table.hl {
+  margin: 2em 0;
+  td.ln { text-align: right; }
+}
+
+li {
+  font: {
+    family: serif;
+    weight: bold;
+    size: 1.2em;
+  }
+}
+```
+
+### Variables
+
+Use the same color all over the place?
+Need to do some math with height and width and text size?
+Sass supports variables, math operations, and many useful functions.
+
+```scss
+$blue: #3bbfce;
+$margin: 16px;
+
+.content_navigation {
+  border-color: $blue;
+  color: darken($blue, 10%);
+}
+
+.border {
+  padding: $margin / 2;
+  margin: $margin / 2;
+  border-color: $blue;
+}
+```
+
+### Mixins
+
+Even more powerful than variables,
+mixins allow you to re-use whole chunks of CSS,
+properties or selectors.
+You can even give them arguments. 
+
+```scss
+@mixin table-scaffolding {
+  th {
+    text-align: center;
+    font-weight: bold;
+  }
+  td, th { padding: 2px; }
+}
+
+@mixin left($dist) {
+  float: left;
+  margin-left: $dist;
+}
+
+#data {
+  @include left(10px);
+  @include table-scaffolding;
+}
+```
+
+A comprehensive list of features is available
+in the [Sass reference](https://sass-lang.com/documentation/file.SASS_REFERENCE.html).
+
+## Executables
+
+The Sass gem includes several executables that are useful
+for dealing with Sass from the command line.
+
+### `sass`
+
+The `sass` executable transforms a source Sass file into CSS.
+See `sass --help` for further information and options.
+
+### `sass-convert`
+
+The `sass-convert` executable converts between CSS, Sass, and SCSS.
+When converting from CSS to Sass or SCSS,
+nesting is applied where appropriate.
+See `sass-convert --help` for further information and options.
+
+### Running locally
+
+To run the Sass executables from a source checkout instead of from rubygems:
+
+```
+$ cd sass
+$ bundle
+$ bundle exec sass ...
+$ bundle exec scss ...
+$ bundle exec sass-convert ...
+```
+
+## Authors
+
+Sass was envisioned by [Hampton Catlin](http://www.hamptoncatlin.com)
+(@hcatlin). However, Hampton doesn't even know his way around the code anymore
+and now occasionally consults on the language issues. Hampton lives in San
+Francisco, California and works as VP of Technology
+at [Moovweb](http://www.moovweb.com/).
+
+[Natalie Weizenbaum](https://twitter.com/nex3) is the primary developer and
+architect of Sass. Her hard work has kept the project alive by endlessly
+answering forum posts, fixing bugs, refactoring, finding speed improvements,
+writing documentation, implementing new features, and designing the language.
+Natalie lives in Seattle, Washington and works on [Dart](http://dartlang.org)
+application libraries at Google.
+
+[Chris Eppstein](http://twitter.com/chriseppstein) is a core contributor to
+Sass and the creator of [Compass](http://compass-style.org/), the first Sass-based framework, and
+[Eyeglass](http://github.com/sass-eyeglass/eyeglass), a node-sass plugin ecosystem for NPM. Chris focuses
+on making Sass more powerful, easy to use, and on ways to speed its adoption
+through the web development community. Chris lives in San Jose, California with
+his wife and two children. He is an Engineer for
+[LinkedIn.com](http://linkedin.com), where his primary responsibility is to
+maintain Sass and many other Sass-related open source projects.
+
+If you use this software, we'd be truly honored if you'd make a
+tax-deductible donation to a non-profit organization and then
+[let us know on twitter](http://twitter.com/SassCSS), so that we can
+thank you. Here's a few that we endorse:
+
+* [Trans Justice Funding Project](http://www.transjusticefundingproject.org/)
+* [United Mitochondrial Disease Foundation](http://umdf.org/compass)
+* [Girl Develop It](https://www.girldevelopit.com/donate)
+
+Sass is licensed under the MIT License.

data/VERSION

@@ -0,0 +1 @@
+4.0.0

data/VERSION_NAME

@@ -0,0 +1 @@
+Bleeding Edge

data/bin/sass

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+# The command line Sass parser.
+
+THIS_FILE = File.symlink?(__FILE__) ? File.readlink(__FILE__) : __FILE__
+begin
+  require File.dirname(THIS_FILE) + '/../lib/sass'
+rescue LoadError
+  require 'sass'
+end
+require 'sass/exec'
+
+opts = Sass::Exec::SassScss.new(ARGV, :sass)
+opts.parse!

data/bin/sass-convert

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+
+THIS_FILE = File.symlink?(__FILE__) ? File.readlink(__FILE__) : __FILE__
+begin
+  require File.dirname(THIS_FILE) + '/../lib/sass'
+rescue LoadError
+  require 'sass'
+end
+require 'sass/exec'
+
+opts = Sass::Exec::SassConvert.new(ARGV)
+opts.parse!

data/bin/scss

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+# The command line Sass parser.
+
+THIS_FILE = File.symlink?(__FILE__) ? File.readlink(__FILE__) : __FILE__
+begin
+  require File.dirname(THIS_FILE) + '/../lib/sass'
+rescue LoadError
+  require 'sass'
+end
+require 'sass/exec'
+
+opts = Sass::Exec::SassScss.new(ARGV, :scss)
+opts.parse!

data/extra/sass-spec-ref.sh

@@ -0,0 +1,40 @@
+#!/bin/bash -e
+# Copyright 2016 Google Inc. Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+
+# Echoes the sass-spec Git ref that should be checked out for the current Travis
+# run. If we're running specs for a pull request which refers to a sass-spec
+# pull request, we'll run against the latter rather than sass-spec master.
+
+default=master
+
+if [ "$TRAVIS_PULL_REQUEST" == "false" ]; then
+  >&2 echo "TRAVIS_PULL_REQUEST: $TRAVIS_PULL_REQUEST."
+  >&2 echo "Ref: $default."
+  echo "$default"
+  exit 0
+fi
+
+>&2 echo "Fetching pull request $TRAVIS_PULL_REQUEST..."
+
+url=https://api.github.com/repos/sass/ruby-sass/pulls/$TRAVIS_PULL_REQUEST
+if [ -z "$GITHUB_AUTH" ]; then
+    >&2 echo "Fetching pull request info without authentication"
+    JSON=$(curl -L -sS $url)
+else
+    >&2 echo "Fetching pull request info as sassbot"
+    JSON=$(curl -u "sassbot:$GITHUB_AUTH" -L -sS $url)
+fi
+>&2 echo "$JSON"
+
+RE_SPEC_PR="sass\/sass-spec(#|\/pull\/)([0-9]+)"
+
+if [[ $JSON =~ $RE_SPEC_PR ]]; then
+  ref="pull/${BASH_REMATCH[2]}/head"
+  >&2 echo "Ref: $ref."
+  echo "$ref"
+else
+  >&2 echo "Ref: $default."
+  echo "$default"
+fi

data/extra/update_watch.rb

@@ -0,0 +1,13 @@
+require 'rubygems'
+require 'sinatra'
+require 'json'
+set :port, 3124
+set :environment, :production
+enable :lock
+Dir.chdir(File.dirname(__FILE__) + "/..")
+
+post "/" do
+  puts "Received payload!"
+  puts "Rev: #{`git name-rev HEAD`.strip}"
+  system %{rake handle_update --trace REF=#{JSON.parse(params["payload"])["ref"].inspect}}
+end

data/init.rb

@@ -0,0 +1,18 @@
+begin
+  require File.join(File.dirname(__FILE__), 'lib', 'sass') # From here
+rescue LoadError
+  begin
+    require 'sass' # From gem
+  rescue LoadError => e
+    # gems:install may be run to install Haml with the skeleton plugin
+    # but not the gem itself installed.
+    # Don't die if this is the case.
+    raise e unless defined?(Rake) &&
+      (Rake.application.top_level_tasks.include?('gems') ||
+        Rake.application.top_level_tasks.include?('gems:install'))
+  end
+end
+
+# Load Sass.
+# Sass may be undefined if we're running gems:install.
+require 'sass/plugin' if defined?(Sass)

data/lib/sass/cache_stores/base.rb

@@ -0,0 +1,88 @@
+module Sass
+  module CacheStores
+    # An abstract base class for backends for the Sass cache.
+    # Any key-value store can act as such a backend;
+    # it just needs to implement the
+    # \{#_store} and \{#_retrieve} methods.
+    #
+    # To use a cache store with Sass,
+    # use the {file:SASS_REFERENCE.md#cache_store-option `:cache_store` option}.
+    #
+    # @abstract
+    class Base
+      # Store cached contents for later retrieval
+      # Must be implemented by all CacheStore subclasses
+      #
+      # Note: cache contents contain binary data.
+      #
+      # @param key [String] The key to store the contents under
+      # @param version [String] The current sass version.
+      #                Cached contents must not be retrieved across different versions of sass.
+      # @param sha [String] The sha of the sass source.
+      #                Cached contents must not be retrieved if the sha has changed.
+      # @param contents [String] The contents to store.
+      def _store(key, version, sha, contents)
+        raise "#{self.class} must implement #_store."
+      end
+
+      # Retrieved cached contents.
+      # Must be implemented by all subclasses.
+      #
+      # Note: if the key exists but the sha or version have changed,
+      # then the key may be deleted by the cache store, if it wants to do so.
+      #
+      # @param key [String] The key to retrieve
+      # @param version [String] The current sass version.
+      #                Cached contents must not be retrieved across different versions of sass.
+      # @param sha [String] The sha of the sass source.
+      #                Cached contents must not be retrieved if the sha has changed.
+      # @return [String] The contents that were previously stored.
+      # @return [NilClass] when the cache key is not found or the version or sha have changed.
+      def _retrieve(key, version, sha)
+        raise "#{self.class} must implement #_retrieve."
+      end
+
+      # Store a {Sass::Tree::RootNode}.
+      #
+      # @param key [String] The key to store it under.
+      # @param sha [String] The checksum for the contents that are being stored.
+      # @param root [Object] The root node to cache.
+      def store(key, sha, root)
+        _store(key, Sass::VERSION, sha, Marshal.dump(root))
+      rescue TypeError, LoadError => e
+        Sass::Util.sass_warn "Warning. Error encountered while saving cache #{path_to(key)}: #{e}"
+        nil
+      end
+
+      # Retrieve a {Sass::Tree::RootNode}.
+      #
+      # @param key [String] The key the root element was stored under.
+      # @param sha [String] The checksum of the root element's content.
+      # @return [Object] The cached object.
+      def retrieve(key, sha)
+        contents = _retrieve(key, Sass::VERSION, sha)
+        Marshal.load(contents) if contents
+      rescue EOFError, TypeError, ArgumentError, LoadError => e
+        Sass::Util.sass_warn "Warning. Error encountered while reading cache #{path_to(key)}: #{e}"
+        nil
+      end
+
+      # Return the key for the sass file.
+      #
+      # The `(sass_dirname, sass_basename)` pair
+      # should uniquely identify the Sass document,
+      # but otherwise there are no restrictions on their content.
+      #
+      # @param sass_dirname [String]
+      #   The fully-expanded location of the Sass file.
+      #   This corresponds to the directory name on a filesystem.
+      # @param sass_basename [String] The name of the Sass file that is being referenced.
+      #   This corresponds to the basename on a filesystem.
+      def key(sass_dirname, sass_basename)
+        dir = Digest::SHA1.hexdigest(sass_dirname)
+        filename = "#{sass_basename}c"
+        "#{dir}/#{filename}"
+      end
+    end
+  end
+end

data/lib/sass/cache_stores/chain.rb

@@ -0,0 +1,34 @@
+module Sass
+  module CacheStores
+    # A meta-cache that chains multiple caches together.
+    # Specifically:
+    #
+    # * All `#store`s are passed to all caches.
+    # * `#retrieve`s are passed to each cache until one has a hit.
+    # * When one cache has a hit, the value is `#store`d in all earlier caches.
+    class Chain < Base
+      # Create a new cache chaining the given caches.
+      #
+      # @param caches [Array<Sass::CacheStores::Base>] The caches to chain.
+      def initialize(*caches)
+        @caches = caches
+      end
+
+      # @see Base#store
+      def store(key, sha, obj)
+        @caches.each {|c| c.store(key, sha, obj)}
+      end
+
+      # @see Base#retrieve
+      def retrieve(key, sha)
+        @caches.each_with_index do |c, i|
+          obj = c.retrieve(key, sha)
+          next unless obj
+          @caches[0...i].each {|prev| prev.store(key, sha, obj)}
+          return obj
+        end
+        nil
+      end
+    end
+  end
+end