spritely 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9a3b754bc1e6fd1111a7eab9259f7239e45e4c4d
-  data.tar.gz: 03f79678a60dd3967883a42828956e7b74074eb4
+  metadata.gz: 667e7648ac4d154e6ec6f9a98b08f1f50a2aae93
+  data.tar.gz: 8ce617668fea3fc218ac4bff2aad24988ba9bdc1
 SHA512:
-  metadata.gz: 1fd3cba6154c6c96082e4c06331de30838f42edddf3607c462617a5e5ced06a2194ee5319092702a66656f71bcea910c1260598daab3fb57da4e72debea22b36
-  data.tar.gz: 2af4928b574b2dbcba9d3bad26332a92a67dad95b767857fb02db5c41f798c1e7111e799e98d4134866d67ebbc5716d088319182c2a6f13a3eecb6df14a586e9
+  metadata.gz: 0b8fb5a5c96ebb17a0c3aefca9a4081f4036c259b182b82cbcfb37085b64da7f10cea73aa1c9b10bd74a0afc4a24ede9ca431ac8db8853559024236ef46aea82
+  data.tar.gz: ac6fc8c395a4a934217090846e458347cc6d150c09dca1ff87000dd6df91191662e0dca3eba6861da2356f5b2ce8a885224c024d9e9f1479df6ceeb9fe156c3c

data/lib/spritely/cache.rb

@@ -1,6 +1,15 @@
 require 'digest/md5'
 
 module Spritely
+  # `Cache` is responsible for generating and fetching the current sprite cache
+  # `value. It is used to determine whether to generate a new sprite map or not.
+  #
+  # Passing in a set of objects that respond to `cache_key` will generate an MD5
+  # hash that can then be stored in the image itself.
+  #
+  # Fetching an existing cache key actually reads the PNG file itself. It scans
+  # the chunks of the PNG until it finds the `cache_key` keyword, returning the
+  # subsequent value found.
   class Cache < Struct.new(:filename)
     PNG_SIGNATURE_LENGTH = 8 # http://www.w3.org/TR/PNG/#5PNG-file-signature
     PNG_INFO_LENGTH = 8 # http://www.w3.org/TR/PNG/#5DataRep

data/lib/spritely/collection.rb

@@ -1,6 +1,8 @@
 require 'spritely/image_set'
 
 module Spritely
+  # A `SpriteMap` has a `Collection` that knows how to calculate the size of the
+  # sprite, based on image repetition and spacing.
   class Collection < Struct.new(:files, :options)
     def self.create(*args)
       new(*args).tap do |collection|
@@ -20,6 +22,12 @@ module Spritely
       files.collect { |file| File.mtime(file) }.join
     end
 
+    # Returns the width of the to-be-generated sprite image. When none of the
+    # images repeat, it is simply the max width of all images in the sprite.
+    # When an image in the sprite is repeated, a calculation is performed based
+    # on the least common multiple of all repeated images. That least common
+    # multiple is then multiplied by the minimum multiple that will result in a
+    # value greater than or equal to the max width of all images in the sprite.
     def width
       return @width if @width
 
@@ -38,6 +46,8 @@ module Spritely
       heights.reduce(:+)
     end
 
+    # Upon creation, the collection is then positioned appropriately by
+    # positioning each image within the sprite.
     def position!
       image_sets.each_with_index do |image_set, index|
         image_set.top = heights[0..index].reduce(:+) - image_set.outer_height

data/lib/spritely/image_set.rb

@@ -1,6 +1,8 @@
 require 'spritely/image'
 
 module Spritely
+  # Each image in the sprite maps to an instance of `ImageSet` that stores the
+  # image data, width, height, and outer positioning.
   class ImageSet
     attr_accessor :top
     attr_reader :path, :options, :data, :width, :height, :left
@@ -37,6 +39,9 @@ module Spritely
       options[:position] == 'right'
     end
 
+    # When positioned in the sprite, we must take into account whether the image
+    # is configured to repeat, or is positioned to the right-hand side of the
+    # sprite map.
     def position_in!(collection_width)
       if repeated?
         left_position = 0

data/lib/spritely/options.rb

@@ -1,10 +1,28 @@
 require 'active_support/core_ext/hash/deep_merge'
 require 'active_support/core_ext/hash/except'
+require 'active_support/core_ext/hash/keys'
 require 'active_support/core_ext/hash/slice'
 
 module Spritely
