montage 0.2.1 → 0.3.0

data/lib/montage/sprite.rb

@@ -2,34 +2,30 @@ module Montage
   # Represents a collection of images which will be used to make a sprite.
   #
   class Sprite
-    attr_reader :name
+    attr_reader :name, :save_path, :url, :padding, :sources
 
     # Creates a new Sprite instance.
     #
     # @param [String] name
     #   The name of the sprite. Will be used as the sprite filename (with an
     #   extension added).
-    # @param [Array<String>] sources
+    # @param [Array(String, Pathname)] sources
     #   The name of each source image.
-    # @param [Project] Project
+    # @param [Pathname] save_path
+    #   The location at which the sprite should be saved.
+    # @param [Montage::Project] project
     #   The project to which the sprite belongs.
+    # @param [Hash] options
+    #   Extra options where you wish to override project defaults.
     #
-    def initialize(name, sources, project)
-      @name, @project = name, project
+    def initialize(name, sources, save_path, project, options = {})
+      @name      = name
+      @save_path = save_path
 
-      @sources =
-        sources.inject(ActiveSupport::OrderedHash.new) do |hash, source|
-          hash[source] = Source.new(@project.paths.sources, source, @name)
-          hash
-        end
-    end
+      @padding   = options.fetch(:padding, project.padding)
+      @url       = options.fetch(:url, project.paths.url)
 
-    # Returns an array of Source instances held by this Sprite.
-    #
-    # @return [Array<Source>]
-    #
-    def sources
-      @sources.map { |_, source| source }
+      @sources   = sources.map { |path| Source.new(path) }
     end
 
     # Returns an array of RMagick image instances; one for each source.
@@ -41,23 +37,15 @@ module Montage
       sources.map { |source| source.image }
     end
 
-    # Returns the path to the sprite on disk.
-    #
-    # @return [Pathname]
-    #
-    def path
-      @project.paths.sprites + "#{@name}.png"
-    end
-
     # Returns the y-position of a given source.
     #
     # @return [Integer, Source]
     #   The vertical position of the source image.
     #
     def position_of(source)
-      source = source.name if source.is_a?(Source)
+      source = source.name if source.is_a?(Montage::Source)
 
-      unless @sources.keys.include?(source)
+      unless sources.detect { |src| src.name == source }
         raise MissingSource,
           "Source image '#{source}' is not present in the '#{@name}' sprite"
       end
@@ -69,9 +57,9 @@ module Montage
         # generating CSS), it works out faster to fetch each source height
         # just once.
         @positions = {}
-        @sources.inject(0) do |offset, (name, src)|
-          @positions[name] = offset
-          offset + src.image.rows + 20
+        @sources.inject(0) do |offset, src|
+          @positions[src.name] = offset
+          offset + src.image.rows + @padding
         end
       end
 
@@ -96,22 +84,22 @@ module Montage
     #   Raised when the output directory can not be written to.
     #
     def write
-      unless @project.paths.sprites.writable?
+      unless @save_path.dirname.writable?
         raise TargetNotWritable, <<-MESSAGE
-          Montage can't save the sprite in `#{@project.paths.sprites.to_s}'
+          Montage can't save the sprite in `#{@save_path.dirname.to_s}'
           as it isn't writable.
         MESSAGE
       end
 
-      list = sources.inject(Magick::ImageList.new) do |list, source|
+      list = @sources.inject(Magick::ImageList.new) do |list, source|
         list << source.image
-        list << Magick::Image.new(1, @project.padding) do
+        list << Magick::Image.new(1, @padding) do
           self.background_color = '#FFF0'
         end
       end
 
       # RMagick uses instance_eval, @set isn't available in the block below.
-      sources_length = sources.length
+      sources_length = @sources.length
 
       montage = list.montage do
         self.gravity = Magick::NorthWestGravity
@@ -124,8 +112,8 @@ module Montage
       end
 
       # Remove the blank space from the bottom of the image.
-      montage.crop!(0, 0, 0, (montage.first.rows) - @project.padding)
-      montage.write("PNG32:#{path}")
+      montage.crop!(0, 0, 0, (montage.first.rows) - @padding)
+      montage.write("PNG32:#{@save_path}")
     end
 
   end # Set

data/lib/montage/sprite_definition.rb

