rapper 0.1.1 → 0.2.0

data/README.markdown

@@ -51,6 +51,7 @@ The `definition_root` setting in the rapper config is a path to a folder contain
 
     --- !omap
     - root: public/javascripts
+    - destination_root: public/assets # optional, default: root + "/assets"
     - tag_root: /javascripts
     - suffix: js
     - assets: !omap
@@ -64,10 +65,14 @@ The `definition_root` setting in the rapper config is a path to a folder contain
               - ext_js_full
             - version: db62
 
-The above definition will create two asset files: `public/javascripts/assets/base.js` and `public/javascripts/assets/stats.js` from the component files in `public/javascripts` (in this case: `public/javascripts/protovis.js` and `public/javascripts/ext_js_full.js`).
+The above definition will create two asset files: `public/assets/base.js` and `public/assets/stats.js` from the component files in `public/javascripts` (in this case: `public/javascripts/protovis.js` and `public/javascripts/ext_js_full.js`).
 
 **Note:** Definition files are YAML ordered mapping documents. This is so that version updates (which involves rapper updating the version numbers and writing out the updated definition as YAML) don't change the order of the file. This is especially useful when using git and merging branches because it prevents nasty merge conflicts.
 
+## View helpers
+
+Rapper provides helper methods to generate HTML include tags for your assets in the `Rapper::ViewHelpers`. Simply `include` it in the appropriate place for your web app / framework / widget / whatever. It's automaticallly included for Merb.
+
 ## Versioning
 
 Version strings are short hashes of the before-compression asset file. This means that they will only change when the contents of the component files for an asset change and time-consuming compression will only happen when a bundle needs to be re-packaged.

data/VERSION

@@ -1 +1 @@
-0.1.1
+0.2.0

data/lib/rapper.rb

@@ -9,7 +9,6 @@ require File.dirname( __FILE__ ) + "/tasks.rb"
 # No holds barred, no time for move fakin' /
 # Gots to get the loot so I can bring home the bacon
 module Rapper
-  
   # The main Rapper class. Handles, well, everything.
   class Engine
     
@@ -27,8 +26,8 @@ module Rapper
     # 
     # @param [String] config_path Path to the configuration YAML file.
     # 
-    # @param [String,Symbol] environment The current environment. This must
-    #   map to an environment configured in the Rapper configuration file.
+    # @param [String,Symbol] environment The current environment. This must map
+    # to an environment configured in the Rapper configuration file.
     def initialize( config_path, environment )
       @environment = environment
       @config = {}
@@ -49,7 +48,6 @@ module Rapper
       types.each do |type|
         definition = @definitions[type]
         source = File.expand_path( definition.root )
-        destination = definition.destination_root
         suffix = definition.suffix
         
         definition.assets.each do |name, spec|
@@ -58,7 +56,7 @@ module Rapper
           source_files = definition.component_paths( name )
           destination_file = definition.asset_path( name )
           
-          log :verbose, "Joining #{source_files.size} files to #{name}"
+          log :verbose, "Joining #{source_files.size} files to #{destination_file}"
           join_files( source_files, destination_file )
           
           if get_config( "compress" )

data/lib/rapper/definition.rb

@@ -21,7 +21,8 @@ module Rapper
     end
     
     def destination_root
-      @definition["root"].gsub( /\/$/, '' ) + "/assets"
+      @default_destination_root ||= @definition["root"].gsub( /\/$/, '' ) + "/assets"
+      @definition["destination_root"] || @default_destination_root
     end
     
     # @return [String] The public url root for the asset component files (used
@@ -44,6 +45,8 @@ module Rapper
     # = Assets =
     # ==========
     
+    # @return [YAML::Omap] Ordered mapping of definition keys to definition
+    # configuration (as a `YAML::Omap`).
     def assets
       @definition["assets"]
     end
@@ -54,11 +57,11 @@ module Rapper
     # 
     # @param [String] version New version string for the asset.
     def set_version( name, version )
-      @definition["assets"][name.to_s]["version"] = version
+      assets[name.to_s]["version"] = version
     end 
     
     def get_version( name )
-      @definition["assets"][name.to_s]["version"]
+      assets[name.to_s]["version"]
     end
     
     # ==========

data/lib/rapper/helpers.rb

@@ -1,8 +1,5 @@
 module Rapper
-  # Set up view helpers for various web frameworks. Currently supported:
-  #   * Merb
-  # To do:
-  #   * Sinatra
+  # Helpers for setting up view helpers.
   module HelperSetup
     
     # Loads view helpers for any/all available web frameworks available.
@@ -22,8 +19,8 @@ module Rapper
     private
   end
   
+  # View helpers.
   module ViewHelpers
-    
     RAPPER = nil
     
     def self.included( klass )
@@ -41,5 +38,4 @@ module Rapper
       end
     end
   end