+  # Provides a simpler method of querying a particular image's options. Rather
+  # than each `Image` needing to know how to parse the keyword arguments passed
+  # into the `spritely-map` function, this simplifies and de-duplicates the
+  # passed option keys.
+  #
+  #   $application-sprite: spritely-map("application/*.png",
+  #     $arrow-repeat: true,
+  #     $arrow-spacing: 10px,
+  #     $another-image-position: right,
+  #     $spacing: 5px
+  #   );
+  #
+  # The options passed in above will be easily accessible via an instance of
+  # this class.
+  #
+  #   options['arrow'] => {repeat: true, spacing: 10}
+  #   options['another-image'] => {position: 'right', spacing: 5}
   class Options < Struct.new(:hash)
-    GLOBAL_OPTIONS = [:spacing, :position]
+    GLOBAL_OPTIONS = ['spacing', 'position']
 
     def cache_key
       stripped_hash.to_s
@@ -15,28 +33,26 @@ module Spritely
     end
 
     def [](key)
-      options[key] || global_options
+      options[key.gsub('-', '_')] || global_options
     end
 
     private
 
     def options
       @options ||= stripped_hash.except(*GLOBAL_OPTIONS).inject({}) do |h, (key, value)|
-        split_key = key.to_s.split('_')
-        option = {split_key.pop.to_sym => value}
-        image = split_key.join('-')
+        image, _, option = key.rpartition('_')
         h[image] ||= global_options.dup
-        h.deep_merge!(image => option)
+        h.deep_merge!(image => {option.to_sym => value})
       end
     end
 
     def global_options
-      @global_options ||= stripped_hash.slice(*GLOBAL_OPTIONS)
+      @global_options ||= stripped_hash.slice(*GLOBAL_OPTIONS).symbolize_keys!
     end
 
     def stripped_hash
       @stripped_hash ||= hash.inject({}) do |h, (key, sass_object)|
-        h.merge!(key.to_sym => sass_object.value)
+        h.merge!(key => sass_object.value)
       end
     end
   end

data/lib/spritely/sass_functions.rb

@@ -30,6 +30,12 @@ module Spritely
 
     ::Sass::Script::Functions.declare :spritely_position, [:sprite_map, :image_name]
 
+    def spritely_background(sprite_map, image_name)
+      Sass::Script::List.new([spritely_url(sprite_map), spritely_position(sprite_map, image_name)], :space)
+    end
+
+    ::Sass::Script::Functions.declare :spritely_background, [:sprite_map, :image_name]
+
     def spritely_width(sprite_map, image_name)
       image = find_image(sprite_map, image_name)
 

data/lib/spritely/sprockets/manifest.rb

@@ -2,6 +2,10 @@ require 'sprockets/manifest'
 require 'active_support/core_ext/module/aliasing'
 
 module Sprockets
+  # In order to hook into Sprockets' asset compilation appropriately, we must
+  # chain our own implementation of `compile`. Our extension calls up to the
+  # original, and then performs the same action on the generated sprite images,
+  # forcing the sprites to be part of the compiled asset manifest.
   class Manifest
     def compile_with_sprites(*args)
       compile_without_sprites(*args)

data/lib/spritely/version.rb

@@ -1,3 +1,3 @@
 module Spritely
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/spec/spritely/options_spec.rb

@@ -14,8 +14,8 @@ describe Spritely::Options do
 
   subject(:options) { Spritely::Options.new(hash) }
 
-  its(:inspect) { should eq("#<Spritely::Options global_options=#{{spacing: 901, position: 'left'}} options=#{{'some-new-image' => {spacing: 789, position: 'right', x: 123, y: 456}, 'another-image' => {spacing: 901, position: 'left', repeat: true}, 'yet-another-image' => {spacing: 901, position: 'left', repeat: false}}}>") }
-  its(:cache_key) { should eq({some_new_image_spacing: 789, some_new_image_x: 123, some_new_image_y: 456, some_new_image_position: 'right', another_image_repeat: true, yet_another_image_repeat: false, spacing: 901, position: 'left'}.to_s) }
+  its(:inspect) { should eq("#<Spritely::Options global_options=#{{spacing: 901, position: 'left'}} options=#{{'some_new_image' => {spacing: 789, position: 'right', x: 123, y: 456}, 'another_image' => {spacing: 901, position: 'left', repeat: true}, 'yet_another_image' => {spacing: 901, position: 'left', repeat: false}}}>") }
+  its(:cache_key) { should eq({"some_new_image_spacing" => 789, "some_new_image_x" => 123, "some_new_image_y" => 456, "some_new_image_position" => 'right', "another_image_repeat" => true, "yet_another_image_repeat" => false, "spacing" => 901, "position" => 'left'}.to_s) }
 
   its(['some-new-image']) { should eq({spacing: 789, position: 'right', x: 123, y: 456}) }
   its(['another-image']) { should eq({spacing: 901, repeat: true, position: 'left'}) }
