polymer 1.0.0.beta.3 → 1.0.0.beta.4

data/History.md

@@ -21,8 +21,15 @@ v1.0.0 / HEAD (Unreleased)
         +polymer("sprite_name/source_name")
 
   Mixins still permit you to supply an optional x-offset and y-offset as
-  the second and third parameters. the "polymer-pos()" mixin is also
-  available as an alternative to the old "sprite-name-pos()" mixins.
+  the second and third parameters. the "polymer-position()" mixin is
+  also available as an alternative to the old "sprite-name-pos()"
+  mixins.
+
+* The "polymer-pos" Sass mixin, which sets only the background position
+  of a source, without including the background-image property, has been
+  renamed to "polymer-position".
+
+* The "generate" command is now "bond": `$ polymer bond`
 
 * A new "position" command shows information about a source within a
   sprite, and provides useful CSS for use when building your own

data/lib/polymer/cache.rb

@@ -4,6 +4,16 @@ module Polymer
   # the cache was last generated.
   class Cache
 
+    # The highest cache version supported by Cache.
+    CACHE_VERSION = 3
+
+    # The default cache.
+    EMPTY_CACHE = {
+      :cache_version => CACHE_VERSION,
+      :sprites       => {},
+      :paths         => {}
+    }
+
     # Returns the path to the cache file.
     #
     # @return [Pathname]
@@ -24,63 +34,71 @@ module Polymer
 
       if @path and @path.file?
         @cache = YAML.load_file @path
+        @cache = EMPTY_CACHE if @cache[:cache_version] < CACHE_VERSION
       else
-        @cache = { :cache_version => 2, :sprites => {} }
+        @cache = EMPTY_CACHE
       end
     end
 
     # Checks whether the given +sprite+ is different to the cached version.
     #
-    # @param [Polymer::Sprite] sprite
-    #   The sprite whose "freshness" is to be checked.
+    # @param [Polymer::Sprite] thing
+    #   The sprite or path whose "freshness" is to be checked.
     #
     # @return [Boolean]
     #
-    def stale?(sprite)
-      not fresh?(sprite)
+    def stale?(thing)
+      not fresh?(thing)
     end
 
-    # Checks whether the given +sprite+ is identical to the cached version.
+    # Checks whether the given +thing+ is identical to the cached version.
     #
-    # @param [Polymer::Sprite] sprite
-    #   The sprite whose "freshness" is to be checked.
+    # @param [Polymer::Sprite, Pathname] thing
+    #   The sprite or path whose "freshness" is to be checked.
     #
     # @return [Boolean]
     #
-    def fresh?(sprite)
-      sprite.save_path.file? and
-        @cache[:sprites].has_key?(sprite.name) and
-        @cache[:sprites][sprite.name] == sprite.digest
+    def fresh?(thing)
+      return false if thing.is_a?(Sprite)   and not thing.save_path.file?
+      return false if thing.is_a?(Pathname) and not thing.cleanpath.file?
+
+      @cache[section(thing)][key(thing)] == digest(thing)
     end
 
-    # Updates the cached value of +sprite+.
+    # Updates the cached value of +thing+.
     #
-    # @param [Polymer::Sprite] sprite
-    #   The sprite whose digest is to be stored in the cache.
+    # @param [Polymer::Sprite, Pathname] thing
+    #   The sprite or Pathname whose digest is to be stored in the cache.
     #
-    def set(sprite)
-      @cache[:sprites][sprite.name] = sprite.digest
+    def set(thing)
+      @cache[section(thing)][key(thing)] = digest(thing)
     end
 
     # Removes a +sprite+'s cached values.
     #
-    # @param [Polymer::Sprite] sprite
-    #   The sprite whose digest is to be removed from the cache.
+    # @param [Polymer::Sprite, Pathname] thing
+    #   The sprite or Pathname whose digest is to be removed from the cache.
     #
-    def remove(sprite)
-      @cache[:sprites].delete(sprite.name)
+    def remove(thing)
+      @cache[section(thing)].delete(key(thing))
     end
 
-    # Removes all sprite cache entries, except those in +retain+.
+    # Removes any sprites no longer present in a project, and any cached
+    # images which cannot be located.
     #
