montage 0.2.1

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,31 @@
+## MAC OS
+.DS_Store
+Icon*
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## RUBINIUS
+*.rbc
+rakefile.compiled.rbc
+
+## PROJECT::GENERAL
+.yardoc
+coverage
+doc
+measurements
+pkg
+rdoc
+tmp
+
+## PROJECT::SPECIFIC
+.sass-cache

data/History.md

@@ -0,0 +1,40 @@
+v0.2.0 - 2010-04-08
+-------------------
+
+* Running `montage` will now generate `_montage.sass` in the specified
+  config.sass directory. A separate mixin will be generated for each sprite,
+  with the mixin accepting three arguments: the name of the source image, an
+  optional horizontal offset, and an optional vertical offset. Disable the
+  Sass generation by setting config.sass to false.
+
+* If pngout or pngout-darwin is available (run `which pngout pngout-darwin` to
+  find out), Montage will compress the generated sprites. Installing pngout
+  is strongly recommended; significant savings can be made on larger PNGs.
+
+* The `montage` command accepts a '--force' option which will regenerate all
+  sprites even if they haven't been changed since the last run.
+
+* Sprites will be regenerated if the file has been deleted.
+
+v0.1.2 - 2010-04-06
+-------------------
+
+* Sprites will only be regenerated when their definition (in montage.yml) has
+  changed, or if the contents of the source files have changed.
+
+* The `montage init` command now uses the highline gem to ask for the paths to
+  a project's source files, and the intended sprite output directory.
+
+* Running `montage init` will copy some sample source files into the source
+  directory. This allows running `montage` immediately after creating the
+  project, to see how things work.
+
+v0.1.1 - 2010-04-05
+-------------------
+
+* Small fix for Ruby 1.9.1, which doesn't define String#inject.
+
+v0.1.0 - 2010-04-05
+-------------------
+
+* Initial release. Supports creation of sprites and not much else.

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2009-2010 Anthony Williams
+
+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,89 @@
+Montage
+=======
+
+_"[Even Rocky had a montage](http://www.youtube.com/watch?v=FIi0vFyqWAc)."_
+
+**Source**
+:  [http://github.com/antw/montage](http://github.com/antw/montage)
+
+**Author**
+:  Anthony Williams
+
+**Copyright**
+:  2009-2010
+
+**License**
+:  MIT License
+
+SYNOPSIS
+--------
+
+Popularised by Dave Shea in an [A List Apart](http://www.alistapart.com/articles/sprites), "sprite" images combine many smaller images into a single, larger image, with CSS then being used to divide the sprite back into it's constituent parts.
+
+However, creating sprites burdens you with having to manually update them every time a minor change is required. Even more frustrating is the need to remember the precise background positions required when editing the CSS.
+
+Montage is a library which, provided a simple configuration file, will automate this process, and if you're a SASS user, you're in for a treat: Montage generates mixins which make working with your sprites incredibly simple:
+
+    SASS Usage:
+
+      #navigation
+        a#home, a#products
+          +main-sprite("home")
+        a#products
+          +main-sprite-pos("products")
+
+    Generated CSS:
+
+      #navigation a#home, #navigation a#products {
+        background: url(/path/to/sprite.ext) 0 0 no-repeat; }
+
+      #navigation a#products {
+        background-position: 0 -40px; }
+
+Montage has been split out from [Kin](http://github.com/antw/kin) -- a collection of various bits-and-bobs from my Merb projects.
+
+Montage is pretty primitive in that it stacks each image in a single column. This is perfect when your source images are of a similar width (such as is the case with icons), but not so good when they vary significantly in size.
+
+FEATURE LIST
+------------
+
+Coming soon.
+
+USAGE
+-----
+
+Coming soon.
+
+Ward specs are run against:
+
+* Ruby (MRI) 1.8.6 p399,
+* Ruby (MRI) 1.8.7 p249,
+* Ruby (YARV) 1.9.1 p378,
+
+Montage requires RMagick which presently rules out support for JRuby and Rubinius.
+
+CONTRIBUTING
+------------
+
+* Fork the project, taking care not to get any in your eyes.
+
+* Make your feature addition or bug fix.
+
+* Add tests for it. This is especially important not only because it helps
+  ensure that I don't unintentionally break it in a future version, but also
+  since it appeases Phyllis --- the goddess of Cucumbers --- who has been
+  known to rain showers of fresh vegetables on those who don't write tests.
+
+* Commit, but do not mess with the Rakefile, VERSION, or history. If you want
+  to have your own version, that is fine, but bump version in a commit by
+  itself so that I can ignore it when I pull.
+
+* Send me a pull request. Bonus points for topic branches. But we all know
+  everything is made up and the points don't matter.
+
+COPYRIGHT
+---------
+
+Montage © 2009-2010 by [Anthony Williams](mailto:hi@antw.me). Licensed under the MIT license. Please see the {file:LICENSE} for more information.
+
+The sample sources in lib/montage/templates/sources are courtesy of Yusuke Kamiyamane: http://p.yusukekamiyamane.com

data/Rakefile

@@ -0,0 +1,41 @@
+require 'rake'
+require 'rake/clean'
+
+require File.expand_path('../lib/montage/version', __FILE__)
+
+CLOBBER.include ['pkg', '*.gem', 'doc', 'coverage', 'measurements']
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name        = 'montage'
+    gem.summary     = 'Montage'
+    gem.homepage    = 'http://github.com/antw/montage'
+    gem.description = 'Even Rocky had a montage.'
+
+    gem.author      = 'Anthony Williams'
+    gem.email       = 'hi@antw.me'
+
+    gem.platform    = Gem::Platform::RUBY
+    gem.has_rdoc    = false
+
+    # Dependencies.
+    gem.add_dependency 'activesupport', '>= 3.0.0.beta'
+    gem.add_dependency 'rmagick',       '>= 2.12'
+    gem.add_dependency 'highline',      '>= 1.5'
+
+    # Development dependencies.
+    gem.add_development_dependency 'rspec',    '>= 1.3.0'
+    gem.add_development_dependency 'cucumber', '>= 0.6'
+    gem.add_development_dependency 'open4',    '>= 1.0'
+    gem.add_development_dependency 'haml',     '>= 3.0.0.beta.1'
+    gem.add_development_dependency 'yard',     '>= 0.5'
+  end
+
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts 'Jeweler (or a dependency) not available. Install it with: gem '\
+       'install jeweler'
+end
+
+FileList['tasks/**/*.rake'].each { |task| import task }

data/VERSION

@@ -0,0 +1 @@
+0.2.1

data/bin/montage

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+
+unless $:.include?(File.dirname(__FILE__) + '/../lib')
+  $:.unshift(File.dirname(__FILE__) + '/../lib')
+end
+
+require 'rubygems' unless ENV['NORUBYGEMS']
+
+require 'montage'
+require 'montage/commands'
+
+Montage::Commands.print_masthead
+
+case ARGV[0]
+  when 'init'
+    require 'montage/commands/init'
+    Montage::Commands::Init.run(ARGV)
+  else
+    require 'montage/commands/generate'
+    Montage::Commands::Generate.run(ARGV)
+end
+

data/lib/montage.rb

@@ -0,0 +1,33 @@
+require 'digest/sha2'
+require 'erb'
+require 'pathname'
+require 'yaml'
+
+# Gems.
+require 'active_support/ordered_hash'
+require 'rmagick'
+
+# On with the library...
+require 'montage/core_ext'
+require 'montage/project'
+require 'montage/sass_builder'
+require 'montage/source'
+require 'montage/sprite'
+require 'montage/version'
+
+module Montage
+  # Generic exception for all Montage exception classes.
+  MontageError = Class.new(StandardError)
+
+  # Raised when a project directory couldn't be found.
+  MissingProject = Class.new(MontageError)
+
+  # Raised when a creating a new project in an existing project directory.
+  ProjectExists = Class.new(MontageError)
+
+  # Raised when a sprite set expects a source image, but none could be found.
+  MissingSource = Class.new(MontageError)
+
+  # Raised when a sprite can't be saved due to incorrect permissions.
+  TargetNotWritable = Class.new(MontageError)
+end

data/lib/montage/commands.rb

@@ -0,0 +1,32 @@
+require 'highline/import'
+
+HighLine.use_color = ! ARGV.delete('--no-color') && ! ARGV.delete('--no-colour')
+HighLine.use_color = false if !STDOUT.tty? && !ENV.has_key?("AUTOTEST")
+
+module Kernel
+  def_delegators :$terminal, :color
+end
+
+module Montage
+  module Commands
+    BLANK = "\n".freeze
+
+    extend self
+
+    # Prints the Montage masthead, introducing the programme, and including
+    # the current version number.
+    def print_masthead
+      say BLANK
+      say "Montage v#{Montage::VERSION}"
+      say "=========#{'=' * Montage::VERSION.length}"
+      say BLANK
+    end
+
+    # Exits immediately, outputting a blank line first.
+    def exit(status)
+      say BLANK
+      Kernel.exit(status)
+    end
+
+  end # Commands
+end # Montage

data/lib/montage/commands/generate.rb

@@ -0,0 +1,234 @@
+module Montage
+  module Commands
+    # Generates sprites for a project.
+    class Generate
+      extend Commands
+
+      # Terminal reset code; removes any content on the current line and moves
+      # the cursor back to the beginning.
+      RESET = "\r\e[0K"
+
+      # Glyphs used when doing long-running processes.
+      GLYPHS = %w( ~ \\ | / )
+
+      # Given a project, generates sprites.
+      #
+      # @param [Array] argv
+      #   The arguments given on the command line.
+      #
+      def self.run(argv)
+        new(Montage::Project.find(Dir.pwd), argv.include?('--force')).run!
+
+      rescue Montage::MissingProject
+        say color(<<-ERROR.compress_lines, :red)
+          Couldn't find a Montage project in the current directory. If
+          you want to create a new project here, run `montage init'.
+        ERROR
+
+        exit(1)
+
+      rescue Montage::MissingSource, Montage::TargetNotWritable => e
+        say Montage::Commands::BLANK
+        say color(e.message.compress_lines, :red)
+
+        exit(1)
+      end
+
+      # Creates a new Generate instance.
+      #
+      # @param [Montage::Project] project
+      #   The project whose sprites are to be generated.
+      # @param [Boolean] force
+      #   Rengerate sprites, even if they haven't been changed.
+      #
+      def initialize(project, force)
+        @project, @force, @generated = project, force, []
+      end
+
+      # Runs the generator, saving the sprites and cache.
+      #
+      def run!
+        if generate_sprites!
+          optimise_with_pngout!
+          write_cache!
+          write_sass!
+        end
+      end
+
+      private # ==============================================================
+
+      # Returns the cached digests.
+      #
+      # @return [Hash]
+      #
+      def cache
+        @_sprite_caches ||= begin
+          cache_path = @project.paths.sprites + '.montage_cache'
+          cache_path.file? ? YAML.load_file(cache_path) || {} : {}
+        end
+      end
+
+      # Step 1: Generates the sprites for the given project. Skips those which
+      # have not changed since they were last generated.
+      #
+      # @return [Boolean]
+      #   Returns true if at least one sprite has been updated.
+      #
+      def generate_sprites!
+        unless @project.paths.sprites.directory?
+          @project.paths.sprites.mkpath
+        end
+
+        @project.sprites.each do |sprite|
+          digest = sprite.digest
+
+
+          if @force or cache[sprite.name] != digest or not sprite.path.file?
+            with_feedback %(Generating "#{sprite.name}"), 'Generating' do
+              sprite.write
+              cache[sprite.name] = digest
+              @generated << sprite
+            end
+
+            say color("Done", :green)
+          else
+            say %(- Generating "#{sprite.name}": ) +
+                color("Unchanged; ignoring", :yellow)
+          end
+        end
+
+        say Montage::Commands::BLANK
+        @generated.any?
+      end
+
+      # Step 2: Optimise generated sprites with PNGOut.
+      #
+      def optimise_with_pngout!
+        return if @generated.empty?
+
+        # Try to find PNGOut.
+        pngout = `which pngout pngout-darwin`.split("\n").first
+
+        if pngout.nil?
+          say <<-MESSAGE.compress_lines
+            Skipping optimisation with PNGOut since Montage couldn't find
+            "pngout" or "pngout-darwin" anywhere.
+          MESSAGE
+          say Montage::Commands::BLANK
+
+          return
+        end
+
+        max_sprite_name_length = @generated.inject(0) do |max, sprite|
+          max > sprite.name.length ? max : sprite.name.length
+        end
+
+        @generated.each do |sprite|
+          original_size = sprite.path.size
+
+          with_feedback %(Optimising "#{sprite.name}"), 'Optimising' do
+            5.times do |i|
+              # Optimise until pngout reports that it can't compress further,
+              # or until we've tried five times.
+              out = `#{pngout} #{sprite.path} #{sprite.path} -s0 -k0 -y`
+              break if out =~ /Unable to compress further/
+            end
+          end
+
+          new_size  = sprite.path.size
+
+          reduction = ('%.1fkb (%d' % [
+            (original_size.to_f - new_size) / 1024,
+            100 - (new_size.to_f / original_size) * 100 ]) + '%)'
+
+          say color("Done; saved #{reduction}", :green)
+        end
+
+        say Montage::Commands::BLANK
+
+      rescue Errno::ENOENT
+        say ("#{RESET}" + <<-MESSAGE.compress_lines)
+          Skipping optimisation with PNGOut since Montage is currently only in
+          bed with Linux and OS X. Sorry!
+        MESSAGE
+        say Montage::Commands::BLANK
+        exit(1)
+      end
+
+      # Step 3: Writes the cached digests to the cache file.
+      #
+      def write_cache!
+        cache_path = @project.paths.sprites + '.montage_cache'
+
+        File.open(cache_path, 'w') do |cache_writer|
+          cache_writer.puts YAML.dump(cache)
+        end
+      end
+
+      # Step 4: Writes the Sass file to disk.
+      #
+      def write_sass!
+        unless @project.paths.sass == false
+          say "- Generating Sass: "
+          Montage::SassBuilder.new(@project).write
+          say color("Done", :green)
+          say Montage::Commands::BLANK
+        end
+      end
+
+      # --- Optimisation Output ----------------------------------------------
+
+      # Executes a block while providing live feedback to the user.
+      #
+      # @param [String] prefix
+      #   The "prefix" of each notification; this is always shown at the
+      #   beginning of each line.
+      # @param [String] verb
+      #   What's happening?
+      #
+      # @example
+      #   with_notification('Generating image', 'Generating') { ... }
+      #
+      #   # "- Generating image: Generating"       # initially
+      #   # "- Generating image: Still generating" # after 3 seconds
+      #   # "- Generating image: STILL generating" # after 6 seconds
+      #
+      def with_feedback(prefix, verb = 'Generating', &work)
+        notifier = Thread.new do
+          prefix = "- #{prefix}: "
+          iteration = 0
+
+          while true do
+            case iteration
+              when  0 then message = color(verb, :blue)
+              when 30 then message = color("Still #{verb.downcase}", :blue)
+              when 60 then message = color("STILL #{verb.downcase}", :blue)
+              when 90 then message =
+                             color("Gosh, this is taking a while...", :blue)
+            end
+
+            say "#{RESET}#{prefix}#{message} [#{GLYPHS[iteration % 4]}] "
+
+            iteration += 1
+            $stdout.flush
+            sleep(0.1)
+          end
+        end
+
+        worker = Thread.new do
+          begin
+            work.call
+          ensure
+            notifier.kill
+          end
+        end
+
+        notifier.join
+        worker.join
+
+        say "#{RESET}#{prefix}"
+      end
+
+    end # Generate
+  end # Commands
+end # Montage