montage 0.2.1 → 0.3.0

data/History.md

@@ -1,3 +1,26 @@
+v0.3.0 - 2010-04-12
+-------------------
+
+* The "montage.yml" file has been replaced with ".montage" which should be
+  located in your project root. In addition, the file is now rather different,
+  and in most cases will never need to be edited when you want to add new
+  sources to the sprite.
+
+* By default Montage will now save sprites to public/images, expected source
+  images to be in public/images/subdir -- where "subdir" will become the name
+  of the sprite. All sources in a subdirectory will be added to the same
+  sprite.
+
+  This behavior is entirely customisable in the .montage file.
+
+* The ".montage_cache" file which was previously saved in the same directory
+  as sprites is now saved in the project root.
+
+* The `montage` command now allows you to specify a path to a Montage
+  configuration file; for example `montage path/to/montage.yml`. When using
+  a non-standard directory structure, you can specify a "config.root" option
+  in the configuration file, containing the path to the project root.
+
 v0.2.0 - 2010-04-08
 -------------------
 

data/Rakefile

@@ -20,13 +20,11 @@ begin
     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'
+    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'

data/VERSION

@@ -1 +1 @@
-0.2.1
+0.3.0

data/bin/montage

@@ -4,19 +4,26 @@ unless $:.include?(File.dirname(__FILE__) + '/../lib')
   $:.unshift(File.dirname(__FILE__) + '/../lib')
 end
 
+require 'optparse'
 require 'rubygems' unless ENV['NORUBYGEMS']
 
 require 'montage'
 require 'montage/commands'
 
-Montage::Commands.print_masthead
+require 'highline/import'
+
+module Kernel
+  def_delegators :$terminal, :color
+end
+
+args = Montage::Commands.parse_options!(ARGV.dup)
+puts
 
 case ARGV[0]
   when 'init'
     require 'montage/commands/init'
-    Montage::Commands::Init.run(ARGV)
+    Montage::Commands::Init.run(args)
   else
     require 'montage/commands/generate'
-    Montage::Commands::Generate.run(ARGV)
+    Montage::Commands::Generate.run(args)
 end
-

data/lib/montage/commands/generate.rb

@@ -17,7 +17,20 @@ module Montage
       #   The arguments given on the command line.
       #
       def self.run(argv)
-        new(Montage::Project.find(Dir.pwd), argv.include?('--force')).run!
+        # If there are any arguments, the first one is a path to a montage
+        # config file.
+        if argv.first and not Pathname.new(argv.first).file?
+          say color(<<-ERROR.compress_lines, :red)
+            Couldn't find `#{argv.first}' configuration file. Are you
+            sure you got the path right?
+          ERROR
+
+          exit(1)
+        end
+
+
+        new(Montage::Project.find(argv.first || Dir.pwd),
+            Montage::Commands.config[:force]).run!
 
       rescue Montage::MissingProject
         say color(<<-ERROR.compress_lines, :red)
@@ -52,6 +65,7 @@ module Montage
           optimise_with_pngout!
           write_cache!
           write_sass!
+          warn_deviants!
         end
       end
 
@@ -63,7 +77,7 @@ module Montage
       #
       def cache
         @_sprite_caches ||= begin
-          cache_path = @project.paths.sprites + '.montage_cache'
+          cache_path = @project.paths.root + '.montage_cache'
           cache_path.file? ? YAML.load_file(cache_path) || {} : {}
         end
       end
@@ -75,15 +89,16 @@ module Montage
       #   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
 
+          # Ensure that we can write to the output directory.
+          unless sprite.save_path.dirname.directory?
+            sprite.save_path.dirname.mkpath
+          end
 
-          if @force or cache[sprite.name] != digest or not sprite.path.file?
+          if @force or cache[sprite.name] != digest or
+              not sprite.save_path.file?
             with_feedback %(Generating "#{sprite.name}"), 'Generating' do
               sprite.write
               cache[sprite.name] = digest
@@ -124,18 +139,19 @@ module Montage
         end
 
         @generated.each do |sprite|
-          original_size = sprite.path.size
+          original_size = sprite.save_path.size
+          save_path = sprite.save_path
 
           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`
+              out = `#{pngout} #{save_path} #{save_path} -s0 -k0 -y`
               break if out =~ /Unable to compress further/
             end
           end
 
