montage 0.2.1

data/lib/montage/commands/init.rb

@@ -0,0 +1,119 @@
+module Montage
+  module Commands
+    # Creates a new project.
+    class Init
+      extend Commands
+
+      # Path to lib/templates
+      TEMPLATES = Pathname.new(__FILE__).dirname.parent + 'templates'
+
+      # === Class Methods ====================================================
+
+      # Creates a new project in the current directory.
+      #
+      # @param [Array] argv
+      #   The arguments given on the command line.
+      #
+      def self.run(*)
+        new(Dir.pwd).run!
+
+      rescue Montage::ProjectExists => e
+        if e.message.match(/`(.*)'$/)[1] == Dir.pwd
+          say color("A Montage project already exists in the " \
+            "current directory", :red)
+        else
+          say color(e.message.compress_lines, :red)
+        end
+
+        exit(1)
+      end
+
+      # === Instance Methods =================================================
+
+      # Creates a new Generate instance.
+      #
+      # @param [Pathname]
+      #   The directory in which a new project is to be created.
+      #
+      def initialize(dir)
+        @dir = Pathname.new(dir)
+      end
+
+      # Runs the command, creating the new project structure.
+      #
+      def run!
+        begin
+          found = Project.find(@dir)
+        rescue MissingProject
+          ask_questions!
+          make_directories!
+          create_config!
+          copy_sources!
+          say color("Your project was created", :green)
+          say Montage::Commands::BLANK
+        else
+          raise Montage::ProjectExists, <<-ERROR.compress_lines
+            A Montage project exists in a parent directory at
+            `#{found.paths.root}'
+          ERROR
+        end
+      end
+
+      private # ==============================================================
+
+      # Step 1: Ask the user where they want files to be stored.
+      #
+      def ask_questions!
+        normalise_path = lambda do |path|
+          npath = Pathname.new(path).expand_path
+          npath = npath.relative_path_from(@dir) unless path[0].chr == '/'
+          npath
+        end
+
+        @sprites_path =
+          ask("Where do you want generated sprites to be stored?") do |query|
+            query.default     = 'public/images/sprites'
+            query.answer_type = normalise_path
+          end
+
+        @sources_path =
+          ask("Where are the source images stored?") do |query|
+            query.default     = "#{@sprites_path}/src"
+            query.answer_type = normalise_path
+          end
+      end
+
+      # Step 2: Make the sprites and sources directories.
+      #
+      def make_directories!
+        @sprites_path.mkpath unless @sprites_path.directory?
+        @sources_path.mkpath unless @sources_path.directory?
+      end
+
+      # Step 3: Write the configuration.
+      #
+      def create_config!
+        template = File.read(TEMPLATES + 'montage.yml')
+        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|
+          config.puts template
+        end
+      end
+
+      # Step 4: Copy the sample source images.
+      #
+      def copy_sources!
+        FileUtils.cp_r(TEMPLATES + 'sources/.', @sources_path)
+      end
+
+    end # Init
+  end # Commands
+end # Montage

data/lib/montage/core_ext.rb

@@ -0,0 +1,80 @@
+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"
+  #
+  # @param [TrueClass, FalseClass] spaced (default=true)
+  #   Determines whether returned string has whitespace collapsed or removed
+  #
+  # @return [String] Receiver with whitespace (including newlines) replaced
+  #
+  def compress_lines(spaced = true)
+    split($/).map { |line| line.strip }.join(spaced ? ' ' : '')
+  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/montage/project.rb

@@ -0,0 +1,185 @@
+module Montage
+  # Represents a directory in which it is expected that there be a
+  # 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'
+    }
+
+    # Stores all the paths the project needs.
+    Paths = Struct.new(:root, :config, :sources, :sprites, :sass, :url)
+
+    # Returns the Paths instance for the project.
+    #
+    # @return [Montage::Project::Paths]
+    #
+    attr_reader :paths
+
+    # Returns an Array containing all the Sprites defined in the project.
+    #
+    # @return [Array<Montage::Sprite>]
+    #
+    attr_reader :sprites
+
+    # Returns the amount of space to be used between each source image when
+    # saving sprites.
+    #
+    # @return [Integer]
+    #
+    attr_reader :padding
+
+    # Creates a new Project instance.
+    #
+    # Note that +new+ does no validation of the given paths: it expects them
+    # 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)
+      config_path = Pathname.new(config_path)
+
+      config = YAML.load_file(config_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] }
+      )
+
+      @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
+    end
+
+    # Returns a particular sprite identified by +name+.
+    #
+    # @param [String] name
+    #   The name of the sprite to be retrieved.
+    #
+    # @return [Montage::Sprite]
+    #
+    def sprite(name)
+      sprites.detect { |sprite| sprite.name == name }
+    end
+
+    private # ================================================================
+
+    # Extracts a configuration value from a configuration hash. If the value
+    # exists, and is a string, it will be appended to the +root+ path.
+    #
+    # 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.
+    #
+    # @return [Pathname, false]
+    #
+    def extract_path_from_config(config, key, root)
+      value = config.delete("config.#{key}") { DEFAULTS[key] }
+      value.is_a?(String) ? root + value : value
+    end
+
+    # === Class Methods ======================================================
+
+    class << self
+
+      # Given a path to a directory, or config file, attempts to find the
+      # Montage root.
+      #
+      # If given a path to a file:
+      #
+      #   * Montage assumes that the file is the configuration.
+      #
+      #   * The root directory is assumed to be the same directory as the one
+      #     in which the configuration resides _unless_ the directory is
+      #     called 'config', in which case the root is considered to be the
+      #     parent directory.
+      #
+      # If given a path to a directory:
+      #
+      #   * Montage will look for montage.yml, or config/montage.yml.
+      #
+      #   * If a configuration couldn't be found, +find+ looks in the next
+      #     directory up. It continues until it finds a valid project or runs
+      #     out of parent directories.
+      #
+      # @param [String, Pathname] path
+      #   Path to the configuration or directory.
+      #
+      # @return [Montage::Project]
+      #   Returns the project.
+      #
+      # @raise [MissingProject]
+      #   Raised when a project directory couldn't be found.
+      #
+      def find(path)
+        path = Pathname(path).expand_path
+        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
+          end
+        end
+
+        raise MissingProject, "Montage couldn't find a project to work " \
+          "on at `#{path}'" if root_path.nil?
+
+        new(root_path, config_path)
+      end
+
+      private
+
+      # Attempt to find the configuration file, first by looking in
+      # ./montage.yml, then ./config/montage.yml
+      #
+      # @return [String]
+      #
+      def find_config(dir)
+        config_paths = [ dir + 'montage.yml', dir + 'config/montage.yml' ]
+        config_paths.detect { |config| config.file? }
+      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.
+      #
+      # @return [String]
+      #
+      def find_root(config)
+        config_dir = config.dirname
+
+        if config_dir.split.last.to_s == 'config'
+          (config_dir + '..').expand_path
+        else
+          config_dir
+        end
+      end
+
+    end # class << self
+  end # Project
+end # Montage

