polymer 1.0.0.beta.3

data/lib/polymer/man/polymer.1.txt

@@ -0,0 +1,60 @@
+POLYMER(1)			Polymer Manual			    POLYMER(1)
+
+
+
+NAME
+       polymer - Image spriting for web applications
+
+SYNOPSIS
+       polymer [--no-colour] COMMAND [ARGUMENTS]
+
+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.
+
+OPTIONS
+       --no-colour
+	      Disables the use of colour in output. This option is also avail-
+	      able as --no-color.
+
+COMMANDS
+       polymer init(1) polymer-init.1.html
+	      Creates a new Polymer project in the current directory.
+
+       polymer bond(1) polymer-bond.1.html
+	      Creates the sprites specified by your .polymer or polymer.rb
+	      file, optimises the images, and creates any requested CSS or
+	      Sass files.
+
+       polymer optimise(1) polymer-optimise.1.html
+	      Given paths to PNG files as arguments, optimises them to reduce
+	      the filesize as much as possible without compromising quality.
+	      Also available as polymer optimize.
+
+       polymer position(1) polymer-position.1.html
+	      Shows the position of a source within a sprite, and provides CSS
+	      which you can use in your own stylesheets.
+
+       Detailed documentation for each of Polymer's commands can be viewed
+       with the polymer help command. For example, to view the documentation
+       for the bond command, run polymer help bond.
+
+SEE ALSO
+       polymer(5) (polymer help .polymer) provides a description of the .poly-
+       mer configuration file format.
+
+
+
+POLYMER 1.0.0.BETA.3		September 2010			    POLYMER(1)

data/lib/polymer/man/polymer.5

@@ -0,0 +1,130 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.ad l
+.
+.TH "\.POLYMER" "5" "September 2010" "POLYMER 1.0.0.BETA.3" "Polymer Manual"
+.
+.SH "NAME"
+\fB\.polymer\fR \- a format for describing image sprites and their sources
+.
+.SH "DESCRIPTION"
+A \fB\.polymer\fR file describes the image sprites used in a Polymer project, and the source images which are used to create those sprites\.
+.
+.P
+Placing a \fB\.polymer\fR file in the root directory of your project will allow the Polymer application to automate generation and optimisation of your sprite images\. In a Ruby project the \fB\.polymer\fR file should be in the same directory as your \fBRakefile\fR\.
+.
+.P
+On systems where files beginning with a "\." are tricky to work with (e\.g\. Windows), you may instead use \fBpolymer\.rb\fR instead of \fB\.polymer\fR\.
+.
+.P
+A \fB\.polymer\fR can be generated by running \fBpolymer init\fR\.
+.
+.SH "SYNTAX"
+The \fB\.polymer\fR file is, at it\'s heart, a Ruby file and thus any valid Ruby code may be used in it\. This may seem intimidating to those who have never used Ruby, but the \fB\.polymer\fR syntax is very simple, and fairly self\-explanatory (the irony of saying that, then writing a man page, is not lost on me\.\.\.)\.
+.
+.SH "GLOBAL SETTINGS"
+Global options are prefixed with "config\." and followed by the value you wish to set\. These settings are OPTIONAL, and Polymer will use it\'s own defaults if you choose not to define them\.
+.
+.TP
+\fBconfig\.sass\fR "\fIstring\fR" or \fIfalse\fR
+The path, relative to the \fB\.polymer\fR file, at which you want the Sass mixin file to be written\. You may also set this to \fIfalse\fR in order to disable generation of Sass files\. Default: "public/stylesheets/sass"
+.
+.TP
+\fBconfig\.css\fR "\fIstring\fR" or \fIfalse\fR
+The path, relative to the \fB\.polymer\fR file, at which you want the CSS file to be written\. You may also set this to \fIfalse\fR in order to disable generation of CSS files\. Default: false
+.
+.TP
+\fBconfig\.url\fR "\fIstring\fR"
+In order for stylesheets to link to the generated sprites, they must be able to create a URL for each sprite\. Typically this URL should be relative to the web root and prefixed with a "/", otherwise browsers will interpret the URL as being relative to the stylesheet\. The \fBurl\fR option accepts a ":filename" segment which Polymer will change to each sprite\'s filename (including the extension)\. Default: "/images/:filename"
+.
+.TP
+\fBconfig\.padding\fR \fInumber\fR
+Polymer stacks each source image on top of one another, with transparent padding being used to ensure that one source does not bleed into another when used as the background for an HTML element\. The \fBpadding\fR option sets the number of pixels to be used to separate each source, and may be set to 0 if no padding is desired\. Default: 20\.
+.
+.TP
+\fBconfig\.cache\fR "\fIstring\fR" or \fIfalse\fR
+Since optimising sprites can take some time, Polymer maintains a cache of each sprite, only generating and optimising those which have changed\. This cache is typically stored in your project root as "\.polymer\-cache"\. You may specify an alternate path here, or provide \fIfalse\fR if you want to disable the cache entirely (not recommended)\.
+.
+.SH "DEFINING SPRITES"
+Sprites are defined using the \fIsprite\fR keyword (which is also aliased as \fIsprites\fR)\. The simplest way of defining a sprite is:
+.
+.IP "" 4
+.
+.nf
+
+sprite "path/to/sources/*" => "path/to/sprite\.png"
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Both of the paths in the above example are relative to the \fB\.polymer\fR file\. In this case, we are telling Polymer to take source files from the "path/to/sources" directory, and composite them together in a sprite to be saved at "path/to/sprite\.png"\.
+.
+.P
+If your source directory contains non\-images, you may need to be more specific:
+.
+.IP "" 4
+.
+.nf
+
+sprite "path/to/sources/*\.{png,gif,jpg}" => "path/to/sprite\.png"
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Sprite definitions may contain a \fB:name\fR segment which Polymer will use to match any sub\-directory:
+.
+.IP "" 4
+.
+.nf
+
+sprites "sources/:name/*" => "sprites/:name\.png"
+.
+.fi
+.
+.IP "" 0
+.
+.P
+In this case, Polymer will look inside the "sources/" directory for sub\-directories\. The contents of sub\-directory will be used to create individual sprites where the final sprite name is the same as the directory name\. For example, given the following directory structure\.\.\.
+.
+.IP "" 4
+.
+.nf
+
+sources/
+  one/
+    book\.png
+    calculator\.png
+  two/
+    magnet\.png
+    television\.png
+.
+.fi
+.
+.IP "" 0
+.
+.P
+\&\.\.\. Polymer will create two sprites in the "sprites/" directory: one\.png will contain "book" and "calculator", while two\.png will contain "magnet" and "television"\.
+.
+.P
+There may be cases where you need to customise an individual sprite and you don\'t want to change the global setting; \fBsprite\fR allows you to specify any of the global settings with the exception of "sass" and "css" like so:
+.
+.IP "" 4
+.
+.nf
+
+sprite "path/to/sources/*" => "path/to/sprite\.png",
+  :padding => 50, :url => "/elsewhere/:filename"
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Each configuration option is prefixed with a colon rather than "config\.", is separated from the value with " => ", and all but the final option should be followed with a comma\.
+.
+.SH "SEE ALSO"
+polymer(1), polymer\-init(1)

