The Sprite container is now called a Sprite Map, and each individual image is called a sprite.

frameworks/compass/stylesheets/compass/utilities/sprites/_base.scss

@@ -1,29 +1,40 @@
 // Set the width and height of an element to the original
 // dimensions of an image before it was included in the sprite.
-@mixin sprite-dimensions($sprite, $name) {
+@mixin sprite-dimensions($map, $sprite) {
-  height: image-height(sprite-file($sprite, $name));
+  height: image-height(sprite-file($map, $sprite));
-  width: image-width(sprite-file($sprite, $name));
+  width: image-width(sprite-file($map, $sprite));
 }
 
-// Set the background position of the given `$sprite` to display the
+// Set the background position of the given sprite `$map` to display the
-// image of the given `$name`. You can move the image relative to its
+// sprite of the given `$sprite` name. You can move the image relative to its
 // natural position by passing `$offset-x` and `$offset-y`.
-@mixin sprite-position($sprite, $name, $offset-x: 0, $offset-y: 0) {
+@mixin sprite-position($map, $sprite, $offset-x: 0, $offset-y: 0) {
-  background-position: sprite-position($sprite, $name, $offset-x, $offset-y);  
+  background-position: sprite-position($map, $sprite, $offset-x, $offset-y);  
 }
 
-@mixin sprite($sprite, $name, $dimensions: false, $offset-x: 0, $offset-y: 0) {
+// Include the position and (optionally) dimensions of this `$sprite`
-  @include sprite-position($sprite, $name, $offset-x, $offset-y);
+// in the given sprite `$map`. The sprite url should come from either a base
+// class or you can specify the `sprite-url` explicitly like this:
+//
+//     background: $map no-repeat;
+@mixin sprite($map, $sprite, $dimensions: false, $offset-x: 0, $offset-y: 0) {
+  @include sprite-position($map, $sprite, $offset-x, $offset-y);
   @if $dimensions {
-    @include sprite-dimensions($sprite, $name);
+    @include sprite-dimensions($map, $sprite);
   }
 }
 
-@mixin sprites($sprite, $sprite-names, $base-class: false, $dimensions: false) {
+// Generates a class for each space separated name in `$sprite-names`.
+// The class will be of the form .<map-name>-<sprite-name>.
+//
+// If a base class is provided, then each class will extend it.
+//
+// If `$dimensions` is `true`, the sprite dimensions will specified.
+@mixin sprites($map, $sprite-names, $base-class: false, $dimensions: false) {
   @each $sprite-name in $sprite-names {
-    .#{sprite-name($sprite)}-#{$sprite-name} {
+    .#{sprite-map-name($map)}-#{$sprite-name} {
       @if $base-class { @extend #{$base-class}; }
-      @include sprite($sprite, $sprite-name, $dimensions);
+      @include sprite($map, $sprite-name, $dimensions);
     }
   }
 }

lib/compass/sass_extensions/functions/sprites.rb

@@ -12,7 +12,7 @@ module Compass::SassExtensions::Functions::Sprites
     end
   end
 
-  class Sprite < Sass::Script::Literal
+  class SpriteMap < Sass::Script::Literal
 
     attr_accessor :image_names, :path, :name, :options
     attr_accessor :images, :width, :height
@@ -191,107 +191,106 @@ module Compass::SassExtensions::Functions::Sprites
 
   end
 
-  # Creates a sprite object. A sprite object, when used in a property is the same
+  # Creates a SpriteMap object. A sprite map, when used in a property is the same
   # as calling sprite-url. So the following background properties are equivalent:
   #
-  #     $sprite: sprite("icons/*.png");
+  #     $icons: sprite-map("icons/*.png");
-  #     background: sprite-url($sprite) no-repeat;
+  #     background: sprite-url($icons) no-repeat;
-  #     background: $sprite no-repeat;
+  #     background: $icons no-repeat;
   #
-  # The sprite object will generate the sprite image, if it is needed,
+  # The sprite map object will generate the sprite map image, if necessary,
   # the first time it is converted to a url. Simply constructing it has no side-effects.
-  def sprite(uri, kwargs = {})
+  def sprite_map(glob, kwargs = {})
     kwargs.extend VariableReader
-    Sprite.from_uri(uri, self, kwargs)
+    SpriteMap.from_uri(glob, self, kwargs)
   end
-  Sass::Script::Functions.declare :sprite, [:uri], :var_kwargs => true
+  Sass::Script::Functions.declare :sprite_map, [:glob], :var_kwargs => true
 
   # Returns the image and background position for use in a single shorthand property:
   #
-  #     $sprite: sprite("icons/*.png"); // contains icons/new.png among others.
+  #     $icons: sprite-map("icons/*.png"); // contains icons/new.png among others.
-  #     background: sprite-image($sprite, new) no-repeat;
+  #     background: sprite($icons, new) no-repeat;
   #
   # Becomes:
   #
   #     background: url('/images/icons.png?12345678') 0 -24px no-repeat;
-  def sprite_image(sprite, image = nil, offset_x = ZERO, offset_y = ZERO)
+  def sprite(map, sprite, offset_x = ZERO, offset_y = ZERO)
-    unless sprite.is_a?(Sprite)
+    unless map.is_a?(SpriteMap)
-      missing_sprite!("sprite-image")
+      missing_sprite!("sprite")
     end
-    unless image && image.is_a?(Sass::Script::String)
+    unless sprite.is_a?(Sass::Script::String)
-      raise Sass::SyntaxError, %Q(The second argument to sprite-image must be a sprite name. See http://beta.compass-style.org/help/tutorials/spriting/ for more information.)
+      raise Sass::SyntaxError, %Q(The second argument to sprite() must be a sprite name. See http://beta.compass-style.org/help/tutorials/spriting/ for more information.)
     end
-    url = sprite_url(sprite)
+    url = sprite_url(map)
-    position = sprite_position(sprite, image, offset_x, offset_y)
+    position = sprite_position(map, sprite, offset_x, offset_y)
     Sass::Script::List.new([url] + position.value, :space)
   end
-  Sass::Script::Functions.declare :sprite_image, [:sprite]
+  Sass::Script::Functions.declare :sprite, [:map, :sprite]
-  Sass::Script::Functions.declare :sprite_image, [:sprite, :name]
+  Sass::Script::Functions.declare :sprite, [:map, :sprite, :offset_x]
-  Sass::Script::Functions.declare :sprite_image, [:sprite, :name, :offset_x]
+  Sass::Script::Functions.declare :sprite, [:map, :sprite, :offset_x, :offset_y]
-  Sass::Script::Functions.declare :sprite_image, [:sprite, :name, :offset_x, :offset_y]
 
-  # Returns the name of a sprite
+  # Returns the name of a sprite map
-  # The name is derived from the folder than contains the sprite images.
+  # The name is derived from the folder than contains the sprites.
-  def sprite_name(sprite)
+  def sprite_map_name(map)
-    unless sprite.is_a?(Sprite)
+    unless map.is_a?(SpriteMap)
-      missing_sprite!("sprite-name")
+      missing_sprite!("sprite-map-name")
     end
-    Sass::Script::String.new(sprite.name)
+    Sass::Script::String.new(map.name)
   end
   Sass::Script::Functions.declare :sprite_name, [:sprite]
 
   # Returns the path to the original image file for the sprite with the given name
-  def sprite_file(sprite, image_name)
+  def sprite_file(map, sprite)
-    unless sprite.is_a?(Sprite)
+    unless map.is_a?(SpriteMap)
       missing_sprite!("sprite-file")
     end
-    if image = sprite.image_for(image_name.value)
+    if image = map.image_for(sprite.value)
       Sass::Script::String.new(image[:relative_file])
     else
-      missing_image!(sprite, image_name)
+      missing_image!(map, sprite)
     end
   end
-  Sass::Script::Functions.declare :sprite_file, [:sprite, :name]
+  Sass::Script::Functions.declare :sprite_file, [:map, :sprite]
     
   # Returns a url to the sprite image.
-  def sprite_url(sprite)
+  def sprite_url(map)
-    unless sprite.is_a?(Sprite)
+    unless map.is_a?(SpriteMap)
       missing_sprite!("sprite-url")
     end
-    sprite.generate
+    map.generate
-    image_url(Sass::Script::String.new("#{sprite.path}.png"))
+    image_url(Sass::Script::String.new("#{map.path}.png"))
   end
-  Sass::Script::Functions.declare :sprite_url, [:sprite]
+  Sass::Script::Functions.declare :sprite_url, [:map]
 
   # Returns the position for the original image in the sprite.
   # This is suitable for use as a value to background-position:
   #
-  #     $sprite: sprite("icons/*.png");
+  #     $icons: sprite-map("icons/*.png");
-  #     background-position: sprite-position($sprite, new);
+  #     background-position: sprite-position($icons, new);
   #
   # Might generate something like:
   #
-  #     background-position: 0 34px;
+  #     background-position: 0 -34px;
   #
   # You can adjust the background relative to this position by passing values for
-  # offset-x and offset-y:
+  # `$offset-x` and `$offset-y`:
   #
-  #     $sprite: sprite("icons/*.png");
+  #     $icons: sprite-map("icons/*.png");
-  #     background-position: sprite-position($sprite, new, 3px, -2px);
+  #     background-position: sprite-position($icons, new, 3px, -2px);
   #
   # Would change the above output to:
   #
-  #     background-position: 3px 32px;
+  #     background-position: 3px -36px;
-  def sprite_position(sprite, image_name = nil, offset_x = ZERO, offset_y = ZERO)
+  def sprite_position(map, sprite = nil, offset_x = ZERO, offset_y = ZERO)
-    unless sprite.is_a?(Sprite)
+    unless map.is_a?(SpriteMap)
       missing_sprite!("sprite-position")
     end
-    unless image_name && image_name.is_a?(Sass::Script::String)
+    unless sprite && sprite.is_a?(Sass::Script::String)
-      raise Sass::SyntaxError, %Q(The second argument to sprite-image must be a sprite name. See http://beta.compass-style.org/help/tutorials/spriting/ for more information.)
+      raise Sass::SyntaxError, %Q(The second argument to sprite-position must be a sprite name. See http://beta.compass-style.org/help/tutorials/spriting/ for more information.)
     end
-    image = sprite.image_for(image_name.value)
+    image = map.image_for(sprite.value)
     unless image
-      missing_image!(sprite, image_name)
+      missing_image!(map, sprite)
     end
     if offset_x.unit_str == "%"
       x = offset_x # CE: Shouldn't this be a percentage of the total width?
@@ -303,19 +302,23 @@ module Compass::SassExtensions::Functions::Sprites
     y = Sass::Script::Number.new(y, y == 0 ? [] : ["px"])
     Sass::Script::List.new([x, y],:space)
   end
-  Sass::Script::Functions.declare :sprite_position, [:sprite]
+  Sass::Script::Functions.declare :sprite_position, [:map]
-  Sass::Script::Functions.declare :sprite_position, [:sprite, :name]
+  Sass::Script::Functions.declare :sprite_position, [:map, :sprite]
-  Sass::Script::Functions.declare :sprite_position, [:sprite, :name, :offset_x]
+  Sass::Script::Functions.declare :sprite_position, [:map, :sprite, :offset_x]
-  Sass::Script::Functions.declare :sprite_position, [:sprite, :name, :offset_x, :offset_y]
+  Sass::Script::Functions.declare :sprite_position, [:map, :sprite, :offset_x, :offset_y]
+
+  def sprite_image(*args)
+    raise Sass::SyntaxError, %Q(The sprite-image() function has been replaced by sprite(). See http://beta.compass-style.org/help/tutorials/spriting/ for more information.)
+  end
 
 protected
 
-  def missing_image!(sprite, image_name)
+  def missing_image!(map, sprite)
-    raise Sass::SyntaxError, "No image called #{image_name} found in sprite #{sprite.path}/#{sprite.name}. Did you mean one of: #{sprite.sprite_names.join(", ")}"
+    raise Sass::SyntaxError, "No sprite called #{sprite} found in sprite map #{map.path}/#{map.name}. Did you mean one of: #{map.sprite_names.join(", ")}"
   end
 
   def missing_sprite!(function_name)
-    raise Sass::SyntaxError, %Q(The first argument to #{function_name} must be a sprite. See http://beta.compass-style.org/help/tutorials/spriting/ for more information.)
+    raise Sass::SyntaxError, %Q(The first argument to #{function_name}() must be a sprite map. See http://beta.compass-style.org/help/tutorials/spriting/ for more information.)
   end
 
 end

lib/compass/sprites.rb

@@ -57,7 +57,7 @@ $#{name}-#{sprite_name}-repeat: $#{name}-repeat !default;
 SCSS
 end.join}
 
-$#{name}-sprite: sprite("#{uri}",
+$#{name}-sprites: sprite-map("#{uri}",
 #{images.map do |sprite_name| 
 %Q{  $#{sprite_name}-position: $#{name}-#{sprite_name}-position,
   $#{sprite_name}-spacing: $#{name}-#{sprite_name}-spacing,
@@ -67,29 +67,29 @@ end.join(",\n")});
 // All sprites should extend this class
 // The #{name}-sprite mixin will do so for you.
 \#{$#{name}-sprite-base-class} {
-  background: $#{name}-sprite no-repeat;
+  background: $#{name}-sprites no-repeat;
 }
 
 // Use this to set the dimensions of an element
 // based on the size of the original image.
 @mixin #{name}-sprite-dimensions($name) {
-  @include sprite-dimensions($#{name}-sprite, $name)
+  @include sprite-dimensions($#{name}-sprites, $name)
 }
 
 // Move the background position to display the sprite.
 @mixin #{name}-sprite-position($name, $offset-x: 0, $offset-y: 0) {
-  @include sprite-position($#{name}-sprite, $name, $offset-x, $offset-y)
+  @include sprite-position($#{name}-sprites, $name, $offset-x, $offset-y)
 }
 
 // Extends the sprite base class and set the background position for the desired sprite.
 // It will also apply the image dimensions if $dimensions is true.
 @mixin #{name}-sprite($name, $dimensions: $#{name}-sprite-dimensions, $offset-x: 0, $offset-y: 0) {
   @extend \#{$#{name}-sprite-base-class};
-  @include sprite($#{name}-sprite, $name, $dimensions, $offset-x, $offset-y)
+  @include sprite($#{name}-sprites, $name, $dimensions, $offset-x, $offset-y)
 }
 
 @mixin #{name}-sprites($sprite-names, $dimensions: $#{name}-sprite-dimensions) {
-  @include sprites($#{name}-sprite, $sprite-names, $#{name}-sprite-base-class, $dimensions)
+  @include sprites($#{name}-sprites, $sprite-names, $#{name}-sprite-base-class, $dimensions)
 }
 
 // Generates a class for each sprited image.

spec/sprites_spec.rb

@@ -246,21 +246,21 @@ describe Compass::Sprites do
   
   it "should use position adjustments in functions" do
     css = render <<-SCSS
-      $squares-sprite: sprite("squares/*.png", $position: 100%);
+      $squares: sprite-map("squares/*.png", $position: 100%);
       .squares-sprite {
-        background: $squares-sprite no-repeat;
+        background: $squares no-repeat;
       }
       
       .adjusted-percentage {
-        background-position: sprite-position($squares-sprite, ten-by-ten, 100%);
+        background-position: sprite-position($squares, ten-by-ten, 100%);
       }
       
       .adjusted-px-1 {
-        background-position: sprite-position($squares-sprite, ten-by-ten, 4px);
+        background-position: sprite-position($squares, ten-by-ten, 4px);
       }
       
       .adjusted-px-2 {
-        background-position: sprite-position($squares-sprite, twenty-by-twenty, -3px, 2px);
+        background-position: sprite-position($squares, twenty-by-twenty, -3px, 2px);
       }
     SCSS
     css.should == <<-CSS
@@ -353,7 +353,7 @@ describe Compass::Sprites do
         }
       SCSS
     end.should raise_error Sass::SyntaxError,
-      %q(The first argument to sprite-url must be a sprite. See http://beta.compass-style.org/help/tutorials/spriting/ for more information.)
+      %q(The first argument to sprite-url() must be a sprite map. See http://beta.compass-style.org/help/tutorials/spriting/ for more information.)
     proc do
       render <<-SCSS
         .squares {
@@ -361,7 +361,7 @@ describe Compass::Sprites do
         }
       SCSS
     end.should raise_error Sass::SyntaxError,
-      %q(The first argument to sprite-image must be a sprite. See http://beta.compass-style.org/help/tutorials/spriting/ for more information.)
+      %q(The sprite-image() function has been replaced by sprite(). See http://beta.compass-style.org/help/tutorials/spriting/ for more information.)
     proc do
       render <<-SCSS
         @import "squares/*.png";
@@ -371,13 +371,13 @@ describe Compass::Sprites do
         }
       SCSS
     end.should raise_error Sass::SyntaxError,
-      %q(The first argument to sprite-position must be a sprite. See http://beta.compass-style.org/help/tutorials/spriting/ for more information.)
+      %q(The first argument to sprite-position() must be a sprite map. See http://beta.compass-style.org/help/tutorials/spriting/ for more information.)
   end
   
   it "should work even if @import is missing" do
     actual_css = render <<-SCSS
       .squares {
-        background: sprite-image(sprite("squares/*.png"), twenty-by-twenty) no-repeat;
+        background: sprite(sprite-map("squares/*.png"), twenty-by-twenty) no-repeat;
       }
     SCSS
     actual_css.should == <<-CSS