-  
 end

data/lib/rapper/html_tags.rb

@@ -1,8 +1,13 @@
 require 'erb'
 
 module Rapper
+  # HTML tag generators.
   module HtmlTags
     
+    # @param [Symbol] type Definition type.
+    # 
+    # @return [Symbol] Tag type for the given definition type. One of `:css_tag`
+    # or `:js_tag`
     def tag_method_for_type( type )
       if @definitions[type].suffix =~ /css/
         :css_tag
@@ -11,10 +16,26 @@ module Rapper
       end
     end
     
+    # Build a JS tag for an asset.
+    #
+    # @param [Symbol] type Definition type.
+    # 
+    # @param [Symbol] name Name of the asset to build a `<script>` tag for.
+    # 
+    # @return [String] A `<script>` tag for the given asset in the configured
+    # HTML style.
     def js_tag( type, name )
       self.get_tag( JsTag, type, name )
     end
     
+    # Build a CSS tag for an asset.
+    # 
+    # @param [Symbol] name Name of the asset to build a `<link>` tag for.
+    # 
+    # @param [Symbol] name Name of the asset to build a `<link>` tag for.
+    # 
+    # @return [String] A `<link>` tag for the given asset in the configured
+    # HTML style.
     def css_tag( type, name )
       self.get_tag( CssTag, type, name )
     end
@@ -40,12 +61,27 @@ module Rapper
       end
     end
     
+    # Represents an HTML tag.
     class Tag
       class << self
+        
+        # @return [Hash] A mapping of HTML styles to their appropriate HTML
+        # tag template strings.
         def templates
-          {}
+          { :html => '', :html5 => '', :xhtml => '' }
         end
         
+        # Build an HTML tag for a given resource in a given HTML style.
+        # 
+        # @param [String] path Publically accessible path to the asset file.
+        # 
+        # @param [String,nil] version Version string to append as a query
+        # string.
+        # 
+        # @param [Symbol] style HTML tag style. One of `:html`, `:html5`, or
+        # `:xhtml`.
+        # 
+        # @return [String] The appropriate HTML tag to include the resource.
         def for( path, version, style )
           @cache ||= {}
           @cache[style] ||= {}
@@ -63,6 +99,7 @@ module Rapper
       end
     end
     
+    # JavaScript tag.
     class JsTag < Tag
       class << self
         def templates
@@ -75,6 +112,7 @@ module Rapper
       end
     end
     
+    # CSS tag.
     class CssTag < Tag
       class << self
         def templates

data/lib/rapper/logging.rb

@@ -14,7 +14,7 @@ module Rapper
     #     period in it).
     # 
     # @param [Symbol] level Log level. :info or :verbose. :verbose level log
-    #   messages are only emitted if the "verbose_logging" setting is truthy.
+    # messages are only emitted if the "verbose_logging" setting is truthy.
     # 
     # @param [String] message Message to be logged.
     def log( level, message )

data/lib/rapper/utils.rb

@@ -11,7 +11,7 @@ module Rapper
     # Concatenate one or more files. Uses <code>cat</code>.
     # 
     # @param [Array<String>,String] source_files A  path or array of paths to
-    #   files to concatenate.
+    # files to concatenate.
     # 
     # @param [String] destination_file Destination for concatenated output.
     def join_files( source_files, destination_file )

data/lib/tasks.rb

@@ -3,6 +3,14 @@ module Rapper
   # Rake tasks for building / refreshing packages
   class Tasks
     
+    # Set up rapper asset packaging Rake tasks.
+    # 
+    # @param [Symbol] namespace The Rake namespace to put the generated
+    # tasks under.
+    # 
+    # @yield [config] Configuration hash. `:path` should be the path to the
+    # configuration YAML file. `:env` is the optional environment. Defaults to
+    # `:production`.
     def initialize( namespace = :rapper, &block )
       @namespace = namespace
       @config = {}
@@ -14,6 +22,8 @@ module Rapper
     
     private
     
+    # Creates all rapper rake tasks: package all assets, package assets for
+    # each type.
     def define
       namespace @namespace do
         desc "Package all assets that need re-packaging"
@@ -24,7 +34,7 @@ module Rapper
         namespace :package do
           @rapper.definitions.each do |type, definition|
             desc "Package all #{type} assets that need re-packaging"
-            task key do
+            task type do
               @rapper.package( type )
             end
           end

