polymer 1.0.0.beta.3

data/lib/polymer/dsl.rb

@@ -0,0 +1,283 @@
+module Polymer
+  # Provides the DSL used in .polymer files.
+  #
+  # In order to account for situations where global configuration may
+  # appear after some sprites are defined, the DSL instance keeps track
+  # of each defined sprite, but only resolves the settings for each
+  # one once +to_project+ is called.
+  #
+  class DSL
+
+    # Given a path to a file, reads and evaluates the contents as a DSL
+    # definition.
+    #
+    # @param [Pathname] path
+    #   Path to a .polymer file to be evaluated.
+    #
+    # @return [Polymer::Project]
+    #   The project represented by the config file.
+    #
+    def self.load(path)
+      dsl = new(path.dirname)
+      dsl.instance_eval path.read.split('__END__').first, path.to_s, 1
+      dsl.to_project
+    end
+
+    # Builds a project using the given block.
+    #
+    # The given DSL block will be run using +instance_eval+, thus no
+    # parameters are given to the block.
+    #
+    # @param [Pathname] root
+    #   When building a project using the DSL, rather than a .polymer file,
+    #   you need to provide a path to the directory you want to serve as the
+    #   Polymer root.
+    #
+    # @return [Polymer::Project]
+    #   The project represented by the DSL.
+    #
+    # @example
+    #
+    #   Polymer::DSL.build do
+    #     sprite 'sources/lurrr/*' => 'sprites/lurrr.png'
+    #   end
+    #
+    def self.build(root, &block)
+      file, line = caller.first.split(':')
+
+      dsl = new(root)
+      dsl.instance_eval &block
+      dsl.to_project
+    end
+
+    # Creates a new DSL instance.
+    #
+    # @param [Pathname] root_path
+    #   Path to the root of the Polymer project. The .polymer config should
+    #   reside in this directory.
+    #
+    def initialize(root_path)
+      @root    = root_path
+      @sprites = []
+      @config  = ProjectConfig.new
+    end
+
+    # Returns the configuration object. Used to set global options which
+    # should either affect the whole project (css, sass), or used as a default
+    # value for sprite settings (padding, url).
+    #
+    # @return [Polymer::DSL::Config]
+    #
+    attr_reader :config
+
+    # Defines a sprite.
+    #
+    # Expects a single Hash as the parameter, where the hash should include
+    # precisely one String key mapped to a String value, and any extra options
+    # to be used when creating the sprite passed with Symbol keys.
+    #
+    # The String key should be a path -- relative to the .polymer file -- to
+    # the source files to be used for the sprite, while the value is a path
+    # indicating where the sprite should be saved (including filename).
+    #
+    # See the DEFINING SPRITES section of polymer(5) for more information.
+    #
+    # @param [Hash] definition
+    #   A { String => String } pair, plus any additional options.
+    #
+    # @option definition [Integer] :padding (20)
+    #   Sets the size of the transparent space to be inserted between each
+    #   source image. Measured in pixels.
+    # @option definition [String] :url ("/images/:filename")
+    #   The URL at which the sprite can be requested by a browser. Used when
+    #   generating stylesheets.
+    #
+    # @example
+    #
+    #   # Creates a sprite where the sources are in "path/to/sources" with the
+    #   # generated sprite saved to "path/to/sprite.png", using 50px vertical
+    #   # padding between each source image.
+    #
+    #   sprite "path/to/sources" => "path/to_sprite", :padding => 50
+    #
+    def sprite(definition)
+      definition[:padding] = 0 if definition[:padding] == false
+
+      # Find the source => sprite mapping.
+      source, sprite = _extract_mapping(definition)
+
+      # If the source contains a :name segment, it may define multiple sprites
+      # depending on the directory structure.
+      if source.to_s =~ /:name/
+        if definition.has_key?(:name)
+          # Can't have a :name segment and an explicit name option.
+          raise Polymer::DslError,
+            "Sprite '#{source} => #{sprite}' has both a :name path segment " \
+            "and a :name option; please use only one."
+        elsif sprite !~ /:name/
+          raise Polymer::MissingName,
+            "Sprite '#{source} => #{sprite}' requires a :name segment in " \
+            "the sprite path."
+        else
+          _define_multiple_sprites(source, sprite, definition)
+        end
+      else
+        _define_sprite(source, sprite, definition)
+      end
+
+      nil
+    end
+
+    alias_method :sprites, :sprite
+
+    # Transforms the configuration -- and defined sprites -- into a Project.
+    #
+    # @return [Polymer::Project]
+    #
+    def to_project
+      project_config = @config.to_h
+
+      Project.new(@root, @sprites.map do |definition|
+        definition = _create_sprite(definition, project_config)
+      end, project_config)
+    end
+
+    #######
+    private
+    #######
+
+    # Given a sprite as defined in the config file, extracts the source path,
+    # the sprite path, _destructively removes them from the Hash_, and returns
+    # a two-element array with their values.
+    #
+    # @return [Array<String, String>] The source and sprite path.
+    #
+    def _extract_mapping(definition)
+      unless source = definition.detect { |key, value| key.is_a?(String) }
+        raise Polymer::MissingMap,
+          'Sprite definition is missing a { source => sprite } pair.'
+      end
+
+      source
+    end
+
+    # Defines a single sprite.
+    #
+    # @param [String] sources
+    #   The path at which Polymer should look for source images. If the path
+    #   is a directory, Polymer will assume that any images within it are to
+    #   be used as sources. Relative to +@root+.
+    # @param [String] sprite
+    #   The path, relative to +@root+ at which the generated sprite is to
+    #   be saved.
+    # @param [Hash] options
+    #   Other options.
+    #
+    # @raise [Polymer::DuplicateName]
+    #   Raised when the sprite uses a name which has been taken by an
+    #   existing sprite.
+    #
+    def _define_sprite(sources, sprite, options)
+      sources, sprite = @root + sources, @root + sprite
+      name = options[:name] || sprite.basename(sprite.extname).to_s
+
+      if @sprites.detect { |definition| definition[:name] == name }
+        raise DuplicateName,
+          "You tried to create a sprite whose name is `#{name}', but a " \
+          "sprite with this name has already been defined."
+      end
+
+      # Handle when a directory is given without a file-matcher.
+      sources = sources + '*' if sources.directory?
+
+      @sprites << options.merge(
+        :name      => name,
+        :sources   => Pathname.glob(sources),
+        :save_path => @root + sprite
+      )
+    end
+
+    # Defines multiple sprites with a :name segment.
+    #
+    # @param [String] sources
+    #   The path at which we can find sources.
+    # @param [String] sprite
+    #   The path at which the sprite is to be saved.
+    # @param [Hash] options
+    #   Other options.
+    #
+    def _define_multiple_sprites(sources, sprite, options)
+      leading, trailing = sources.split(':name')
+
+      Pathname.glob(@root + leading + '*').each do |entry|
+        next unless entry.directory?
+
+        sprite_opts = options.dup # Create a copy for each sprite.
+        sprite_opts[:name] = entry.basename.to_s # Use directory as the name
+
+        source_path = "#{leading}#{sprite_opts[:name]}#{trailing}"
+        sprite_path = sprite.gsub(/:name/, sprite_opts[:name])
+
+        _define_sprite(source_path, sprite_path, sprite_opts)
+      end
+    end
+
+    # Given a sprite definition, creates a final Sprite instance.
+    #
+    # @param [Hash] definition
+    #   The sprite as defined; with options parsed by _define_sprites.
+    # @param [Hash] project_config
+    #   The global project configuration.
+    #
+    # @return [Polymer::Sprite]
+    #
+    def _create_sprite(definition, project_config)
+      url = definition.fetch(:url, project_config[:url]).dup
+      url.gsub!(/:name/, definition[:name])
+      url.gsub!(/:filename/, definition[:save_path].basename.to_s)
+
+      Polymer::Sprite.new \
+        definition[:name],
+        definition[:sources],
+        definition[:save_path],
+        definition.fetch(:padding, project_config[:padding]),
+        url
+    end
+
+    # Provides the DSL for the global configuration options.
+    #
+    # @private
+    #
+    class ProjectConfig
+      ATTRIBUTES = %w( cache css padding url sass ).map(&:to_sym).freeze
+
+      # Define the setter methods for each attribute. The setters are
+      # sans-equals to provide a slightly more concise syntax.
+      #
+      ATTRIBUTES.each do |method|
+        class_eval <<-RUBY
+          def #{method}(value)           # def padding(value)
+            @config[:#{method}] = value  #   @config[:padding] = value
+          end                            # end
+        RUBY
+      end
+
+      # Creates a new ProjectConfig. Sets the default values which are used in
+      # the event that the user doesn't specify them.
+      #
+      def initialize
+        @config = ATTRIBUTES.inject({}) do |memo, attribute|
+          memo[attribute] = Polymer::Project::DEFAULTS[attribute]
+          memo
+        end
+      end
+
+      # Returns a hash containing each of the attribute values.
+      #
+      def to_h
+        @config
+      end
+    end # ProjectConfig
+
+  end # DSL
+end # Polymer

data/lib/polymer/man/polymer-bond.1

@@ -0,0 +1,60 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.ad l
+.
+.TH "POLYMER\-BOND" "1" "September 2010" "POLYMER 1.0.0.BETA.3" "Polymer Manual"
+.
+.SH "NAME"
+\fBpolymer\-bond\fR \- Create sprite images defined in your \.polymer file
+.
+.SH "SYNOPSIS"
+\fBpolymer bond\fR [\-\-force] [\-\-fast] [\-\-config=POLYMER_CONFIG]
+.
+.SH "DESCRIPTION"
+Generate the sprites defined in your polymer(5) file\. After each sprite is generated, the sprites are optimised using whichever available PNG optimisers you have installed (PNGOUT, OptiPNG, and PNGCrush) in order to reduce the filesize as much as possible\.
+.
+.P
+Sass and CSS is then generated according to the settings defined in your polymer(5) configuration\.
+.
+.P
+Polymer keeps track of the contents of each sprite with a \fB\.polymer\-cache\fR file so that subsequent runs of \fBpolymer bond\fR will only re\-generate (and re\-optimise) those sprites whose sources have changed\. See the \fIPOLYMER CACHE\fR section \-\- below \-\- for more information\.
+.
+.SH "OPTIONS"
+.
+.TP
+\fB\-\-force\fR
+Something something something dark side: re\-generate sprites even if the sources have not changed since last time\.
+.
+.TP
+\fB\-\-fast\fR
+Skips optimisation of generated sprites\. Useful when you want to quickly preview changes without waiting for the optimisers to run\.
+.
+.TP
+\fB\-\-config=<path>\fR
+In order to perform some tasks \-\- such as generating sprites \-\- Polymer needs to locate your \fB\.polymer\fR project file\. The default behaviour is to look for one in the current working directory, and to keep ascending the directory structure until it finds one\.
+.
+.IP
+To disable this behaviour, you may supply a path to the config file by using the \fB\-\-config\fR option\.
+.
+.SH "POLYMER CACHE"
+Since optimising sprites can be a lengthy process (very large sprites may take minutes), Polymer keeps track of the contents of each sprite with a \fB\.polymer\-cache\fR file\.
+.
+.P
+Polymer will re\-generate an existing sprite in the following cases:
+.
+.IP "1." 4
+the contents of a source file is changed; or,
+.
+.IP "2." 4
+a new source file is added, or an existing one deleted; or,
+.
+.IP "3." 4
+the generated sprite file is missing; or,
+.
+.IP "4." 4
+you pass the \fB\-\-force\fR option\.
+.
+.IP "" 0
+.
+.SH "SEE ALSO"
+polymer(5)

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

@@ -0,0 +1,66 @@
+POLYMER-BOND(1) 		Polymer Manual		       POLYMER-BOND(1)
+
+
+
+NAME
+       polymer-bond - Create sprite images defined in your .polymer file
+
+SYNOPSIS
+       polymer bond [--force] [--fast] [--config=POLYMER_CONFIG]
+
+DESCRIPTION
+       Generate the sprites defined in your polymer(5) file. After each sprite
+       is generated, the sprites are optimised using whichever available PNG
+       optimisers you have installed (PNGOUT, OptiPNG, and PNGCrush) in order
+       to reduce the filesize as much as possible.
+
+       Sass and CSS is then generated according to the settings defined in
+       your polymer(5) configuration.
+
+       Polymer keeps track of the contents of each sprite with a .poly-
+       mer-cache file so that subsequent runs of polymer bond will only
+       re-generate (and re-optimise) those sprites whose sources have changed.
+       See the POLYMER CACHE section -- below -- for more information.
+
+OPTIONS
+       --force
+	      Something something something dark side: re-generate sprites
+	      even if the sources have not changed since last time.
+
+       --fast Skips optimisation of generated sprites. Useful when you want to
+	      quickly preview changes without waiting for the optimisers to
+	      run.
+
+       --config=<path>
+	      In order to perform some tasks -- such as generating sprites --
+	      Polymer needs to locate your .polymer project file. The default
+	      behaviour is to look for one in the current working directory,
+	      and to keep ascending the directory structure until it finds
+	      one.
+
+	      To disable this behaviour, you may supply a path to the config
+	      file by using the --config option.
+
+POLYMER CACHE
+       Since optimising sprites can be a lengthy process (very large sprites
+       may take minutes), Polymer keeps track of the contents of each sprite
+       with a .polymer-cache file.
+
+       Polymer will re-generate an existing sprite in the following cases:
+
+       1.  the contents of a source file is changed; or,
+
+       2.  a new source file is added, or an existing one deleted; or,
+
+       3.  the generated sprite file is missing; or,
+
+       4.  you pass the --force option.
+
+
+
+SEE ALSO
+       polymer(5)
+
+
+
+POLYMER 1.0.0.BETA.3		September 2010		       POLYMER-BOND(1)

data/lib/polymer/man/polymer-init.1

@@ -0,0 +1,33 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.ad l
+.
+.TH "POLYMER\-INIT" "1" "September 2010" "POLYMER 1.0.0.BETA.3" "Polymer Manual"
+.
+.SH "NAME"
+\fBpolymer\-init\fR \- Create a new Polymer project in the current directory
+.
+.SH "SYNOPSIS"
+\fBpolymer init\fR [\-\-sprites=SPRITES] [\-\-sources=SOURCES] [\-\-no\-examples] [\-\-windows]
+.
+.SH "DESCRIPTION"
+Create a \fB\.polymer\fR file in the current directory with some sensible default settings\. By default, the \fBinit\fR command also copies some sample sources to provide a working example of how to create your own sprites\.
+.
+.SH "OPTIONS"
+.
+.TP
+\fB\-\-sprites=<path>\fR
+Path to a directory, relative to the current directory, in which sprites should be saved by default\. This can be customised later by in your polymer(5) file\. Default: public/images
+.
+.TP
+\fB\-\-sources=<path>\fR
+Path to a directory, relative to the current directory, in which Polymer should find the sources for your sprites\. This can be customised later in your polymer(5) file\. Default public/images/sprites
+.
+.TP
+\fB\-\-no\-examples\fR
+The \fBinit\fR command copies some sample sources into your \fBsources\fR directory to provide an example of how Polymer works\. The \fB\-\-no\-examples\fR option disabled this\.
+.
+.TP
+\fB\-\-windows\fR
+To provide better support for systems where files beginning with a "\." are troublesome, the \fB\-\-windows\fR option tells Polymer to create a \fBpolymer\.rb\fR file instead of \fB\.polymer\fR\.
+

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

@@ -0,0 +1,42 @@
+POLYMER-INIT(1) 		Polymer Manual		       POLYMER-INIT(1)
+
+
+
+NAME
+       polymer-init - Create a new Polymer project in the current directory
+
+SYNOPSIS
+       polymer init [--sprites=SPRITES] [--sources=SOURCES] [--no-examples]
+       [--windows]
+
+DESCRIPTION
+       Create a .polymer file in the current directory with some sensible
+       default settings. By default, the init command also copies some sample
+       sources to provide a working example of how to create your own sprites.
+
+OPTIONS
+       --sprites=<path>
+	      Path to a directory, relative to the current directory, in which
+	      sprites should be saved by default. This can be customised later
+	      by in your polymer(5) file. Default: public/images
+
+       --sources=<path>
+	      Path to a directory, relative to the current directory, in which
+	      Polymer should find the sources for your sprites. This can be
+	      customised later in your polymer(5) file. Default pub-
+	      lic/images/sprites
+
+       --no-examples
+	      The init command copies some sample sources into your sources
+	      directory to provide an example of how Polymer works. The
+	      --no-examples option disabled this.
+
+       --windows
+	      To provide better support for systems where files beginning with
+	      a "." are troublesome, the --windows option tells Polymer to
+	      create a polymer.rb file instead of .polymer.
+
+
+
+
+POLYMER 1.0.0.BETA.3		September 2010		       POLYMER-INIT(1)

data/lib/polymer/man/polymer-optimise.1

@@ -0,0 +1,23 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.ad l
+.
+.TH "POLYMER\-OPTIMISE" "1" "September 2010" "POLYMER 1.0.0.BETA.3" "Polymer Manual"
+.
+.SH "NAME"
+\fBpolymer\-optimise\fR \- Optimise PNG images
+.
+.SH "SYNOPSIS"
+\fBpolymer optimise\fR PATH [PATH [PATH \.\.\.]]
+.
+.SH "DESCRIPTION"
+Optimises the PNG images at \fIPATH\fR\. Does not require you to be in a Polymer project directory\.
+.
+.P
+The \fBoptimise\fR command permits you to use the optimisers supported by Polymer on any PNG image\. This is useful for optimising non\-sprite image, or sprites which were generated with the \fB\-\-fast\fR option\.
+.
+.P
+All \fIPATH\fRs are relative to the current working directory\.
+.
+.P
+This command may also be run as \fBpolymer optimize\fR\.

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

@@ -0,0 +1,25 @@
+POLYMER-OPTIMISE(1)		Polymer Manual		   POLYMER-OPTIMISE(1)
+
+
+
+NAME
+       polymer-optimise - Optimise PNG images
+
+SYNOPSIS
+       polymer optimise PATH [PATH [PATH ...]]
+
+DESCRIPTION
+       Optimises the PNG images at PATH. Does not require you to be in a Poly-
+       mer project directory.
+
+       The optimise command permits you to use the optimisers supported by
+       Polymer on any PNG image. This is useful for optimising non-sprite
+       image, or sprites which were generated with the --fast option.
+
+       All PATHs are relative to the current working directory.
+
+       This command may also be run as polymer optimize.
+
+
+
+POLYMER 1.0.0.BETA.3		September 2010		   POLYMER-OPTIMISE(1)

data/lib/polymer/man/polymer-position.1

@@ -0,0 +1,39 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.ad l
+.
+.TH "POLYMER\-POSITION" "1" "September 2010" "POLYMER 1.0.0.BETA.3" "Polymer Manual"
+.
+.SH "NAME"
+\fBpolymer\-position\fR \- Information about your sprite sources
+.
+.SH "SYNOPSIS"
+\fBpolymer position\fR SOURCE
+.
+.SH "DESCRIPTION"
+Shows the position of a \fISOURCE\fR image with a sprite\. This is useful should you wish to manually create your own CSS files, without having to calculate the position of each source yourself\. Also provides you with the basic CSS needed to show the source image\.
+.
+.P
+The \fISOURCE\fR may be the name of a source image in any of your sprites, or a \fISPRITE\fR/\fISOURCE\fR pair\.
+.
+.P
+For example, assuming the following sources\.\.\.
+.
+.IP "" 4
+.
+.nf
+
+sources/
+  one/
+    book\.png
+    television\.png
+  two/
+    magnet\.png
+    television\.png
+.
+.fi
+.
+.IP "" 0
+.
+.P
+\&\.\.\. \fBpolymer position book\fR will show the position of the book source in the "one" sprite\. \fBpolymer position television\fR will output the position of the television source in both the "one" and "two" sprites\. Finally, \fBpolymer position two/television\fR shows the position of the television source in only the "two" sprite\.

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

@@ -0,0 +1,42 @@
+POLYMER-POSITION(1)		Polymer Manual		   POLYMER-POSITION(1)
+
+
+
+NAME
+       polymer-position - Information about your sprite sources
+
+SYNOPSIS
+       polymer position SOURCE
+
+DESCRIPTION
+       Shows the position of a SOURCE image with a sprite. This is useful
+       should you wish to manually create your own CSS files, without having
+       to calculate the position of each source yourself. Also provides you
+       with the basic CSS needed to show the source image.
+
+       The SOURCE may be the name of a source image in any of your sprites, or
+       a SPRITE/SOURCE pair.
+
+       For example, assuming the following sources...
+
+
+
+	   sources/
+	     one/
+	       book.png
+	       television.png
+	     two/
+	       magnet.png
+	       television.png
+
+
+
+       ... polymer position book will show the position of the book source in
+       the "one" sprite. polymer position television will output the position
+       of the television source in both the "one" and "two" sprites. Finally,
+       polymer position two/television shows the position of the television
+       source in only the "two" sprite.
+
+
+
+POLYMER 1.0.0.BETA.3		September 2010		   POLYMER-POSITION(1)

data/lib/polymer/man/polymer.1

@@ -0,0 +1,50 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.ad l
+.
+.TH "POLYMER" "1" "September 2010" "POLYMER 1.0.0.BETA.3" "Polymer Manual"
+.
+.SH "NAME"
+\fBpolymer\fR \- Image spriting for web applications
+.
+.SH "SYNOPSIS"
+\fBpolymer\fR [\-\-no\-colour] COMMAND [ARGUMENTS]
+.
+.SH "DESCRIPTION"
+\fBPolymer\fR 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\.
+.
+.P
+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\.
+.
+.P
+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\.
+.
+.SH "OPTIONS"
+.
+.TP
+\fB\-\-no\-colour\fR
+Disables the use of colour in output\. This option is also available as \fB\-\-no\-color\fR\.
+.
+.SH "COMMANDS"
+.
+.TP
+polymer init(1) \fIpolymer\-init\.1\.html\fR
+Creates a new Polymer project in the current directory\.
+.
+.TP
+polymer bond(1) \fIpolymer\-bond\.1\.html\fR
+Creates the sprites specified by your \fB\.polymer\fR or \fBpolymer\.rb\fR file, optimises the images, and creates any requested CSS or Sass files\.
+.
+.TP
+polymer optimise(1) \fIpolymer\-optimise\.1\.html\fR
+Given paths to PNG files as arguments, optimises them to reduce the filesize as much as possible without compromising quality\. Also available as \fBpolymer optimize\fR\.
+.
+.TP
+polymer position(1) \fIpolymer\-position\.1\.html\fR
+Shows the position of a source within a sprite, and provides CSS which you can use in your own stylesheets\.
+.
+.P
+Detailed documentation for each of Polymer\'s commands can be viewed with the \fBpolymer help\fR command\. For example, to view the documentation for the \fBbond\fR command, run \fBpolymer help bond\fR\.
+.
+.SH "SEE ALSO"
+polymer(5) (\fBpolymer help \.polymer\fR) provides a description of the \fB\.polymer\fR configuration file format\.