-    # @param [Array<Polymer::Cache>] retain
-    #   An array of cache entries which are _not_ to be removed.
+    # @param [Flexo::Project] project
     #
-    def remove_all_except(retain)
-      names = retain.map { |sprite| sprite.name }
+    def clean!(project)
+      return false unless @path
+
+      @cache[:paths].delete_if do |key, _|
+        not @path.dirname.join(key).file?
+      end
+
+      sprite_keys = project.sprites.map { |sprite| key(sprite) }
 
       @cache[:sprites].delete_if do |key, _|
-        not names.include?(key)
+        not sprite_keys.include?(key)
       end
     end
 
@@ -102,5 +120,41 @@ module Polymer
       true
     end
 
+    #######
+    private
+    #######
+
+    # @return [Symbol]
+    #   Returns the cache section (:sprites or :paths) for the given object.
+    def section(thing)
+      thing.is_a?(Pathname) ? :paths : :sprites
+    end
+
+    # @return [String]
+    #   Returns the key which represents the given Sprite or Pathname in the
+    #   cache file.
+    def key(thing)
+      if thing.is_a?(Pathname)
+        if @path
+          # Store Pathnames as relative to the cache.
+          Pathname.pwd.join(thing).relative_path_from(@path.dirname).to_s
+        else
+          thing.cleanpath.to_s
+        end
+      else
+        thing.name.to_s
+      end
+    end
+
+    # @return [String]
+    #   Returns the SHA256 digest of the given Pathname or Sprite.
+    def digest(thing)
+      if thing.is_a?(Pathname)
+        Digest::SHA256.file(thing.cleanpath).to_s
+      else
+        thing.digest
+      end
+    end
+
   end # Cache
 end # Polymer

data/lib/polymer/cli.rb

@@ -61,18 +61,11 @@ module Polymer
         say_status('generated', sprite.name, :green)
 
         unless options[:fast]
-          say "  optimising  #{sprite.name} ... "
-          before = sprite.save_path.size
+          run_optimisation(sprite.save_path, sprite.name)
 
-          reduction = Polymer::Optimisation.optimise_file(sprite.save_path)
-
-          if reduction > 0
-            saved = '- saved %.2fkb (%.1f' %
-              [reduction.to_f / 1024, (reduction.to_f / before) * 100]
-            say_status "\r\e[0K   optimised", "#{sprite.name} #{saved}%)", :green
-          else
-            print "\r\e[0K"
-          end
+          # Store the cached image so that running polymer-optimise
+          # skips this image.
+          project.cache.set(sprite.save_path.relative_path_from(project.root))
         end
       end
 
@@ -91,7 +84,7 @@ module Polymer
       end
 
       # Clean up the cache, removing sprites which no longer exist.
-      project.cache.remove_all_except(project.sprites)
+      project.cache.clean!(project)
 
       # Finish by writing the new cache.
       project.cache.write
@@ -108,22 +101,22 @@ module Polymer
     def help(command = nil)
       page_map = {
         # Main manual page.
-        nil        => 'polymer.1',
+         nil         => 'polymer.1',
         'polymer'    => 'polymer.1',
 
         # Sub-commands.
-        'init'     => 'polymer-init.1',
-        'bond'     => 'polymer-bond.1',
-        'optimise' => 'polymer-optimise.1',
-        'optimize' => 'polymer-optimise.1',
-        'position' => 'polymer-position.1',
+        'init'       => 'polymer-init.1',
+        'bond'       => 'polymer-bond.1',
+        'optimise'   => 'polymer-optimise.1',
+        'optimize'   => 'polymer-optimise.1',
+        'position'   => 'polymer-position.1',
 
         # Configuration format.
         'polymer(5)' => 'polymer.5',
         'polymer.5'  => 'polymer.5',
         '.polymer'   => 'polymer.5',
         'polymer.rb' => 'polymer.5',
-        'config'   => 'polymer.5'
+        'config'     => 'polymer.5'
       }
 
       if page_map.has_key?(command)
@@ -207,33 +200,42 @@ module Polymer
       paths are relative to the current working directory.
     DESC
 