data/lib/polymer/man/polymer.5.txt

@@ -0,0 +1,145 @@
+.POLYMER(5)			Polymer Manual			   .POLYMER(5)
+
+
+
+NAME
+       .polymer - a format for describing image sprites and their sources
+
+DESCRIPTION
+       A .polymer file describes the image sprites used in a Polymer project,
+       and the source images which are used to create those sprites.
+
+       Placing a .polymer file in the root directory of your project will
+       allow the Polymer application to automate generation and optimisation
+       of your sprite images. In a Ruby project the .polymer file should be in
+       the same directory as your Rakefile.
+
+       On systems where files beginning with a "." are tricky to work with
+       (e.g. Windows), you may instead use polymer.rb instead of .polymer.
+
+       A .polymer can be generated by running polymer init.
+
+SYNTAX
+       The .polymer file is, at it's heart, a Ruby file and thus any valid
+       Ruby code may be used in it. This may seem intimidating to those who
+       have never used Ruby, but the .polymer syntax is very simple, and
+       fairly self-explanatory (the irony of saying that, then writing a man
+       page, is not lost on me...).
+
+GLOBAL SETTINGS
+       Global options are prefixed with "config." and followed by the value
+       you wish to set. These settings are OPTIONAL, and Polymer will use it's
+       own defaults if you choose not to define them.
+
+       config.sass "string" or false
+	      The path, relative to the .polymer file, at which you want the
+	      Sass mixin file to be written. You may also set this to false in
+	      order to disable generation of Sass files. Default: "pub-
+	      lic/stylesheets/sass"
+
+       config.css "string" or false
+	      The path, relative to the .polymer file, at which you want the
+	      CSS file to be written. You may also set this to false in order
+	      to disable generation of CSS files. Default: false
+
+       config.url "string"
+	      In order for stylesheets to link to the generated sprites, they
+	      must be able to create a URL for each sprite. Typically this URL
+	      should be relative to the web root and prefixed with a "/", oth-
+	      erwise browsers will interpret the URL as being relative to the
+	      stylesheet. The url option accepts a ":filename" segment which
+	      Polymer will change to each sprite's filename (including the
+	      extension). Default: "/images/:filename"
+
+       config.padding number
+	      Polymer stacks each source image on top of one another, with
+	      transparent padding being used to ensure that one source does
+	      not bleed into another when used as the background for an HTML
+	      element. The padding option sets the number of pixels to be used
+	      to separate each source, and may be set to 0 if no padding is
+	      desired. Default: 20.
+
+       config.cache "string" or false
+	      Since optimising sprites can take some time, Polymer maintains a
+	      cache of each sprite, only generating and optimising those which
+	      have changed. This cache is typically stored in your project
+	      root as ".polymer-cache". You may specify an alternate path
+	      here, or provide false if you want to disable the cache entirely
+	      (not recommended).
+
+DEFINING SPRITES
+       Sprites are defined using the sprite keyword (which is also aliased as
+       sprites). The simplest way of defining a sprite is:
+
+
+
+	   sprite "path/to/sources/*" => "path/to/sprite.png"
+
+
+
+       Both of the paths in the above example are relative to the .polymer
+       file. In this case, we are telling Polymer to take source files from
+       the "path/to/sources" directory, and composite them together in a
+       sprite to be saved at "path/to/sprite.png".
+
+       If your source directory contains non-images, you may need to be more
+       specific:
+
+
+
+	   sprite "path/to/sources/*.{png,gif,jpg}" => "path/to/sprite.png"
+
+
+
+       Sprite definitions may contain a :name segment which Polymer will use
+       to match any sub-directory:
+
+
+
+	   sprites "sources/:name/*" => "sprites/:name.png"
+
+
+
+       In this case, Polymer will look inside the "sources/" directory for
+       sub-directories. The contents of sub-directory will be used to create
+       individual sprites where the final sprite name is the same as the
+       directory name. For example, given the following directory structure...
+
+
+
+	   sources/
+	     one/
+	       book.png
+	       calculator.png
+	     two/
+	       magnet.png
+	       television.png
+
+
+
+       ... Polymer will create two sprites in the "sprites/" directory:
+       one.png will contain "book" and "calculator", while two.png will con-
+       tain "magnet" and "television".
+
+       There may be cases where you need to customise an individual sprite and
+       you don't want to change the global setting; sprite allows you to spec-
+       ify any of the global settings with the exception of "sass" and "css"
+       like so:
+
+
+
+	   sprite "path/to/sources/*" => "path/to/sprite.png",
+	     :padding => 50, :url => "/elsewhere/:filename"
+
+
+
+       Each configuration option is prefixed with a colon rather than "con-
+       fig.", is separated from the value with " => ", and all but the final
+       option should be followed with a comma.
+
+SEE ALSO
+       polymer(1), polymer-init(1)
+
+
+
+POLYMER 1.0.0.BETA.3		September 2010			   .POLYMER(5)