-          new_size  = sprite.path.size
+          new_size  = save_path.size
 
           reduction = ('%.1fkb (%d' % [
             (original_size.to_f - new_size) / 1024,
@@ -158,7 +174,7 @@ module Montage
       # Step 3: Writes the cached digests to the cache file.
       #
       def write_cache!
-        cache_path = @project.paths.sprites + '.montage_cache'
+        cache_path = @project.paths.root + '.montage_cache'
 
         File.open(cache_path, 'w') do |cache_writer|
           cache_writer.puts YAML.dump(cache)
@@ -176,6 +192,37 @@ module Montage
         end
       end
 
+      # Step 5: Warn about images which are more than one standard deviation
+      # from the mean width.
+      #
+      def warn_deviants!
+        @generated.each do |sprite|
+          next if sprite.sources.size < 2
+
+          mean, std_dev = standard_deviation(sprite.sources.map do |source|
+            source.image.columns
+          end)
+
+          next if std_dev < 100 # Skip relatively narrow images.
+
+          sprite.sources.each do |source|
+            width = source.image.columns
+            if width > mean + std_dev || width < mean - std_dev
+              say <<-MESSAGE.compress_lines
+                The "#{source.name}" source image in the "#{sprite.name}"
+                sprite deviates significantly from the average width. You
+                might want to consider removing this source from the sprite.
+
+                The mean width for sources in this sprite is #{mean}px,
+                while this source is #{width}px wide.
+
+              MESSAGE
+              say Montage::Commands::BLANK
+            end
+          end
+        end
+      end
+
       # --- Optimisation Output ----------------------------------------------
 
       # Executes a block while providing live feedback to the user.
@@ -229,6 +276,20 @@ module Montage
         say "#{RESET}#{prefix}"
       end
 
+      # Knuth. via Wikipedia. :/
+      def 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 # Generate
   end # Commands
 end # Montage

data/lib/montage/commands/init.rb

@@ -72,13 +72,13 @@ module Montage
 
         @sprites_path =
           ask("Where do you want generated sprites to be stored?") do |query|
-            query.default     = 'public/images/sprites'
+            query.default     = File.join('public', 'images')
             query.answer_type = normalise_path
           end
 
         @sources_path =
           ask("Where are the source images stored?") do |query|
-            query.default     = "#{@sprites_path}/src"
+            query.default     = (@sprites_path + "sprites").to_s
             query.answer_type = normalise_path
           end
       end
@@ -94,16 +94,10 @@ module Montage
       #
       def create_config!
         template = File.read(TEMPLATES + 'montage.yml')
-        template.gsub!(/<sprites>/, %("#{@sprites_path.to_s}"))
-        template.gsub!(/<sources>/, %("#{@sources_path.to_s}"))
+        template.gsub!(/<sprites>/, @sprites_path.to_s)
+        template.gsub!(/<sources>/, @sources_path.to_s)
 
-        if (@dir + 'config').directory?
-          config_path = @dir + 'config/montage.yml'
-        else
-          config_path = @dir + 'montage.yml'
-        end
-
-        File.open(config_path, 'w') do |config|
+        File.open(@dir + '.montage', 'w') do |config|
           config.puts template
         end
       end

data/lib/montage/commands.rb

@@ -1,29 +1,62 @@
-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
+    extend self
+
+    # A blank line; HighLine doesn't allow calling +say+ without an argument.
     BLANK = "\n".freeze
 
-    extend self
+    # Returns a configuration hash, containing options defined on the
+    # command-line.
+    #
+    # @return [Hash]
+    #
+    def config
+      @config ||= { :force => false, :quiet => false }
+    end
 
-    # 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
+    # Uses OptParse to parse command-line arguments.
+    #
+    # Returns any unparsed command-line arguments.
+    #
+    def parse_options!(argv)
+      HighLine.use_color = false if !STDOUT.tty? && !ENV.has_key?("AUTOTEST")
+
+      OptionParser.new do |opts|
+        opts.banner = "Usage: montage [config file path] [options]"
+
+        opts.on('-c', '--[no-]color', '--[no-]colour',
+                'Enables and disables colour output.') do |color|
+          HighLine.use_color = color
+        end
+
+        opts.on('-f', '--force',
+                'Regenerate sprites even if no changes have been made.') do
+          Montage::Commands.config[:force] = true
+        end
+
+        # opts.on('-q', '--quiet',
+        #         'Tell Montage to shut up. No messages sent to STDOUT.') do
+        #   Montage::Commands.config[:quiet] = true
+        # end
+
+        opts.on_tail("-h", "--help", "Shows this message.") do
+          say BLANK
+          say opts.to_s
+          exit
+        end
+
+        opts.on_tail("--version", "Print the current Montage version.") do
+          say BLANK
+          say "Montage v#{Montage::VERSION}"
+          exit
+        end
+      end.parse!(argv)
+
+      argv
     end
 
     # Exits immediately, outputting a blank line first.
-    def exit(status)
+    def exit(status = 0)
       say BLANK
       Kernel.exit(status)
     end

data/lib/montage/project.rb

@@ -3,14 +3,16 @@ module Montage
   # configuration file, and source images.
   class Project
     DEFAULTS = {
-      :sources     => 'public/images/sprites/src',
-      :sprites     => 'public/images/sprites',
-      :sass        => 'public/stylesheets/sass',
-      :sprite_url  => '/images/sprites'
+      :sources => 'public/images/sprites/src',
+      :sprites => 'public/images/sprites',
+      :sass    => 'public/stylesheets/sass',
+      :to      => "public/images/:name.png",
+      :url     => "/images/:name.png",
+      :padding => 20
     }
 
     # Stores all the paths the project needs.
-    Paths = Struct.new(:root, :config, :sources, :sprites, :sass, :url)
+    Paths = Struct.new(:root, :config, :sass, :url)
 
     # Returns the Paths instance for the project.
     #
@@ -37,31 +39,29 @@ module Montage
     # to be correct. If you're not sure of the exact paths, use +Project.find+
     # instead.
     #
-    # @param [String, Pathname] root_path
-    #   Path to the root of the Montage project.
     # @param [String, Pathname] config_path
     #   Path to the config file.
     #
-    def initialize(root_path, config_path)
-      root_path   = Pathname.new(root_path)
+    def initialize(config_path)
       config_path = Pathname.new(config_path)
+      config      = YAML.load_file(config_path)
+      root_path   = determine_project_root(config_path, config)
 
-      config = YAML.load_file(config_path)
+      # Sass path may be a string representing a path, or `false`.
+      sass_path = config.delete("config.sass") { DEFAULTS[:sass] }
+      sass_path = sass_path.is_a?(String) ? root_path + sass_path : sass_path
 
       @paths = Paths.new(
-        root_path, config_path,
-        extract_path_from_config(config, :sources, root_path),
-        extract_path_from_config(config, :sprites, root_path),
-        extract_path_from_config(config, :sass,    root_path),
-        config.delete('config.sprite_url') { DEFAULTS[:sprite_url] }
+        root_path, config_path, sass_path,
+        config.delete('config.url') { DEFAULTS[:url] }
       )
 
       @padding = (config.delete('config.padding') || 20).to_i
 
       # All remaining config keys are sprite defintions.
-      @sprites = config.inject([]) do |sprites, (name, sources)|
-        sprites << Sprite.new(name, sources, self)
-      end
+      @sprites = config.map do |path, opts|
+        Montage::SpriteDefinition.new(self, path, opts).to_sprites
+      end.flatten
     end
 
     # Returns a particular sprite identified by +name+.
@@ -82,9 +82,9 @@ module Montage
     #
     # The configuration item will be _removed_ from the hash.
     #
-    # @param [Hash] config    The configuration Hash.
-    # @param [Symbol] key     The configuration key.
-    # @param [Pathname] root  The project root path.
+    # @param [Hash]     config  The configuration Hash.
+    # @param [Symbol]   key     The configuration key.
+    # @param [Pathname] root    The project root path.
     #
     # @return [Pathname, false]
     #
@@ -93,6 +93,30 @@ module Montage
       value.is_a?(String) ? root + value : value
     end
 
+    # Attempts to find the project root for the configuration file. If the
+    # config file is in a directory called 'config' then the project root is
+    # assumed to be one level up.
+    #
+    # @param [Pathname] config_path  The path to the config file.
+    # @param [Hash]     config       The project configuration.
+    #
+    # @return [Pathname]
+    #
+    def determine_project_root(config_path, config)
+      config_dir = config_path.dirname
+
+      if config.has_key?('config.root')
+        root_dir = Pathname.new(config.delete('config.root'))
+        root_dir.absolute? ? root_dir : (config_dir + root_dir)
+      else
+        if config_dir.split.last.to_s == 'config'
+          config_dir + '..'
+        else
+          config_dir
+        end
+      end
+    end
+
     # === Class Methods ======================================================
 
     class << self
@@ -111,7 +135,7 @@ module Montage
       #
       # If given a path to a directory:
       #
-      #   * Montage will look for montage.yml, or config/montage.yml.
+      #   * Montage will look for a .montage file.
       #
       #   * If a configuration couldn't be found, +find+ looks in the next
       #     directory up. It continues until it finds a valid project or runs
@@ -131,37 +155,28 @@ module Montage
         config_path, root_path = nil, nil
 
         if path.file?
-          root_path = find_root(path)
           config_path = path
         elsif path.directory?
-          if config_path = find_config(path)
-            root_path = path
-          else
-            # Assume we're in a subdirectory of the current project.
-            path.split.first.ascend do |directory|
-              if config_path = find_config(directory)
-                break if root_path = find_root(config_path)
-              end
-            end
+          path.ascend do |directory|
+            break if config_path = contains_config?(directory)
           end
         end
 
         raise MissingProject, "Montage couldn't find a project to work " \
-          "on at `#{path}'" if root_path.nil?
+          "on at `#{path}'" unless config_path
 
-        new(root_path, config_path)
+        new(config_path)
       end
 
       private
 
-      # Attempt to find the configuration file, first by looking in
-      # ./montage.yml, then ./config/montage.yml
+      # Looks for a .montage configuration file in the given directory.
       #
       # @return [String]
       #
-      def find_config(dir)
-        config_paths = [ dir + 'montage.yml', dir + 'config/montage.yml' ]
-        config_paths.detect { |config| config.file? }
+      def contains_config?(dir)
+        expected = (dir + '.montage')
+        expected.file? and expected
       end
 
       # Attempts to find the project root for the configuration file. If the

data/lib/montage/source.rb

@@ -3,56 +3,21 @@ module Montage
   #
   class Source
 
-    attr_reader :name
+    attr_reader :name, :path
     alias_method :to_s, :name
 
     # Creates a new Source instance.
     #
-    # @param [Pathname] dir
-    #   The directory in which the source image should stored.
-    # @param [String] name
-    #   The name of the source image, sans extension
-    # @param [String] sprite
-    #   The name of the sprite to which the source belongs. Used only in
-    #   error messages.
+    # @param [Pathname] path
+    #   The path the the source image.
     #
-    def initialize(dir, name, sprite_name)
-      @dir, @name, @sprite_name = dir, name, sprite_name
+    def initialize(path)
+      @path = Pathname.new(path)
+      @name = @path.basename.to_s.chomp(@path.extname.to_s)
     end
 
     def inspect # :nodoc
-      "#<Montage::Source #{@sprite_name}:#{@name}>"
-    end
-
-    # Returns the full path to the source image.
-    #
-    # @return [Pathname]
-    # @raise  [Montage::MissingSource]
-    #
-    def path
-      @path ||= begin
-        unless @dir.directory?
-          raise MissingSource, <<-MESSAGE.compress_lines
-            Couldn't find the source directory for the `#{@sprite_name}'
-            sprite. Montage was looking for #{@dir}; if your sprites are in a
-            different location, add a 'config.sources' option your config
-            file.
-          MESSAGE
-        end
-
-        path = @dir.entries.detect do |entry|
-          entry.to_s.chomp(entry.extname) == @name
-        end
-
-        if path.nil?
-          raise MissingSource, <<-MESSAGE.compress_lines
-            Couldn't find a matching file for source image `#{@name}' as part
-            of the `#{@sprite_name}' sprite. Was looking in `#{@dir}'.
-          MESSAGE
-        end
-
-        @dir + path
-      end
+      "#<Montage::Source #{@name}>"
     end
 
     # Returns the RMagick image instance representing the source.
@@ -60,7 +25,10 @@ module Montage
     # @return [Magick::Image]
     #
     def image
-      @image ||= Magick::Image.read(path).first
+      raise MissingSource, "Couldn't find the source file `#{@path}'" \
+        unless @path.file?
+
+      @image ||= Magick::Image.read(@path).first
     end
 
     # Returns a digest which represents the sprite name and file contents.
@@ -68,7 +36,10 @@ module Montage
     # @return [String]
     #
     def digest
-      Digest::SHA256.hexdigest(@name + Digest::SHA256.file(path).to_s)
+      raise MissingSource, "Couldn't find the source file `#{@path}'" \
+        unless @path.file?
+
+      Digest::SHA256.hexdigest(@name + Digest::SHA256.file(@path).to_s)
     end
 
   end # Source