@@ -0,0 +1,127 @@
+module Montage
+  # Represents a pseudo-file system path, where a directory can be replaced
+  # with the :sprite named segment. :name will match any directory -- all
+  # files with the same :name value will be placed into the same sprite file.
+  #
+  # Where a sprite source defines a :name segment, no sprite name needs to be
+  # explicitly set in the .montage file.
+  #
+  # For example, given the following directory structure:
+  #
+  #   /path/to/something/
+  #     big/
+  #       one.png
+  #       two.png
+  #     small/
+  #       three.png
+  #       four.png
+  #
+  # ... then segmented path "/path/to/something/:name/*" will match all four
+  # PNG files, with "one" and "two" being placed in the "big" sprite, "three"
+  # and "four" in the "small" sprite.
+  #
+  class SpriteDefinition
+    # Creates a new SpriteDefinition instance.
+    #
+    # @param [Montage::Project]       project
+    # @param [String, Pathname]       path
+    # @param [Hash{String => Object}] options
+    #
+    def initialize(project, path, options = {})
+      @project = project
+      @path    = project.paths.root + path
+
+      # Symbolize option keys.
+      @options = options.inject({}) do |opts, (key, value)|
+        opts[key.to_sym] = value ; opts
+      end
+
+      @options[:to] = (@project.paths.root +
+                      (@options[:to] || Project::DEFAULTS[:to])).to_s
+
+      @options[:url]     ||= project.paths.url
+      @options[:padding] ||= project.padding
+
+      if has_name_segment? and @options.has_key?(:name)
+        raise Montage::DuplicateName, <<-ERROR.compress_lines
+          Sprite `#{path}' has both a :name path segment and a "name"
+          option; please use only one.
+        ERROR
+      elsif not has_name_segment? and not @options.has_key?(:name)
+        raise Montage::MissingName, <<-ERROR.compress_lines
+          Sprite `#{path}' requires a name. Add a :name path segment
+          or add a "name" option.
+        ERROR
+      elsif has_name_segment? and not @options[:to] =~ /:name/
+        raise Montage::MissingName, <<-ERROR.compress_lines
+          Sprite `#{path}' requires :name in the "to" option.
+        ERROR
+      end
+    end
+
+    # Returns an array of Sprites defined.
+    #
+    # @return [Array(Montage::Sprite)]
+    #
+    def to_sprites
+      matching_sources.map do |sprite_name, sources|
+        save_path = Pathname.new(@options[:to].gsub(/:name/, sprite_name))
+
+        url = @options[:url].dup # Since it may be the DEFAULT string
+        url.gsub!(/:name/, sprite_name)
+        url.gsub!(/:filename/, save_path.basename.to_s)
+
+        Montage::Sprite.new(sprite_name, sources, save_path, @project,
+          :url     => url,
+          :padding => @options[:padding]
+        )
+      end
+    end
+
+    private # ================================================================
+
+    # Returns whether the path has a :name segment.
+    #
+    # @return [Boolean]
+    #
+    def has_name_segment?
+      @path.to_s =~ /:name/
+    end
+
+    # Returns a Hash containing source files which can be used when creating
+    # Sprites. Each key is sprite name with each value the path to a matching
+    # source file. When a SpriteDefinition doesn't have a :name segment, the
+    # Hash will contain a single key: nil.
+    #
+    # @return[Hash{String => Array(Pathname)}]
+    #
+    def matching_sources
+      @matching_sources ||= begin
+        if not has_name_segment?
+          { @options[:name] => Pathname.glob(@path.to_s) }
+        else
+          regexp = Regexp.escape(@path.to_s)
+          regexp.gsub!(/\\\*\\\*/, '.+')
+          regexp.gsub!(/\\\*/,     '[^\\/]+')
+          regexp.gsub!(/:name/,    '([^\\/]+)')
+
+          # Replace OR globs ({png,jpg,etc}).
+          regexp.gsub!(/\\\{([^\\\}]+)\\\}/) do |found|
+            "(?:#{found[2..-4].split(',').join('|')})"
+          end
+
+          all_files = Pathname.glob(@path.to_s.gsub(/:name/, '*'))
+          all_files.inject({}) do |sources, file|
+            if file.file? && match = file.to_s.match(regexp)
+              sources[match[1]] ||= []
+              sources[match[1]] << file
+            end
+
+            sources
+          end
+        end
+      end # begin
+    end # matching_sources
+
+  end # SpriteDefinition
+end # Montage

data/lib/montage/templates/montage.yml

@@ -1,26 +1,36 @@
 ---
 
-  # If you need to specify non-standard locations for the source
-  # files, or the output locations for the sprites or SASS, change
-  # the relevant option below. Directories are relative to the
-  # project root unless they have a leading slash.
+  config.root: "."
+  config.sass: "public/stylesheets/sass"
+  config.url:  "/images/:filename"
 
-  config.sources:    <sources>
-  config.sprites:    <sprites>
-  config.sass:       "public/stylesheets/sass"
-  config.sprite_url: "/images/sprites"
+  # --------------------------------------------------------------
 
-  # --------------------------------------------------------------------------
+  # The sample definition below will search each sub-directory in
+  # the sources directory; a sprite will be created for each sub-
+  # directory containing the png, jpg, and gif files.
+  #
+  # All paths are relative to the project root file, unless they
+  # begin with a / in which case they are absolute. Add as many
+  # sprite definitions as you need.
 
-  # The sample below will produce two sprites (one.png and two.png) with the
-  # specified source images. You can omit file extensions.
+  "<sources>/:name/*.{png,jpg,jpeg,gif}":
+    to: "<sprites>/:name.png"
 
-  one:
-    - book
-    - box-label
-    - calculator
+  # You can override any of the default settings on a per-sprite
+  # basis. For example... (these are the defaults)
 
-  two:
-    - calendar-month
-    - camera
-    - eraser
+  # "public/images/sprites/src/:name/*.{png,jpg,jpeg,gif}":
+  #   to: "public/images/:name.png"
+  #
+  #   # The directory in which the sprite(s) are saved relative to
+  #   # the web-root (used in Sass files to locate the image).
+  #   url: "/images/:filename"
+  #
+  #   # Puts 20 pixels of space between each source image.
+  #   padding: 20
+
+  # # Alternatively, change the default settings for all sprites:
+  #
+  # config.url: "/omicron_persei_8/sprites"
+  # config.sass: false

data/lib/montage/templates/sass_mixins.erb

@@ -8,7 +8,7 @@
   @<%= index == 0 ? '' : 'else ' %>if $icon == "<%= source.name %>"
     $y_offset: $y_offset - <%= sprite.position_of(source) %>px
 <% end %>
-  background: url(<%= @project.paths.url + "/#{sprite.name}.png" %>) $x_offset $y_offset no-repeat
+  background: url(<%= sprite.url %>) $x_offset $y_offset no-repeat
 
 =<%= sprite.name %>-sprite-pos($icon, $x_offset: 0px, $y_offset: 0px)
 <% sprite.sources.each_with_index do |source, index| %>

data/lib/montage.rb

@@ -4,7 +4,6 @@ require 'pathname'
 require 'yaml'
 
 # Gems.
-require 'active_support/ordered_hash'
 require 'rmagick'
 
 # On with the library...
@@ -13,6 +12,7 @@ require 'montage/project'
 require 'montage/sass_builder'
 require 'montage/source'
 require 'montage/sprite'
+require 'montage/sprite_definition'
 require 'montage/version'
 
 module Montage
@@ -30,4 +30,13 @@ module Montage
 
   # Raised when a sprite can't be saved due to incorrect permissions.
   TargetNotWritable = Class.new(MontageError)
+
+  # Raised when a sprite defintion doesn't include a name.
+  MissingName = Class.new(MontageError)
+
+  # Raised when a sprite defines a :name path segment, and a name option.
+  DuplicateName = Class.new(MontageError)
+
+  # Raised when a sprite definition doesn't have a to option.
+  MissingTo = Class.new(MontageError)
 end

data/montage.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{montage}
-  s.version = "0.2.1"
+  s.version = "0.3.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Anthony Williams"]
-  s.date = %q{2010-04-08}
+  s.date = %q{2010-04-12}
   s.default_executable = %q{montage}
   s.description = %q{Even Rocky had a montage.}
   s.email = %q{hi@antw.me}
@@ -36,36 +36,24 @@ Gem::Specification.new do |s|
      "lib/montage/sass_builder.rb",
      "lib/montage/source.rb",
      "lib/montage/sprite.rb",
+     "lib/montage/sprite_definition.rb",
      "lib/montage/templates/montage.yml",
      "lib/montage/templates/sass_mixins.erb",
-     "lib/montage/templates/sources/book.png",
-     "lib/montage/templates/sources/box-label.png",
-     "lib/montage/templates/sources/calculator.png",
-     "lib/montage/templates/sources/calendar-month.png",
-     "lib/montage/templates/sources/camera.png",
-     "lib/montage/templates/sources/eraser.png",
+     "lib/montage/templates/sources/one/book.png",
+     "lib/montage/templates/sources/one/box-label.png",
+     "lib/montage/templates/sources/one/calculator.png",
+     "lib/montage/templates/sources/one/calendar-month.png",
+     "lib/montage/templates/sources/one/camera.png",
+     "lib/montage/templates/sources/one/eraser.png",
+     "lib/montage/templates/sources/two/inbox-image.png",
+     "lib/montage/templates/sources/two/magnet.png",
+     "lib/montage/templates/sources/two/newspaper.png",
+     "lib/montage/templates/sources/two/television.png",
+     "lib/montage/templates/sources/two/wand-hat.png",
+     "lib/montage/templates/sources/two/wooden-box-label.png",
      "lib/montage/version.rb",
      "montage.gemspec",
-     "spec/fixtures/custom_dirs/montage.yml",
-     "spec/fixtures/default/montage.yml",
-     "spec/fixtures/default/public/images/sprites/src/one.png",
-     "spec/fixtures/default/public/images/sprites/src/three.png",
-     "spec/fixtures/default/public/images/sprites/src/two.png",
-     "spec/fixtures/directory_config/config/montage.yml",
-     "spec/fixtures/missing_source/montage.yml",
-     "spec/fixtures/missing_source_dir/montage.yml",
-     "spec/fixtures/root_config/montage.yml",
-     "spec/fixtures/root_config/public/images/sprites/src/source_one.png",
-     "spec/fixtures/root_config/public/images/sprites/src/source_three.jpg",
-     "spec/fixtures/root_config/public/images/sprites/src/source_two",
-     "spec/fixtures/sources/hundred.png",
-     "spec/fixtures/sources/mammoth.png",
-     "spec/fixtures/sources/other.png",
-     "spec/fixtures/sources/twenty.png",
-     "spec/fixtures/subdirs/montage.yml",
-     "spec/fixtures/subdirs/sub/sub/keep",
      "spec/lib/command_runner.rb",
-     "spec/lib/fixtures.rb",
      "spec/lib/have_public_method_defined.rb",
      "spec/lib/project_helper.rb",
      "spec/lib/shared_project_specs.rb",
@@ -77,6 +65,7 @@ Gem::Specification.new do |s|
      "spec/montage/sass_builder_spec.rb",
      "spec/montage/source_spec.rb",
      "spec/montage/spec/have_public_method_defined_spec.rb",
+     "spec/montage/sprite_definition_spec.rb",
      "spec/montage/sprite_spec.rb",
      "spec/rcov.opts",
      "spec/spec.opts",
@@ -92,7 +81,6 @@ Gem::Specification.new do |s|
   s.summary = %q{Montage}
   s.test_files = [
     "spec/lib/command_runner.rb",
-     "spec/lib/fixtures.rb",
      "spec/lib/have_public_method_defined.rb",
      "spec/lib/project_helper.rb",
      "spec/lib/shared_project_specs.rb",
@@ -104,6 +92,7 @@ Gem::Specification.new do |s|
      "spec/montage/sass_builder_spec.rb",
      "spec/montage/source_spec.rb",
      "spec/montage/spec/have_public_method_defined_spec.rb",
+     "spec/montage/sprite_definition_spec.rb",
      "spec/montage/sprite_spec.rb",
      "spec/spec_helper.rb"
   ]
@@ -113,30 +102,24 @@ Gem::Specification.new do |s|
     s.specification_version = 3
 
     if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<activesupport>, [">= 3.0.0.beta"])
       s.add_runtime_dependency(%q<rmagick>, [">= 2.12"])
       s.add_runtime_dependency(%q<highline>, [">= 1.5"])
       s.add_development_dependency(%q<rspec>, [">= 1.3.0"])
-      s.add_development_dependency(%q<cucumber>, [">= 0.6"])
       s.add_development_dependency(%q<open4>, [">= 1.0"])
       s.add_development_dependency(%q<haml>, [">= 3.0.0.beta.1"])
       s.add_development_dependency(%q<yard>, [">= 0.5"])
     else
-      s.add_dependency(%q<activesupport>, [">= 3.0.0.beta"])
       s.add_dependency(%q<rmagick>, [">= 2.12"])
       s.add_dependency(%q<highline>, [">= 1.5"])
       s.add_dependency(%q<rspec>, [">= 1.3.0"])
-      s.add_dependency(%q<cucumber>, [">= 0.6"])
       s.add_dependency(%q<open4>, [">= 1.0"])
       s.add_dependency(%q<haml>, [">= 3.0.0.beta.1"])
       s.add_dependency(%q<yard>, [">= 0.5"])
     end
   else
-    s.add_dependency(%q<activesupport>, [">= 3.0.0.beta"])
     s.add_dependency(%q<rmagick>, [">= 2.12"])
     s.add_dependency(%q<highline>, [">= 1.5"])
     s.add_dependency(%q<rspec>, [">= 1.3.0"])
-    s.add_dependency(%q<cucumber>, [">= 0.6"])
     s.add_dependency(%q<open4>, [">= 1.0"])
     s.add_dependency(%q<haml>, [">= 3.0.0.beta.1"])
     s.add_dependency(%q<yard>, [">= 0.5"])

data/spec/lib/project_helper.rb

@@ -34,8 +34,8 @@ module Montage
         self.class.cleanup!
         project_dir.mkpath
 
-        self.sources_path = "public/images/sprites/src"
-        self.sprites_path = "public/images/sprites"
+        self.sources_path = "public/images/sprites"
+        self.sprites_path = "public/images"
       end
 
       def sources_path=(path)
@@ -86,17 +86,40 @@ module Montage
 
       # --- File Writers -----------------------------------------------------
 
-      # Writes montage.yml file in the project root with the given contents.
+      # Writes .montage file in the project root with the given contents.
       #
+      # @param [String] to
+      #   The path at which to save the config file. Or: The file contents if
+      #   you want to save at the default location.
       # @param [String] contents
       #   The contents to be saved as the config file.
       #
-      def write_config(contents)
-        File.open(project_dir + 'montage.yml', 'w') do |file|
+      def write_config(to, contents = nil)
+        if contents.nil?
+          # Sigh; if only 1.9 was more popular...
+          contents, to = to, '.montage'
+        else
+          (project_dir + to).dirname.mkpath
+        end
+
+        File.open(project_dir + to, 'w') do |file|
           file.puts contents.unindent
         end
       end
 
+      # Writes a simple config file.
+      #
+      # @param [String] to
+      #   The path at which to save the config file.
+      #
+      def write_simple_config(to = '.montage')
+        write_config to, <<-CONFIG
+          ---
+            "public/images/sprites/:name/*.{png,jpg,jpeg,gif}":
+              to: "public/images/:name.png"
+        CONFIG
+      end
+
       # Writes a source image file to the src directory.
       #
       # @param [String] name
@@ -123,13 +146,25 @@ module Montage
 
       # Creates a directory in the project.
       #
-      # @param [String] dir
+      # @param [String] path
       #   Path to the directory, relative to the project root.
       #
       def mkdir(path)
         (project_dir + path).mkpath
       end
 
+      # Creates an empty file.
+      #
+      # @param [String] path
+      #   Path to the file to be touched.
+      #
+      def touch(*paths)
+        paths.each do |path|
+          (project_dir + path).dirname.mkpath
+          FileUtils.touch(project_dir + path)
+        end
+      end
+
     end # ProjectHelper
   end # Spec
 end # Montage

data/spec/lib/shared_project_specs.rb

@@ -2,9 +2,16 @@ describe 'a project with correct paths', :shared => true do
   # Requires:
   #
   #   @project => Montage::Project
-  #   @root    => Pathname (path to project root)
+  #   @helper  => Montage::Spec::ProjectHelper
   #   @config  => Pathname (path to config file)
   #
+  #   (optional)
+  #   @root    => Pathname (path to the root of the project)
+  #
+
+  before(:all) do
+    @root ||= @helper.project_dir
+  end
 
   it 'should set the project root path' do
     @project.paths.root.should == @root
@@ -14,19 +21,11 @@ describe 'a project with correct paths', :shared => true do
     @project.paths.config.should == @config
   end
 
-  it 'should set the sources path' do
-    @project.paths.sources.should == @root + 'public/images/sprites/src'
-  end
-
-  it 'should set the sprite path' do
-    @project.paths.sprites.should == @root + 'public/images/sprites'
-  end
-
   it 'should set the SASS output path' do
     @project.paths.sass.should == @root + 'public/stylesheets/sass'
   end
 
   it 'should set the CSS sprite URL' do
-    @project.paths.url.should == '/images/sprites'
+    @project.paths.url.should == '/images/:name.png'
   end
-end
+end