+    method_option :force, :type => :boolean, :default => false,
+      :desc => "Re-optimise images which haven't changed since the last " \
+               "time they were optimised; has no effect unless in a " \
+               "project directory."
+
     map 'optimize' => :optimise
 
     def optimise(*paths)
       dir = Pathname.new(Dir.pwd)
-      paths = paths.map { |path| dir + path }
 
-      paths.each do |path|
-        fpath = path.relative_path_from(dir).to_s
+      # Try to use the project cache.
+      begin
+        project = find_project
+        cache   = project.cache
+      rescue Polymer::MissingProject
+        project, cache = nil, Polymer::Cache.new
+      end
 
-        # Ensure the file is a PNG.
-        unless path.to_s =~ /\.png/
-          say_status 'skipped', "#{fpath} - not a PNG", :yellow
-          next
-        end
+      paths = paths.map do |path|
+        path = dir + path
+        # If given a directory, append a glob which recursively looks
+        # for PNG files, otherwise use the path literally.
+        path.directory? ? Pathname.glob(path + '**' + '*.png') : path.cleanpath
+      end.flatten
 
-        before = path.size
-        say "  optimising  #{fpath} "
-        reduction = Polymer::Optimisation.optimise_file(path)
+      paths.each do |path|
+        relative = path.relative_path_from(dir)
 
-        if reduction > 0
-          saved = '- saved %.2fkb (%.1f' %
-            [reduction.to_f / 1024, (reduction.to_f / before) * 100]
-          say_status "\r\e[0K   optimised", "#{fpath} #{saved}%)", :green
-        else
-          say_status "\r\e[0K   optimised", "#{fpath} - no savings", :green
+        if options[:force] or cache.stale?(relative)
+          run_optimisation(path, relative)
+          cache.set(relative)
         end
       end
+
+      cache.clean!(project) if project
+      cache.write
     end
 
     # --- position -----------------------------------------------------------
@@ -301,7 +303,7 @@ module Polymer
     # @return [Polymer::Project]
     #
     def find_project!
-      Polymer::DSL.load Polymer::Project.find_config(Dir.pwd)
+      find_project
     rescue Polymer::MissingProject
       say <<-ERROR.compress_lines, :red
         Couldn't find a Polymer project in the current directory, or any of
@@ -311,6 +313,43 @@ module Polymer
       exit 1
     end
 
+    # Trys to find a project, and raises if one is not available.
+    #
+    # @return [Polymer::Project]
+    #
+    def find_project
+      Polymer::DSL.load Polymer::Project.find_config(Dir.pwd)
+    end
+
+    # Runs optimisation on a given +path+.
+    #
+    # @param [Pathname] path
+    #   Path to the file to optimise.
+    # @param [String] name
+    #   The name of the "thing" being optimised. This is the value shown to
+    #   the user, and allows removal of the path prefix, or use of a sprite
+    #   name.
+    #
+    def run_optimisation(path, name)
+      # Ensure the file is a PNG.
+      unless path.to_s =~ /\.png/
+        say_status 'skipped', "#{name} - not a PNG", :yellow
+        return
+      end
+
+      before = path.size
+      say "  optimising  #{name} "
+      reduction = Polymer::Optimisation.optimise_file(path)
+
+      if reduction > 0
+        saved = '- saved %.2fkb (%.1f' %
+          [reduction.to_f / 1024, (reduction.to_f / before) * 100]
+        say_status "\r\e[0K   optimised", "#{name} #{saved}%)", :green
+      else
+        say_status "\r\e[0K   optimised", "#{name} - no savings", :green
+      end
+    end
+
     # Returns if the current machine has groff available.
     #
     # @return [Boolean]

data/lib/polymer/man/polymer-bond.1

@@ -2,7 +2,7 @@
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .ad l
 .
-.TH "POLYMER\-BOND" "1" "September 2010" "POLYMER 1.0.0.BETA.3" "Polymer Manual"
+.TH "POLYMER\-BOND" "1" "September 2010" "POLYMER 1.0.0.BETA.4" "Polymer Manual"
 .
 .SH "NAME"
 \fBpolymer\-bond\fR \- Create sprite images defined in your \.polymer file

data/lib/polymer/man/polymer-bond.1.txt

@@ -63,4 +63,4 @@ SEE ALSO
 
 
 
