polymer 1.0.0.beta.3

data/Gemfile

@@ -0,0 +1,8 @@
+source 'http://rubygems.org'
+
+gemspec
+
+group(:quality) do
+  gem 'bluecloth', '>= 2.0.7'
+  gem 'yard',      '>= 0.6'
+end

data/History.md

@@ -0,0 +1,126 @@
+v1.0.0 / HEAD (Unreleased)
+--------------------------
+
+* Montage has been renamed to Polymer and is now released under the BSD
+  three-clause license.
+
+* The Polymer configuration must now be located at the project root and
+  should be named either ".polymer" or, for Windows users, "polymer.yml".
+  You should rename your existing ".montage" file to ".polymer", and
+  ".montage\_cache" should be changed to ".polymer-cache".
+
+* The Polymer configuration file no longer uses YAML, but instead opts
+  for a simple Ruby-based DSL. See `polymer help .polymer` for full
+  documentation.
+
+* The Sass mixin has changed slightly; instead of generating separate
+  mixins for each of your sprites, all of your sprites are available
+  using the global "polymer()" mixin. This should be called as such:
+
+      .my_selector
+        +polymer("sprite_name/source_name")
+
+  Mixins still permit you to supply an optional x-offset and y-offset as
+  the second and third parameters. the "polymer-pos()" mixin is also
+  available as an alternative to the old "sprite-name-pos()" mixins.
+
+* A new "position" command shows information about a source within a
+  sprite, and provides useful CSS for use when building your own
+  styleesheets.
+
+* Documentation of each command is now available by running `polymer
+  help` or `polymer help [COMMAND]`.
+
+* The Polymer configuration no longer allows a "config.root" option and
+  the library will not work correctly if this is present in your config
+  file. Please move your ".polymer" file to your project root and remove
+  this option.
+
+* The library internals have been substantially changed with Thor now
+  being used to handle all CLI commands.
+
+* When creating a new Polymer project, you may suppress the copying of
+  example sources by passing the --no-examples option.
+
+* The polymer init command no longer uses Highline to prompt for your
+  preferred paths to your source and output files. If you need to change
+  the defaults you may instead use the --source and --sprites options.
+
+* All CLI commands are now tested with Cucumber.
+
+* Jeweler has been replaced with plain rake tasks inspired by Rakegem --
+  [http://github.com/mojombo/rakegem](http://github.com/mojombo/rakegem).
+
+v0.4.0 (18th August, 2010)
+--------------------------
+
+* You no longer need to specify a :name option in your sprite defintions
+  when supplying a full output filename.
+
+v0.3.0 (12th April, 2010)
+-------------------------
+
+* 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 (8th April, 2010)
+------------------------
+
+* 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 (6th April, 2010)
+------------------------
+
+* 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 (5th April, 2010)
+------------------------
+
+* Small fix for Ruby 1.9.1, which doesn't define String#inject.
+
+v0.1.0 (5th April, 2010)
+------------------------
+
+* Initial release. Supports creation of sprites and not much else.

data/LICENSE

@@ -0,0 +1,28 @@
+Copyright (c) 2009-2010, Anthony Williams
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+  * Redistributions of source code must retain the above copyright notice,
+    this list of conditions and the following disclaimer.
+
+  * Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in the
+    documentation and/or other materials provided with the distribution.
+
+  * Neither the name of the Anthony Williams nor the names of its
+    contributors may be used to endorse or promote products derived from
+    this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL ANTHONY WILLIAMS BE LIABLE FOR ANY DIRECT,
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
+OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

data/README.md

@@ -0,0 +1,229 @@
+POLYMER
+=======
+
+DESCRIPTION
+-----------
+
+Polymer is a tool for creating sprite images which combine many smaller
+sources into a single larger image. Spriting allows you to reduce the
+number of HTTP requests required to load a web page, and as such can
+result in reduced load times.
+
+Polymer also creates the necessary CSS to position the sprite within an
+HTML element so that only the desired source appears. Those writing
+their website or application in Ruby can make use of Polymer's Sass
+builder which creates a Sass mixin, further simplifying the use of your
+sprites.
+
+In order to reduce the amount of data transferred to clients loading
+your pages, Polymer optimises the sprites it generates using PNGOUT,
+OptiPNG, and PNGCrush.
+
+INSTALLATION
+------------
+
+The recommended way to install Polymer is with Rubygems:
+
+    $ [sudo] gem install polymer
+
+Polymer currently uses RMagick/ImageMagick in order to read and write
+images. Eventually, I want to offer support for ChunkyPNG also, which
+should substantially ease installation.
+
+Most Linux and BSD distributions include ImageMagick in their packaging
+system; while Mac OS X users can install it with [Homebrew][homebrew]:
+
+    $ brew install ghostscript
+    $ brew install imagemagick
+
+If you wish to install Polymer from source:
+
+    $ git clone http://github.com/antw/polymer.git && cd polymer
+    $ gem build polymer.gemspec
+    $ [sudo] gem install --local polymer-VERSION.gem
+
+(Where "VERSION" is the current version of Polymer). If you do not have
+Git installed, the latest versions can be [downloaded instead][download].
+
+GETTING STARTED
+---------------
+
+In order for Polymer to create sprites from your source images, it must
+first create a "project" -- this is a `.polymer` file which is placed
+into your project's root directory. This file comes with some sensible
+defaults which should suffice for most cases. This file is generated by
+running `polymer init`.
+
+1. Run `polymer init` to create a ".polymer" file in the current
+   directory. Prior to running the command, you may want to glance at
+   the [polymer-init(1)][polymer-init] manpage to get an overview of the
+   supported options. `polymer init` also places some example source
+   images into your project.
+
+2. Run `polymer bond`: this is the main task which converts the source
+   images into the final sprites. If you have PNGOUT, OptiPNG, or
+   PNGCrush installed, Polymer will also optimise the generates sprites
+   to reduce them to the smallest possible filesize.
+
+3. Run `polymer bond` again. Nothing happens! Polymer maintains a cache
+   of your sprite images so that it only generates them again if any of
+   the sources have changed; pretty handy since optimising large sprites
+   can take some time. See [polymer(5)][polymer-5] to learn how to
+   disable this.
+
+USING YOUR SPRITES
+------------------
+
+### Updating Sprites
+
+Having created some example sprites in "Getting Started", you can now
+add completely new sprites by adding new directories alongside "one" and
+"two", alter existing sprites by adding, changing, or removing source
+images, then once again running `polymer bond`.
+
+If this isn't sufficiently flexible, see [polymer(5)][polymer-5] to
+learn how to define your own sprites in the ".polymer" file.
+
+### Sass / SCSS Stylesheets
+
+Out-of-the-box, Polymer generates a Sass stylesheet containing a mixin.
+This stylesheet is created at the path given to "config.sass" in
+".polymer".
+
+This mixin can be used thusly: (in this case, "main" is the name of the
+sprite, "home" and "products" are the names of source images
+sans-extension).
+
+    Assuming directory structure:
+
+    public/images/sprites/
+      messages/
+        new.png
+        reply.png
+
+    Your Sass stylesheet like:
+
+      @import polymer.sass
+
+      .buttons
+        a#compose, a#reply
+          +polymer("messages/new")
+        a#reply
+          +polymer-pos("messages/reply")
+
+Which creates:
+
+    .buttons a#compose, .buttons a#reply {
+      background: url(/path/to/sprite.ext) 0 0 no-repeat; }
+
+    .buttons a#products {
+      background-position: 0 -40px; }
+
+With the latest versions of the Haml library, you may use SCSS instead:
+
+      @import("polymer.sass")
+
+      .buttons {
+        a#compose, a#reply {
+          @include polymer("messages/new") }
+        a#reply {
+          @include polymer-pos("messages/reply") } }
+
+You can disable creation of the Sass mixin file by setting `config.sass
+false` in the ".polymer" file.
+
+### CSS Stylesheets
+
+... are not yet implemented. Hold tight; these should be around before
+Polymer hits v1.0.
+
+PNG OPTIMISATION
+----------------
+
+... needs to be written up.
+
+CONTRIBUTING
+------------
+
+A Bundler Gemfile is provided to simplify installing Polymer's
+dependencies. Running `bundle install` will install everything needed to
+contribute. Bundler is not used in the Polymer library itself.
+
+* 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 Epidity, God of Potatoes, who has
+  been known to shower rancid cucumbers upon those who fail to test.
+
+* Commit, but please do not mess with the Rakefile or history. If you
+  want to have your own version, _that is fine_, but bump the 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 (although
+  "everything is made up, and the points don't matter...").
+
+Polymer specs are run against:
+
+* Ruby (MRI) 1.8.7 p302,
+* Ruby (YARV) 1.9.1 p378,
+* Ruby (YARV) 1.9.2 p0.
+
+GETTING HELP
+------------
+
+Polymer comes complete with some manpages which document the various
+commands:
+
+* **[polymer(1)][polymer-1]** -- `polymer help`
+* **[polymer(5)][polymer-5]** -- `polymer help .polymer`
+* **[polymer-init(1)][polymer-init]** -- `polymer help init`
+* **[polymer-bond(1)][polymer-bond]** -- `polymer help bond`
+* **[polymer-optimise(1)][polymer-optimise]** -- `polymer help optimise`
+* **[polymer-position(1)][polymer-position]** -- `polymer help position`
+
+If you've encountered a bug, or Polymer isn't behaving as you expect,
+please [file an issue report][issues].
+
+DETAILS
+-------
+
+**Source**
+:  [http://github.com/antw/polymer][polymer]
+
+**Author**
+:  Anthony Williams
+
+**Copyright**
+:  2009-2010
+
+**License**
+:  BSD License
+
+Polymer © 2009-2010 by [Anthony Williams](mailto:hi@antw.me).
+Polymer is free software, released under the BSD license. Please see the
+LICENSE file for more information.
+
+The sample sources in lib/polymer/templates/sources are courtesy of
+[Yusuke Kamiyamane][yusuke], whose extraordinary generosity in releasing
+three-thousand royalty-free icons cannot be stated enough.
+
+[montage]:   http://github.com/antw/montage
+[polymer]:   http://github.com/antw/polymer
+[homebrew]:  http://mxcl.github.com/homebrew/
+[pngout]:    http://advsys.net/ken/utils.htm
+[download]:  http://github.com/antw/polymer/downloads
+[kin]:       http://github.com/antw/kin
+[semver]:    http://semver.org/
+[yard]:      http://yardoc.org/
+[issues]:    http://github.com/antw/polymer/issues
+[yusuke]:    http://p.yusukekamiyamane.com
+
+[polymer-1]:        http://antw.github.com/polymer/polymer.1.html
+[polymer-5]:        http://antw.github.com/polymer/polymer.5.html
+[polymer-init]:     http://antw.github.com/polymer/polymer-init.1.html
+[polymer-bond]:     http://antw.github.com/polymer/polymer-bond.1.html
+[polymer-optimise]: http://antw.github.com/polymer/polymer-optimise.1.html
+[polymer-position]: http://antw.github.com/polymer/polymer-position.1.html

data/Rakefile

@@ -0,0 +1,186 @@
+require 'rake'
+require 'rake/clean'
+
+$LOAD_PATH.unshift File.expand_path('../lib', __FILE__)
+require 'polymer/version'
+
+CLOBBER.include %w( pkg *.gem documentation coverage
+                    measurements lib/polymer/man )
+
+# === Helpers ================================================================
+
+require 'date'
+
+def replace_header(head, header_name, value)
+  head.sub!(/(\.#{header_name}\s*= ').*'/) { "#{$1}#{value}'" }
+end
+
+# === Tasks ==================================================================
+
+# --- Build ------------------------------------------------------------------
+
+desc 'Build the gem, and push to Github'
+task :release => :build do
+  unless system('git branch') =~ /^\* master$/
+    puts "You must be on the master branch to release!"
+    exit!
+  end
+
+  sh "git commit --allow-empty -a -m 'Release #{Polymer::VERSION}'"
+  sh "git tag v#{Polymer::VERSION}"
+  sh "git push origin master"
+  sh "git push origin v#{Polymer::VERSION}"
+
+  puts "Push to Rubygems.org with"
+  puts "  gem push pkg/polymer-#{Polymer::VERSION}.gem"
+end
+
+desc 'Builds the gem'
+task :build => [:man, :gemspec] do
+  sh "mkdir -p pkg"
+  sh "gem build polymer.gemspec"
+  sh "mv polymer-#{Polymer::VERSION}.gem pkg"
+end
+
+desc 'Create a fresh gemspec'
+task :gemspec => :validate do
+  gemspec_file = File.expand_path('../polymer.gemspec', __FILE__)
+
+  # Read spec file and split out the manifest section.
+  spec = File.read(gemspec_file)
+  head, manifest, tail = spec.split("  # = MANIFEST =\n")
+
+  # Replace name version and date.
+  replace_header head, :name,              'polymer'
+  replace_header head, :rubyforge_project, 'polymer'
+  replace_header head, :version,            Polymer::VERSION
+  replace_header head, :date,               Date.today.to_s
+
+  # Determine file list from git ls-files.
+  files = `git ls-files`.
+    split("\n").
+    sort.
+    reject { |file| file =~ /^\./ }.
+    reject { |file| file =~ /^(rdoc|pkg|spec|tasks|features|man)/ }
+
+  # Add man pages.
+  files += Dir['lib/polymer/man/*']
+
+  # Format list for the gemspec.
+  files = files.map { |file| "    #{file}" }.join("\n")
+
+  # Piece file back together and write.
+  manifest = "  s.files = %w[\n#{files}\n  ]\n"
+  spec = [head, manifest, tail].join("  # = MANIFEST =\n")
+  File.open(gemspec_file, 'w') { |io| io.write(spec) }
+
+  puts "Updated #{gemspec_file}"
+end
+
+task :validate do
+  unless Dir['lib/*'] - %w(lib/polymer.rb lib/polymer)
+    puts 'The lib/ directory should only contain a polymer.rb file, and a ' \
+         'polymer/ directory'
+    exit!
+  end
+
+  unless Dir['VERSION*'].empty?
+    puts 'A VERSION file at root level violates Gem best practices'
+    exit!
+  end
+end
+
+# --- Tests ------------------------------------------------------------------
+
+require 'rspec/core/rake_task'
+require 'cucumber/rake/task'
+
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+end
+
+Cucumber::Rake::Task.new(:features) do |features|
+  features.cucumber_opts = '--format progress --tag ~@pending'
+end
+
+desc 'Run RSpec examples followed by the Cucumber features'
+task :test    => [:spec, :features]
+task :default => :test
+
+# --- Man Pages --------------------------------------------------------------
+
+desc 'Builds the Polymer manual pages'
+task :man do
+  require 'pathname'
+
+  source_dir = Pathname.new('man')
+  dest_dir   = Pathname.new('lib/polymer/man')
+
+  dest_dir.rmtree if dest_dir.directory?
+  dest_dir.mkpath
+
+  Pathname.glob(source_dir + '*.ronn').each do |source|
+    destination = dest_dir + source.basename('.ronn')
+
+    # Create the man page.
+    sh "ronn --roff --manual='Polymer Manual' " \
+       "--organization='POLYMER #{Polymer::VERSION.upcase}' " \
+       "--pipe #{source} > #{destination}"
+
+    # Set man pages to be left-aligned (not justified).
+    sh "sed -i '' -e '3i\\\n.ad l\n' #{destination}"
+
+    # Create a text-only version of the man page.
+    sh "groff -Wall -mtty-char -mandoc -Tascii " \
+       "#{destination} | col -b > #{destination}.txt"
+  end
+end
+
+desc 'Builds HTML for Github Pages, then publishes'
+task :pages do
+  # Cheers to rtomayko/ronn/Rakefile
+  sh "ronn -5 --manual='Polymer Manual' " \
+     "--organization='POLYMER #{Polymer::VERSION.upcase}' " \
+     "-s toc -w man/*.ronn"
+
+  puts '-' * 50
+  puts 'Rebuilding pages ...'
+
+  verbose(false) do
+    rm_rf 'pages'
+    push_url = `git remote show origin`.lines.grep(/Push.*URL/).first[/git@.*/]
+    sh 'git fetch -q origin'
+    sh 'rev=$(git rev-parse origin/gh-pages)'
+    sh 'git clone -q -b gh-pages . pages'
+    cd 'pages'
+    sh 'git reset --hard $rev'
+    sh 'rm -f polymer*.html index.html'
+    sh 'cp -rp ../man/polymer*.html ../man/index.html ./'
+    sh 'git add *.html'
+    sh 'git commit -m "Rebuild manual."'
+    sh "git push #{push_url} gh-pages"
+  end
+end
+
+# --- YARD -------------------------------------------------------------------
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new do |doc|
+    doc.options << '--no-highlight'
+  end
+rescue LoadError
+  desc 'yard task requires that the yard gem is installed'
+  task :yard do
+    abort 'YARD is not available. In order to run yard, you must: gem ' \
+          'install yard'
+  end
+end
+
+# --- Console ----------------------------------------------------------------
+
+desc 'Open an irb session preloaded with Polymer'
+task :console do
+  sh 'irb -I ./lib -rubygems -r ./lib/polymer.rb'
+end
+

data/bin/polymer

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+
+unless $:.include? File.expand_path('../../lib', __FILE__)
+  $:.unshift File.expand_path('../../lib', __FILE__)
+end
+
+require 'polymer'
+require 'polymer/cli'
+
+Polymer::CLI.start

data/lib/polymer/cache.rb

@@ -0,0 +1,106 @@
+module Polymer
+  # Represents a cache file. Keeps track of the contents of each sprite and
+  # provides an easy means of determining if the sprite has been changed since
+  # the cache was last generated.
+  class Cache
+
+    # Returns the path to the cache file.
+    #
+    # @return [Pathname]
+    #
+    attr_reader :path
+
+    # Creates a new Cache.
+    #
+    # If the given +path+ does not exist, an empty cache instance will be
+    # created, and calling +write+ will create a new file at +path+.
+    #
+    # @param [Pathname] path
+    #   Path to the cache file to be loaded. If no +path+ is given, the cache
+    #   will operate in-memory only and +write+ is disabled.
+    #
+    def initialize(path = nil)
+      @path = path
+
+      if @path and @path.file?
+        @cache = YAML.load_file @path
+      else
+        @cache = { :cache_version => 2, :sprites => {} }
+      end
+    end
+
+    # Checks whether the given +sprite+ is different to the cached version.
+    #
+    # @param [Polymer::Sprite] sprite
+    #   The sprite whose "freshness" is to be checked.
+    #
+    # @return [Boolean]
+    #
+    def stale?(sprite)
+      not fresh?(sprite)
+    end
+
+    # Checks whether the given +sprite+ is identical to the cached version.
+    #
+    # @param [Polymer::Sprite] sprite
+    #   The sprite whose "freshness" is to be checked.
+    #
+    # @return [Boolean]
+    #
+    def fresh?(sprite)
+      sprite.save_path.file? and
+        @cache[:sprites].has_key?(sprite.name) and
+        @cache[:sprites][sprite.name] == sprite.digest
+    end
+
+    # Updates the cached value of +sprite+.
+    #
+    # @param [Polymer::Sprite] sprite
+    #   The sprite whose digest is to be stored in the cache.
+    #
+    def set(sprite)
+      @cache[:sprites][sprite.name] = sprite.digest
+    end
+
+    # Removes a +sprite+'s cached values.
+    #
+    # @param [Polymer::Sprite] sprite
+    #   The sprite whose digest is to be removed from the cache.
+    #
+    def remove(sprite)
+      @cache[:sprites].delete(sprite.name)
+    end
+
+    # Removes all sprite cache entries, except those in +retain+.
+    #
+    # @param [Array<Polymer::Cache>] retain
+    #   An array of cache entries which are _not_ to be removed.
+    #
+    def remove_all_except(retain)
+      names = retain.map { |sprite| sprite.name }
+
+      @cache[:sprites].delete_if do |key, _|
+        not names.include?(key)
+      end
+    end
+
+    # Writes the cache file to disk.
+    #
+    # @return [true]
+    #   Returnss true once the file has been written.
+    # @return [false]
+    #   Returns false if the Cache was initialized without a path (and, as
+    #   such, nothing can be saved).
+    #
+    def write
+      return false unless @path
+
+      @path.open('w') do |file|
+        file.puts YAML.dump(@cache)
+      end
+
+      true
+    end
+
+  end # Cache
+end # Polymer