data/rapper.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{rapper}
-  s.version = "0.1.1"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Tyson Tate"]
-  s.date = %q{2011-03-23}
+  s.date = %q{2011-04-02}
   s.description = %q{Static asset packager and compressor with versioning and built-in view helpers. Compresses files only when they need compressing.}
   s.email = %q{tyson@tysontate.com}
   s.extra_rdoc_files = [
@@ -40,6 +40,7 @@ Gem::Specification.new do |s|
     "rapper.gemspec",
     "spec/fixtures/config/asset_definitions/base/javascripts.yml",
     "spec/fixtures/config/asset_definitions/base/stylesheets.yml",
+    "spec/fixtures/config/asset_definitions/custom_destination/javascripts.yml",
     "spec/fixtures/config/assets.yml",
     "spec/fixtures/javascripts/simple_1.js",
     "spec/fixtures/javascripts/simple_2.js",

data/spec/fixtures/config/asset_definitions/custom_destination/javascripts.yml

@@ -0,0 +1,11 @@
+--- !omap 
+- root: spec/fixtures/javascripts
+- destination_root: tmp/custom_destination
+- tag_root: /javascripts
+- suffix: js
+- assets: !omap 
+    - multiple_files: !omap 
+        - files: 
+          - simple_1
+          - simple_2
+        - version: f3d9

data/spec/fixtures/config/assets.yml

@@ -27,6 +27,11 @@ test_no_bundle:
   <<: *base
   version: false
   bundle: false
+test_custom_destination:
+  <<: *base
+  definition_root: spec/fixtures/config/asset_definitions/custom_destination
+  bundle: true
+  compress: false
 xhtml_tags:
   <<: *base
   version: false

data/spec/rapper_spec.rb

@@ -127,6 +127,14 @@ describe Rapper do
     end
   end
   
+  describe "custom definition destination" do
+    it "works" do
+      rapper = Rapper::Engine.new( "spec/fixtures/config/assets.yml", "test_custom_destination" )
+      rapper.package
+      Dir[ "tmp/custom_destination/*" ].should == ["tmp/custom_destination/multiple_files.js"]
+    end
+  end
+  
   describe "packaging test cases" do
     Dir["spec/fixtures/test_cases/*"].each do |folder|
       next unless File.directory?( folder )

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: rapper
 version: !ruby/object:Gem::Version 
-  hash: 25
+  hash: 23
   prerelease: 
   segments: 
   - 0
-  - 1
-  - 1
-  version: 0.1.1
+  - 2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Tyson Tate
@@ -15,13 +15,11 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-03-23 00:00:00 -07:00
+date: 2011-04-02 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   prerelease: false
-  name: closure-compiler
-  type: :runtime
   version_requirements: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -33,11 +31,11 @@ dependencies:
         - 0
         - 0
         version: 1.0.0
+  type: :runtime
   requirement: *id001
+  name: closure-compiler
 - !ruby/object:Gem::Dependency 
   prerelease: false
-  name: rspec
-  type: :development
   version_requirements: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -49,11 +47,11 @@ dependencies:
         - 3
         - 1
         version: 1.3.1
+  type: :development
   requirement: *id002
+  name: rspec
 - !ruby/object:Gem::Dependency 
   prerelease: false
-  name: yard
-  type: :development
   version_requirements: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -65,11 +63,11 @@ dependencies:
         - 6
         - 4
         version: 0.6.4
+  type: :development
   requirement: *id003
+  name: yard
 - !ruby/object:Gem::Dependency 
   prerelease: false
-  name: bluecloth
-  type: :development
   version_requirements: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -81,11 +79,11 @@ dependencies:
         - 0
         - 10
         version: 2.0.10
+  type: :development
   requirement: *id004
+  name: bluecloth
 - !ruby/object:Gem::Dependency 
   prerelease: false
-  name: bundler
-  type: :development
   version_requirements: &id005 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -97,11 +95,11 @@ dependencies:
         - 0
         - 0
         version: 1.0.0
+  type: :development
   requirement: *id005
+  name: bundler
 - !ruby/object:Gem::Dependency 
   prerelease: false
-  name: jeweler
-  type: :development
   version_requirements: &id006 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -113,11 +111,11 @@ dependencies:
         - 5
         - 2
         version: 1.5.2
+  type: :development
   requirement: *id006
+  name: jeweler
 - !ruby/object:Gem::Dependency 
   prerelease: false
-  name: rake
-  type: :development
   version_requirements: &id007 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -129,7 +127,9 @@ dependencies:
         - 8
         - 7
         version: 0.8.7
+  type: :development
   requirement: *id007
+  name: rake
 description: Static asset packager and compressor with versioning and built-in view helpers. Compresses files only when they need compressing.
 email: tyson@tysontate.com
 executables: []
@@ -163,6 +163,7 @@ files:
 - rapper.gemspec
 - spec/fixtures/config/asset_definitions/base/javascripts.yml
 - spec/fixtures/config/asset_definitions/base/stylesheets.yml
+- spec/fixtures/config/asset_definitions/custom_destination/javascripts.yml
 - spec/fixtures/config/assets.yml
 - spec/fixtures/javascripts/simple_1.js
 - spec/fixtures/javascripts/simple_2.js