polymer 1.0.0.beta.3

data/lib/polymer/cli.rb

@@ -0,0 +1,340 @@
+require 'fileutils'
+require 'thor'
+
+module Polymer
+  class CLI < Thor
+
+    include Thor::Actions
+
+    class_option 'no-color', :type => :boolean, :default => false,
+      :desc => 'Disable colours in output', :aliases => '--no-colour'
+
+    def initialize(*args)
+      super
+      self.shell = Thor::Shell::Basic.new if options['no-color']
+    end
+
+    # --- bond ---------------------------------------------------------------
+
+    desc 'bond [SPRITES]',
+      'Creates the sprites specified by your .polymer or polymer.rb file'
+
+    long_desc <<-DESC
+      The bond task reads your project configuration and creates your shiny
+      new sprites. If enabled, CSS and/or SCSS will also be written so as to
+      make working with your sprites a little easier.
+
+      You may specify exactly which sprites you want generated, otherwise
+      Polymer will generate all sprites defined in your config file. Any
+      sprite which has not changed since you last ran this command will not be
+      re-generated unless you pass the --force option.
+    DESC
+
+    method_option :force, :type => :boolean, :default => false,
+      :desc => 'Re-generates sprites whose sources have not changed'
+
+    method_option :fast, :type => :boolean, :default => false,
+      :desc => "Skip optimisation of images after they are generated"
+
+    def bond(*sprites)
+      project = find_project!
+
+      # Determine which sprites we'll be working on.
+      sprites = project.sprites.select do |sprite|
+        if sprites.empty? or sprites.include?(sprite.name)
+          # The user specified no sprites, or this sprite was requested.
+          if project.cache.stale?(sprite) or options[:force]
+            # Digest is different, user is forcing update or sprite file
+            # has been deleted.
+            project.cache.set(sprite)
+          end
+        end
+      end
+
+      # There's nothing to generate.
+      return if sprites.empty?
+
+      # Get on with it.
+      sprites.each do |sprite|
+        next unless sprite.save
+
+        say_status('generated', sprite.name, :green)
+
+        unless options[:fast]
+          say "  optimising  #{sprite.name} ... "
+          before = sprite.save_path.size
+
+          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
+        end
+      end
+
+      # Stylesheets.
+      if SassGenerator.generate(project)
+        say_status('written', 'Sass mixin', :green)
+      end
+
+      #process Processors::CSS,        project
+
+      # Find sprites with deviant-width sources.
+      sprites.each do |sprite|
+        if deviants = DeviantFinder.find_deviants(sprite)
+          say DeviantFinder.format_ui_message(sprite, deviants)
+        end
+      end
+
+      # Clean up the cache, removing sprites which no longer exist.
+      project.cache.remove_all_except(project.sprites)
+
+      # Finish by writing the new cache.
+      project.cache.write
+
+    rescue Polymer::MissingSource, Polymer::TargetNotWritable => e
+      say e.message.compress_lines, :red
+      exit 1
+    end
+
+    # --- help ---------------------------------------------------------------
+
+    # Provides customised help information using the man pages.
+    # Nod-of-the-hat to Bundler.
+    def help(command = nil)
+      page_map = {
+        # Main manual page.
+        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',
+
+        # Configuration format.
+        'polymer(5)' => 'polymer.5',
+        'polymer.5'  => 'polymer.5',
+        '.polymer'   => 'polymer.5',
+        'polymer.rb' => 'polymer.5',
+        'config'   => 'polymer.5'
+      }
+
+      if page_map.has_key?(command)
+        root = File.expand_path('../man', __FILE__)
+
+        if groff_available?
+          groff = 'groff -Wall -mtty-char -mandoc -Tascii'
+          pager = ENV['MANPAGER'] || ENV['PAGER'] || 'more'
+
+          Kernel.exec "#{groff} #{root}/#{page_map[command]} | #{pager}"
+        else
+          puts File.read("#{root}/#{page_map[command]}.txt")
+        end
+      else
+        super
+      end
+    end
+
+    # --- init ---------------------------------------------------------------
+
+    desc 'init', 'Creates a new Polymer project in the current directory'
+
+    long_desc <<-DESC
+      In order to use Polymer, a .polymer configuration file must be created.
+      The init task creates a sample configuration, and also adds a couple of
+      example source images to demonstrate how to use Polymer to create your
+      own sprite images.
+    DESC
+
+    method_option :sprites, :type => :string, :default => 'public/images',
+      :desc => 'Default location to which generated sprites are saved'
+
+    method_option :sources, :type => :string, :default => '<sprites>/sprites',
+      :desc => 'Default location of source images'
+
+    method_option 'no-examples', :type => :boolean, :default => false,
+      :desc => "Disables copying of example source files"
+
+    method_option :windows, :type => :boolean, :default => false,
+      :desc => 'Create polymer.rb instead of .polymer for easier editing on ' \
+               'Windows systems.'
+
+    def init
+      if File.exists?('.polymer')
+        say 'A .polymer file already exists in this directory.', :red
+        exit 1
+      end
+
+      project_dir = Pathname.new(Dir.pwd)
+
+      config = {
+        :sprites => options[:sprites],
+        :sources => options[:sources].gsub(/<sprites>/, options[:sprites]),
+        :windows => options[:windows]
+      }
+
+      filename  = options[:windows] ? 'polymer.rb' : '.polymer'
+      polymerfile = project_dir + filename
+
+      template 'polymer.tt', polymerfile, config
+
+      # Clean up the template.
+      contents = polymerfile.read.gsub(/\n{3,}/, "\n\n")
+      polymerfile.open('w') { |file| file.puts contents }
+
+      unless options['no-examples']
+        directory 'sources',  project_dir + config[:sources]
+      end
+
+      say_status '', '-------------------------'
+      say_status '', 'Your project was created!'
+    end
+
+    # --- optimise -----------------------------------------------------------
+
+    desc 'optimise PATHS', 'Optimises PNG images at the given PATHS'
+
+    long_desc <<-DESC
+      Given a path to an image (or multiple images), runs Polymer's optimisers
+      on the image. Requires that the paths be images to PNG files. Image
+      paths are relative to the current working directory.
+    DESC
+
+    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
+
+        # Ensure the file is a PNG.
+        unless path.to_s =~ /\.png/
+          say_status 'skipped', "#{fpath} - not a PNG", :yellow
+          next
+        end
+
+        before = path.size
+        say "  optimising  #{fpath} "
+        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", "#{fpath} #{saved}%)", :green
+        else
+          say_status "\r\e[0K   optimised", "#{fpath} - no savings", :green
+        end
+      end
+    end
+
+    # --- position -----------------------------------------------------------
+
+    desc 'position SOURCE', 'Shows the position of a source within a sprite'
+
+    long_desc <<-DESC
+      The position task shows you the position of a source image within a
+      sprite and also shows the appropriate CSS statement for the source
+      should you wish to create your own CSS files.
+
+      You may supply the name of a source image; if a source image with the
+      same name exists in multiple sprites, the positions of each of them will
+      be shown to you. If you want a particular source, you may instead
+      provide a "sprite/source" pair.
+    DESC
+
+    def position(source)
+      project = find_project!
+
+      if source.index('/')
+        # Full sprite/source pair given.
+        sprite, source = source.split('/', 2)
+
+        if project.sprite(sprite)
+          sprites = [project.sprite(sprite)]
+        else
+          say "No such sprite: #{sprite}", :red
+          exit 1
+        end
+      else
+        # Only a source name was given.
+        sprites = project.sprites
+      end
+
+      # Remove sprites which don't have a matching source.
+      sprites.reject! { |sprite| not sprite.source(source) }
+      say("No such source: #{source}") && exit(1) if sprites.empty?
+
+      say ""
+
+      sprites.each do |sprite|
+        say "#{sprite.name}/#{source}: #{sprite.position_of(source)}px", :green
+        say "    #{Polymer::CSSGenerator.background_statement(sprite, source)}"
+        say "  - or -"
+        say "    #{Polymer::CSSGenerator.position_statement(sprite, source)}"
+        say ""
+      end
+    end
+
+    # --- version ------------------------------------------------------------
+
+    desc 'version', "Shows the version of Polymer you're using"
+    map '--version' => :version
+
+    def version
+      say "Polymer #{Polymer::VERSION}"
+    end
+
+    private # ----------------------------------------------------------------
+
+    # Returns the Project for the current directory. Exits with a message if
+    # no project could be found.
+    #
+    # @return [Polymer::Project]
+    #
+    def find_project!
+      Polymer::DSL.load Polymer::Project.find_config(Dir.pwd)
+    rescue Polymer::MissingProject
+      say <<-ERROR.compress_lines, :red
+        Couldn't find a Polymer project in the current directory, or any of
+        the parent directories. Run "polymer init" if you want to create a new
+        project here.
+      ERROR
+      exit 1
+    end
+
+    # Returns if the current machine has groff available.
+    #
+    # @return [Boolean]
+    #
+    def groff_available?
+      require 'rbconfig'
+
+      if RbConfig::CONFIG["host_os"] =~ /(msdos|mswin|djgpp|mingw)/
+        `which groff 2>NUL`
+      else
+        `which groff 2>/dev/null`
+      end
+
+      $? == 0
+    end
+
+    def self.source_root
+      File.expand_path(File.join(File.dirname(__FILE__), 'templates'))
+    end
+
+    # Temporary -- until the next Thor release.
+    def self.banner(task, namespace = nil, subcommand = false)
+      super.gsub(/^.*polymer/, 'polymer')
+    end
+
+  end # CLI
+end # Polymer