data/lib/polymer/optimisation.rb

@@ -0,0 +1,130 @@
+module Polymer
+  # Contains support for PNGOUT, OptiPNG, and PNGCrush.
+  module Optimisation
+
+    # Returns an array of optimisers supported on the current system.
+    #
+    # @return [Array<Polymer::Optimisation::Optimiser>]
+    #
+    def self.optimisers
+      @optimisers ||=
+        [PNGOut, OptiPNG, PNGCrush].select { |o| o.supported? }.map(&:new)
+    end
+
+    # Given a path to a file, runs all of the available optimisers until
+    # either:
+    #
+    #   1. No further optimisations could be found.
+    #   2. Each optimiser has been run three times.
+    #
+    # @param [Pathname] path
+    #   Path to the file to be optimised.
+    #
+    # @return [Integer, false]
+    #   Returns the number of bytes by which the filesize was reduced.
+    # @return [false]
+    #   Returns false if the current machine has no optimisers available.
+    #
+    def self.optimise_file(path)
+      return false if optimisers.empty?
+
+      reduction = 0
+      skip = []
+
+      3.times do |i|
+        before_iteration = reduction
+
+        optimisers.each do |optimiser|
+          next if skip.include?(optimiser)
+
+          if (opt_reduction = optimiser.run(path)) > 0
+            reduction += opt_reduction
+          else
+            # This optimiser can't find any more savings, don't run
+            # it again.
+            skip << optimiser
+          end
+        end # optimisers.each
+
+        # If the iteration found no savings, return immediately rather than
+        # running them again.
+        return reduction if before_iteration >= reduction
+      end # 3.times
+
+      reduction
+    end
+
+    # A base optimiser class.
+    class Optimiser
+      COMMAND = ''
+
+      # Runs the optimiser on a file once. Running again may yield further
+      # reductions in file size.
+      #
+      # @param [Pathname] path
+      #   Path to the file to be optimised.
+      #
+      # @return [Integer]
+      #   Returns the number of bytes by which the filesize was reduced.
+      #
+      # @see [Polymer::Optimisation.optimise_file]
+      #
+      def run(path)
+        before_size = path.size
+        `#{self.class::COMMAND.gsub(/\[PATH\]/, path.to_s)}`
+        before_size - path.size
+      end
+
+      # Tests if the optimiser is supported on the current system.
+      #
+      # @return [Boolean]
+      #
+      def self.supported?
+        unless defined?(@supported)
+          stdout = `which #{self::COMMAND.split(' ', 2).first}`
+          @supported = $?.exitstatus.zero? && stdout !~ /not found/
+        end
+
+        @supported
+      end
+    end # Optimiser
+
+    # An optimiser which uses PNGOUT. pngout may also be called
+    # "pngout-darwin" if installed using MacPorts.
+    class PNGOutDefault < Optimiser
+      COMMAND = 'pngout [PATH] [PATH] -s0 -k0 -y'
+    end
+
+    # MacPorts installs a pngout-darwin binary.
+    class PNGOutDarwin < PNGOutDefault
+      COMMAND = 'pngout-darwin [PATH] [PATH] -s0 -k0 -y'
+    end
+
+    # An optimiser which uses OptiPNG.
+    class OptiPNG < Optimiser
+      COMMAND = 'optipng [PATH]'
+    end # OptiPNG
+
+    # An optimiser which uses PNGCrush.
+    class PNGCrush < Optimiser
+      COMMAND = 'pngcrush -brute -e .png.tmp [PATH]'
+
+      # PNGCrush doesn't overwrite existing files. Instead the -e (extension)
+      # option is used to write to a temporary file, which is them moved over
+      # the new file.
+      def run(path)
+        super
+        FileUtils.rm(path)
+        FileUtils.mv(path.to_s + '.tmp', path)
+      end
+    end # PNGCrush
+
+    # Which PNGOUT should we use?
+    if not PNGOutDefault.supported? and PNGOutDarwin.supported?
+      PNGOut = PNGOutDarwin
+    else
+      PNGOut = PNGOutDefault
+    end
+
+  end # Optimisation
+end # Polymer