@@ -23,7 +23,7 @@ describe Spritely::Options do
 
   describe '#[]' do
     it 'should fall back to an empty hash' do
-      expect(options[:unknown]).to eq({spacing: 901, position: 'left'})
+      expect(options['unknown']).to eq({spacing: 901, position: 'left'})
     end
   end
 end

data/spec/spritely/sass_functions_spec.rb

@@ -6,47 +6,41 @@ describe Spritely::SassFunctions do
     def files; []; end
   end
 
+  module AssetUrlModule
+    def asset_url(path)
+      Sass::Script::String.new("url(#{path})")
+    end
+  end
+
   let(:sprite_map) { SpriteMapDouble.new }
+  let(:image) { double(left: 10, top: 12, width: 25, height: 50) }
 
-  before { allow(Spritely::SpriteMap).to receive(:create).and_return(sprite_map) }
+  before do
+    allow(Spritely::SpriteMap).to receive(:create).and_return(sprite_map)
+    allow(sprite_map).to receive(:find).with('bar').and_return(image)
+  end
 
-  shared_examples "a sprite function that checks image existence" do
-    before { allow(sprite_map).to receive(:find).with('bar').and_return(image) }
+  before(:all) { ::Sass::Script::Functions.send(:include, AssetUrlModule) }
+  after(:all) { ::Sass::Script::Functions.send(:undef_method, :asset_url) }
 
-    context 'the image does not exist' do
-      let(:image) { nil }
+  shared_examples "a sprite function that checks image existence" do
+    let(:image) { nil }
 
-      it 'should raise a nice exception' do
-        expect { subject }.to raise_error(Sass::SyntaxError, "No image 'bar' found in sprite map 'test'.")
-      end
+    it 'should raise a nice exception' do
+      expect { subject }.to raise_error(Sass::SyntaxError, "No image 'bar' found in sprite map 'test'.")
     end
   end
 
   describe '#spritely_url' do
-    before do
-      asset_url_module = Module.new do
-        def asset_url(path)
-          path
-        end
-      end
-      ::Sass::Script::Functions.send(:include, asset_url_module)
-    end
-
-    after do
-      ::Sass::Script::Functions.send(:undef_method, :asset_url)
-    end
+    subject { evaluate("spritely-url(spritely-map('test/*.png'))") }
 
-    it "should use Rails' built-in asset_url function" do
-      expect(evaluate("spritely-url(spritely-map('test/*.png'))")).to eq('sprites/test.png')
-    end
+    it { should eq('url(sprites/test.png)') }
   end
 
   describe '#spritely_position' do
-    let(:image) { double(left: 10, top: 12) }
-
     subject { evaluate("spritely-position(spritely-map('test/*.png'), 'bar')") }
 
-    include_examples "a sprite function that checks image existence"
+    it_should_behave_like "a sprite function that checks image existence"
 
     it { should eq('-10px -12px') }
 
@@ -57,22 +51,26 @@ describe Spritely::SassFunctions do
     end
   end
 
-  describe '#spritely_width' do
-    let(:image) { double(width: 25) }
+  describe '#spritely_background' do
+    subject { evaluate("spritely-background(spritely-map('test/*.png'), 'bar')") }
+
+    it_should_behave_like "a sprite function that checks image existence"
 
+    it { should eq('url(sprites/test.png) -10px -12px') }
+  end
+
+  describe '#spritely_width' do
     subject { evaluate("spritely-width(spritely-map('test/*.png'), 'bar')") }
 
-    include_examples "a sprite function that checks image existence"
+    it_should_behave_like "a sprite function that checks image existence"
 
     it { should eq('25px') }
   end
 
   describe '#spritely_height' do
-    let(:image) { double(height: 50) }
-
     subject { evaluate("spritely-height(spritely-map('test/*.png'), 'bar')") }
 
-    include_examples "a sprite function that checks image existence"
+    it_should_behave_like "a sprite function that checks image existence"
 
     it { should eq('50px') }
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: spritely
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Alex Robbin
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-06-05 00:00:00.000000000 Z
+date: 2014-06-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: chunky_png