data/lib/montage/sass_builder.rb

@@ -0,0 +1,37 @@
+module Montage
+  # Given a project, builds a SASS file containing mixin to simplify use of
+  # the generated sprites in a project.
+  #
+  class SassBuilder
+
+    TEMPLATE = Pathname.new(__FILE__).dirname + 'templates/sass_mixins.erb'
+
+    # Creates a new SassBuilder instance.
+    #
+    # @param [Montage::Project] project
+    #   The project whose Sass file is to be built.
+    #
+    def initialize(project)
+      @project = project
+    end
+
+    # Builds the Sass mixin file, then writes it to disk.
+    #
+    # @return [Boolean]
+    #
+    def write
+      if @project.paths.sass.to_s[-5..-1] == '.sass'
+        @project.paths.sass.dirname.mkpath
+        save_to = @project.paths.sass
+      else
+        @project.paths.sass.mkpath
+        save_to = @project.paths.sass + '_montage.sass'
+      end
+
+      File.open(save_to, 'w') do |file|
+        file.puts ERB.new(File.read(TEMPLATE), nil, '<>').result(binding)
+      end
+    end
+
+  end # SassBuilder
+end

data/lib/montage/source.rb

@@ -0,0 +1,75 @@
+module Montage
+  # Represents a single source file used in a sprite.
+  #
+  class Source
+
+    attr_reader :name
+    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.
+    #
+    def initialize(dir, name, sprite_name)
+      @dir, @name, @sprite_name = dir, name, sprite_name
+    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
+    end
+
+    # Returns the RMagick image instance representing the source.
+    #
+    # @return [Magick::Image]
+    #
+    def image
+      @image ||= Magick::Image.read(path).first
+    end
+
+    # Returns a digest which represents the sprite name and file contents.
+    #
+    # @return [String]
+    #
+    def digest
+      Digest::SHA256.hexdigest(@name + Digest::SHA256.file(path).to_s)
+    end
+
+  end # Source
+end # Montage