data/lib/polymer/project.rb

@@ -0,0 +1,164 @@
+module Polymer
+  # Represents a directory in which it is expected that there be a
+  # configuration file, and source images.
+  #
+  # The Project class exists mostly to make CLI tasks simpler; if you're using
+  # Polymer within your own library, you may prefer to create Sprite instances
+  # without using a Project.
+  #
+  class Project
+
+    # Defaults used by DSL when the user doesn't provide explicit values.
+    DEFAULTS = {
+      :sass    => 'public/stylesheets/sass',
+      :url     => "/images/:name.png",
+      :cache   => '.polymer-cache',
+      :css     => false,
+      :padding => 20
+    }
+
+    # Returns the path to the project root directory.
+    #
+    # @return [Pathname]
+    #
+    attr_reader :root
+
+    # @return [Pathname, false]
+    #   The path to the Sass mixin file.
+    # @return [false]
+    #   False if Sass has been disabled.
+    #
+    attr_reader :sass
+
+    # @return [Pathname, false]
+    #   The path to the CSS file.
+    # @return [false]
+    #   False if CSS generation has been disabled.
+    #
+    attr_reader :css
+
+    # An array containing all of the sprites in the project.
+    #
+    # @return [Array<Polymer::Sprite>]
+    #
+    attr_reader :sprites
+
+    # Creates a new Project.
+    #
+    # Note that +new+ does not validation of the given paths or options; it
+    # expects them to be correct. You're probably better using +DSL.build+.
+    #
+    # @param [Pathname] root_path
+    #   Path to the root of the Polymer project. The .polymer config should
+    #   reside in this directory.
+    # @param [Array<Polymer::Sprite>] sprites
+    #   An array of sprites which belong to the project.
+    # @param [Hash] options
+    #   Extra options for customising the behaviour of the Project.
+    #
+    # @option options [String, false] :css (false)
+    #   Sets the path -- relative to +root_path+ -- at which the CSS
+    #   file should be saved. Setting +:css+ to false will disable
+    #   generation of CSS stylesheets.
+    # @option options [String, false] :sass (false)
+    #   Sets the path -- relative to +root_path+ -- at which the Sass
+    #   mixin file should be saved. Setting +:sass+ to false will
+    #   disable generation of the mixin file.
+    #
+    def initialize(root_path, sprites, options = {})
+      @root      = root_path
+      @sprites   = sprites
+
+      @sass      = extract_path :sass,  options
+      @css       = extract_path :css,   options
+      @cachefile = extract_path :cache, options
+    end
+
+    # Returns the sprite whose name is +name+.
+    #
+    # @param [String] name
+    #   The name of the sprite to be retrieved.
+    #
+    # @return [Polymer::Sprite] The sprite.
+    # @return [nil]           If no such sprite exists.
+    #
+    def sprite(name)
+      sprites.detect { |sprite| sprite.name == name }
+    end
+
+    # Returns if the cache should be used.
+    #
+    # @return [true]  If the cache should be used by CLI.
+    # @return [false] If the cache is disabled and should not be used.
+    #
+    def use_cache?
+      !! @cachefile
+    end
+
+    # Returns a Cache instance for this project.
+    #
+    # @return [Polymer::Cache]
+    #
+    def cache
+      @cache ||= Polymer::Cache.new(@cachefile)
+    end
+
+    private # ================================================================
+
+    # Extracts a path, typically specified in the DSL, and converts it to
+    # an absolute Pathname (by appending it on to +@root+).
+    #
+    # @param [Symbol] key
+    #   The option key in which the value is expected.
+    # @param [Hash] options
+    #   The options hash passed to #initialize.
+    #
+    # @return [Pathname]
+    #   Returns the path appended to +@root+.
+    # @return [false, nil]
+    #   When the option value was not a string.
+    #
+    def extract_path(key, options)
+      value = options.fetch(key, DEFAULTS[key])
+      value.is_a?(String) ? @root + value : value
+    end
+
+    # === Class Methods ======================================================
+
+    # Given a path to a directory, +find_config+ attempts to locate a
+    # suitable configuration file by looking for a ".polymer" or "polymer.rb"
+    # file. If no such file is found in the given directory, it ascends the
+    # directory structure until one is found, or it runs out of parent
+    # directories to check.
+    #
+    # If given a path to a file, +find_config+ assumes that this file is the
+    # config, and simply returns it as a Pathname.
+    #
+    # @param [Pathname, String] path
+    #   The path to the directory or configuration file.
+    #
+    # @return [Pathname]
+    #   The path to the found configuration.
+    #
+    # @raise [Polymer::MissingProject]
+    #   Raised when +find_config+ could not find a suitable configuration
+    #   file.
+    #
+    def self.find_config(path)
+      path, config_path = Pathname.new(path).expand_path, nil
+      return path if path.file?
+
+      path.ascend do |directory|
+        if (dot_polymer = directory + '.polymer').file?
+          return dot_polymer
+        elsif (polymer_rb = directory + 'polymer.rb').file?
+          return polymer_rb
+        end
+      end
+
+      raise MissingProject,
+        "Polymer couldn't find a configuration file at `#{path.to_s}'"
+    end
+
+  end # Project
+end # Polymer

data/lib/polymer/sass_generator.rb

@@ -0,0 +1,38 @@
+module Polymer
+  class SassGenerator
+
+    TEMPLATE = Pathname.new(__FILE__).dirname + 'templates/sass_mixins.erb'
+
+    # Given a project, generates a Sass mixin stylesheet which can can be
+    # included into your own Sass stylesheets.
+    #
+    # @param [Polymer::Project] project
+    #   The project instance for which to generate a Sass stylesheet.
+    #
+    # @return [true]
+    #   Returned when the stylesheet was generated and saved to the location
+    #   specified by +project.sass+.
+    # @return [false]
+    #   Returned when +project.sass+ evaluates to false, disabling generation
+    #   of the Sass mixin file.
+    #
+    def self.generate(project)
+      return false unless project.sass
+
+      if project.sass.to_s[-5..-1] == '.sass'
+        project.sass.dirname.mkpath
+        save_to = project.sass
+      else
+        project.sass.mkpath
+        save_to = project.sass + '_polymer.sass'
+      end
+
+      File.open(save_to, 'w') do |file|
+        file.puts ERB.new(File.read(TEMPLATE), nil, '<>').result(binding)
+      end
+
+      true
+    end # self.generate
+
+  end # SassGenerator
+end # Polymer