data/lib/polymer/core_ext.rb

@@ -0,0 +1,78 @@
+# Some simple string extensions to make things easier.
+class String
+
+  # Replace sequences of whitespace (including newlines) with either
+  # a single space or remove them entirely (according to param _spaced_)
+  #
+  #   <<QUERY.compress_lines
+  #     SELECT name
+  #     FROM users
+  #   QUERY => "SELECT name FROM users"
+  #
+  # @return [String] Receiver with whitespace (including newlines) replaced
+  #
+  def compress_lines
+    split($/).map { |line| line.strip }.join(' ')
+  end
+
+  # Removes leading whitespace from each line, such as might be added when
+  # using a HEREDOC string.
+  #
+  # @return [String] Receiver with leading whitespace removed.
+  #
+  def unindent
+    (other = dup) and other.unindent! and other
+  end
+
+  # Bang version of #unindent.
+  #
+  # @return [String] Receiver with leading whitespace removed.
+  #
+  def unindent!
+    gsub!(/^[ \t]{#{minimum_leading_whitespace}}/, '')
+  end
+
+  private
+
+  # Checks each line and determines the minimum amount of leading whitespace.
+  #
+  # @return [Integer] The number of leading whitespace characters.
+  #
+  def minimum_leading_whitespace
+    whitespace = split("\n", -1).inject(0) do |indent, line|
+      if line.strip.empty?
+        indent # Ignore completely blank lines.
+      elsif line =~ /^(\s+)/
+        (1.0 / $1.length) > indent ? 1.0 / $1.length : indent
+      else
+        1.0
+      end
+    end
+
+    whitespace == 1.0 ? 0 : (1.0 / whitespace).to_i
+  end
+
+end
+
+# String#compress_lines is extracted from the extlib gem
+# ------------------------------------------------------
+#
+# Copyright (c) 2009 Dan Kubb
+#
+# 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/lib/polymer/css_generator.rb

@@ -0,0 +1,32 @@
+module Polymer
+  class CSSGenerator
+
+    # --- Class Methods ------------------------------------------------------
+
+    # Returns a string which may be used as the background statement for the
+    # given sprite and source pair.
+    #
+    # @param [Polymer::Sprite] sprite
+    # @param [Polymer::Source] source
+    #
+    # @return [String]
+    #
+    def self.background_statement(sprite, source)
+      "background: url(#{sprite.url}) 0 " \
+      "#{-sprite.position_of(source)}px no-repeat;"
+    end
+
+    # Returns a string which may be used as the background-position statement
+    # for the given sprite and source pair.
+    #
+    # @param [Polymer::Sprite] sprite
+    # @param [Polymer::Source] source
+    #
+    # @return [String]
+    #
+    def self.position_statement(sprite, source)
+      "background-position: 0 #{-sprite.position_of(source)}px;"
+    end
+
+  end # CSSGenerator
+end # Polymer

data/lib/polymer/deviant_finder.rb

@@ -0,0 +1,76 @@
+module Polymer
+  # Given a Sprite, DeviantFinder checks to see if the sprite has any sources
+  # which are significantly wider than the average.
+  class DeviantFinder
+
+    # Given a Sprite, checks to see if the sprite has any sources which are
+    # significantly wider than the average. Images with a small standard
+    # deviation in source width or fewer than 3 sources will be skipped.
+    #
+    # @param [Polymer::Sprite] sprite
+    #   The sprite whose source widths are to be checked.
+    #
+    # @return [Array<String>]
+    #   Returns an array of source images whose width is greater than the
+    #   standard deviation.
+    # @return [nil]
+    #   Returns nil if all of the source images are an approriate width.
+    #
+    def self.find_deviants(sprite)
+      # Need more than two sources to find deviants.
+      return false if sprite.sources.size < 2
+
+      mean, std_dev = standard_deviation(sprite.sources.map do |source|
+        source.image.columns
+      end)
+
+      return false if std_dev < 100 # Skip images with a < 100px deviation.
+
+      deviants = sprite.sources.select do |source|
+        width = source.image.columns
+        width > mean + std_dev || width < mean - std_dev
+      end
+
+      deviants.any? and deviants
+    end
+
+    # Print a warning if the sprite contains wide sources.
+    def self.format_ui_message(sprite, deviants)
+      if deviants
+        <<-MESSAGE.compress_lines
+          Your "#{sprite.name}" sprite contains one or more source images
+          which deviate significantly from the average source width. You might
+          want to consider removing these sources from the sprite in order to
+          reduce the sprite filesize.
+
+          Wide sources: #{deviants.map(&:name).join(', ')}
+        MESSAGE
+      end
+    end
+
+    private # ----------------------------------------------------------------
+
+    # Knuth.
+    #
+    # @param [Array<Integer>] data
+    #   An array containing the widths of each source image.
+    #
+    # @return [Array<Integer, Integer>]
+    #   Returns a two-element array whose first element is the mean width of
+    #   the source images; the second element is the standard deviation.
+    #
+    def self.standard_deviation(data)
+      n, mean, m2 = 0, 0, 0
+
+      data.each do |x|
+        n = n + 1
+        delta = x - mean
+        mean = mean + delta / n
+        m2 = m2 + delta * (x - mean)
+      end
+
+      [ mean, Math.sqrt(m2 / (n - 1)) ]
+    end
+
+  end # DeviantFinder
+end # Polymer