-POLYMER 1.0.0.BETA.3		September 2010		       POLYMER-BOND(1)
+POLYMER 1.0.0.BETA.4		September 2010		       POLYMER-BOND(1)

data/lib/polymer/man/polymer-init.1

@@ -2,7 +2,7 @@
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .ad l
 .
-.TH "POLYMER\-INIT" "1" "September 2010" "POLYMER 1.0.0.BETA.3" "Polymer Manual"
+.TH "POLYMER\-INIT" "1" "September 2010" "POLYMER 1.0.0.BETA.4" "Polymer Manual"
 .
 .SH "NAME"
 \fBpolymer\-init\fR \- Create a new Polymer project in the current directory

data/lib/polymer/man/polymer-init.1.txt

@@ -39,4 +39,4 @@ OPTIONS
 
 
 
-POLYMER 1.0.0.BETA.3		September 2010		       POLYMER-INIT(1)
+POLYMER 1.0.0.BETA.4		September 2010		       POLYMER-INIT(1)

data/lib/polymer/man/polymer-optimise.1

@@ -2,7 +2,7 @@
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .ad l
 .
-.TH "POLYMER\-OPTIMISE" "1" "September 2010" "POLYMER 1.0.0.BETA.3" "Polymer Manual"
+.TH "POLYMER\-OPTIMISE" "1" "September 2010" "POLYMER 1.0.0.BETA.4" "Polymer Manual"
 .
 .SH "NAME"
 \fBpolymer\-optimise\fR \- Optimise PNG images
@@ -10,6 +10,12 @@
 .SH "SYNOPSIS"
 \fBpolymer optimise\fR PATH [PATH [PATH \.\.\.]]
 .
+.SH "OPTIONS"
+.
+.TP
+\fB\-\-force\fR
+Something something something dark side: re\-optimise images even if they haven\'t changed since last time they were optimised\.
+.
 .SH "DESCRIPTION"
 Optimises the PNG images at \fIPATH\fR\. Does not require you to be in a Polymer project directory\.
 .

data/lib/polymer/man/polymer-optimise.1.txt

@@ -8,6 +8,11 @@ NAME
 SYNOPSIS
        polymer optimise PATH [PATH [PATH ...]]
 
+OPTIONS
+       --force
+	      Something something something dark side: re-optimise images even
+	      if they haven't changed since last time they were optimised.
+
 DESCRIPTION
        Optimises the PNG images at PATH. Does not require you to be in a Poly-
        mer project directory.
@@ -22,4 +27,4 @@ DESCRIPTION
 
 
 
-POLYMER 1.0.0.BETA.3		September 2010		   POLYMER-OPTIMISE(1)
+POLYMER 1.0.0.BETA.4		September 2010		   POLYMER-OPTIMISE(1)

data/lib/polymer/man/polymer-position.1

@@ -2,7 +2,7 @@
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .ad l
 .
-.TH "POLYMER\-POSITION" "1" "September 2010" "POLYMER 1.0.0.BETA.3" "Polymer Manual"
+.TH "POLYMER\-POSITION" "1" "September 2010" "POLYMER 1.0.0.BETA.4" "Polymer Manual"
 .
 .SH "NAME"
 \fBpolymer\-position\fR \- Information about your sprite sources

data/lib/polymer/man/polymer-position.1.txt

@@ -39,4 +39,4 @@ DESCRIPTION
 
 
 
-POLYMER 1.0.0.BETA.3		September 2010		   POLYMER-POSITION(1)
+POLYMER 1.0.0.BETA.4		September 2010		   POLYMER-POSITION(1)

data/lib/polymer/man/polymer.1

@@ -2,7 +2,7 @@
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .ad l
 .
-.TH "POLYMER" "1" "September 2010" "POLYMER 1.0.0.BETA.3" "Polymer Manual"
+.TH "POLYMER" "1" "September 2010" "POLYMER 1.0.0.BETA.4" "Polymer Manual"
 .
 .SH "NAME"
 \fBpolymer\fR \- Image spriting for web applications

data/lib/polymer/man/polymer.1.txt

@@ -57,4 +57,4 @@ SEE ALSO
 
 
 
-POLYMER 1.0.0.BETA.3		September 2010			    POLYMER(1)
+POLYMER 1.0.0.BETA.4		September 2010			    POLYMER(1)

data/lib/polymer/man/polymer.5

@@ -2,7 +2,7 @@
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .ad l
 .
-.TH "\.POLYMER" "5" "September 2010" "POLYMER 1.0.0.BETA.3" "Polymer Manual"
+.TH "\.POLYMER" "5" "September 2010" "POLYMER 1.0.0.BETA.4" "Polymer Manual"
 .
 .SH "NAME"
 \fB\.polymer\fR \- a format for describing image sprites and their sources
@@ -88,7 +88,7 @@ sprites "sources/:name/*" => "sprites/:name\.png"
 .IP "" 0
 .
 .P
-In this case, Polymer will look inside the "sources/" directory for sub\-directories\. The contents of sub\-directory will be used to create individual sprites where the final sprite name is the same as the directory name\. For example, given the following directory structure\.\.\.
+In this case, Polymer will look inside the "sources/" directory for sub\-directories\. The contents of each sub\-directory will be used to create individual sprites where the final sprite name is the same as the directory name\. For example, given the following directory structure\.\.\.
 .
 .IP "" 4
 .
@@ -126,5 +126,8 @@ sprite "path/to/sources/*" => "path/to/sprite\.png",
 .P
 Each configuration option is prefixed with a colon rather than "config\.", is separated from the value with " => ", and all but the final option should be followed with a comma\.
 .
+.P
+You may use \fBsprite\fR as many times as you need\.
+.
 .SH "SEE ALSO"
 polymer(1), polymer\-init(1)

data/lib/polymer/man/polymer.5.txt

@@ -101,9 +101,10 @@ DEFINING SPRITES
 
 
        In this case, Polymer will look inside the "sources/" directory for
-       sub-directories. The contents of sub-directory will be used to create
-       individual sprites where the final sprite name is the same as the
-       directory name. For example, given the following directory structure...
+       sub-directories. The contents of each sub-directory will be used to
+       create individual sprites where the final sprite name is the same as
+       the directory name. For example, given the following directory struc-
+       ture...
 
 
 
@@ -137,9 +138,11 @@ DEFINING SPRITES
        fig.", is separated from the value with " => ", and all but the final
        option should be followed with a comma.
 
+       You may use sprite as many times as you need.
+
 SEE ALSO
        polymer(1), polymer-init(1)
 
 
 
-POLYMER 1.0.0.BETA.3		September 2010			   .POLYMER(5)
+POLYMER 1.0.0.BETA.4		September 2010			   .POLYMER(5)

data/lib/polymer/templates/sass_mixins.erb

@@ -15,7 +15,7 @@
 <% end %>
 <% end %>
 
-@mixin polymer-pos($source, $x-offset: 0px, $y-offset: 0px)
+@mixin polymer-position($source, $x-offset: 0px, $y-offset: 0px)
 <% project.sprites.each_with_index do |sprite, sprite_index| %>
 <% sprite.sources.each_with_index do |source, source_index| %>
 <% if sprite_index == 0 and source_index == 0 %>

data/lib/polymer/version.rb

@@ -1,4 +1,4 @@
 module Polymer
   # The current version of the Polymer library.
-  VERSION = '1.0.0.beta.3'.freeze
+  VERSION = '1.0.0.beta.4'.freeze
 end

data/polymer.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |s|
   # rake task. It it completely safe to edit them, but using the rake task
   # is easier.
   s.name              = 'polymer'
-  s.version           = '1.0.0.beta.3'
-  s.date              = '2010-09-24'
+  s.version           = '1.0.0.beta.4'
+  s.date              = '2010-09-29'
   s.rubyforge_project = 'polymer'
 
   # You may safely edit the section below.

metadata

@@ -7,8 +7,8 @@ version: !ruby/object:Gem::Version
   - 0
   - 0
   - beta
-  - 3
-  version: 1.0.0.beta.3
+  - 4
+  version: 1.0.0.beta.4
 platform: ruby
 authors: 
 - Anthony Williams
@@ -16,7 +16,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-09-24 00:00:00 +01:00
+date: 2010-09-29 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency