rapper 0.0.1

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,11 @@
+source "http://rubygems.org"
+
+gem "closure-compiler", "~> 1.0.0"
+
+group :development do
+  gem "rspec", "~> 1.3.1"
+  gem "yard", "~> 0.6.4"
+  gem "bluecloth", "~> 2.0.10"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.5.2"
+end

data/Gemfile.lock

@@ -0,0 +1,24 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    bluecloth (2.0.10)
+    closure-compiler (1.0.0)
+    git (1.2.5)
+    jeweler (1.5.2)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    rake (0.8.7)
+    rspec (1.3.1)
+    yard (0.6.4)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bluecloth (~> 2.0.10)
+  bundler (~> 1.0.0)
+  closure-compiler (~> 1.0.0)
+  jeweler (~> 1.5.2)
+  rspec (~> 1.3.1)
+  yard (~> 0.6.4)

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Tyson Tate
+
+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/README.markdown

@@ -0,0 +1,140 @@
+# rapper
+
+Static asset packager and compressor with versioning and built-in view helpers. Easy to configure, easy to use, and easy to ignore when you want to. No crazy JavaScript comment DSLs, either.
+
+Merb and Sinatra view helpers are coming soon, as well as pluggable compression backends (YUI Compressor, Google Closure Compiler, etc.) `rapper` currently only includes Google Closure Compiler.
+
+## Packaging assets without wanting to claw your eyes out
+
+1. Create a config file and one or more asset type definition files.
+2. Load `rapper` with the config path and current environment:
+
+        engine = Rapper::Engine.new( "config/assets.yml", "development" )
+
+3. Then package the assets:
+
+        engine.package
+
+4. That's it. Stop fussing with ridiculous asset packagers that want you to spend an hour shuffling files around for them.
+
+## Rapper configuration
+
+Rapper is configured using a YAML file that defines the settings to be used in various server environments. Example:
+
+    base: &base
+      definition_root: config/assets
+      tag_style: html   # optional, ["html", "xhtml", "html5"], default: html5
+    
+    development:
+      <<: *base
+      bundle: false     # optional, default: true
+      compress: false   # optional, default: true
+      versions: false   # optional, default: true
+      log: stdout       # optional, ["stdout", file path], default: off
+      log_verbose: true # optional, default: off
+    
+    production:
+      <<: *base
+      bundle: true
+      compress: true
+      versions: true
+      # optional, passed to Google Closure Compiler
+      closure_compiler:
+        # default: SIMPLE_OPTIMIZATIONS
+        compilation_level: ADVANCED_OPTIMIZATIONS
+
+The only required setting is `definition_root`. (Of course, you'll still need definition files to define the asset packages that you want build. More on that below.)
+
+The minimum settings needed for a configuration file is:
+
+    base:
+      definition_root: config/assets
+
+The following defaults are applied if not defined in your configuration:
+
+    bundle: true
+    compress: true
+    tag_style: html5
+    versions: true
+    closure_compiler:
+      compilation_level: SIMPLE_OPTIMIZATIONS
+
+## Rapper definitions
+
+The `definition_root` setting in the rapper config is a path to a folder containing more YAML files that define the various types of bundles you want to build (eg. `stylesheets.yml`, `javascripts.yml`) Example definition file:
+
+    --- !omap 
+    - source_root: public/javascripts
+    - destination_root: public/assets/javascripts
+    - suffix: js
+    - assets: 
+      - base: 
+        - files: 
+          - mootools
+      - stats: 
+        - files: 
+          - protovis
+          - ext_js_full
+
+The above definition will create two asset files: `public/assets/javascripts/base.js` and `public/assets/javascripts/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 working with many branches because it prevents nasty merge conflicts.
+
+## Versioning
+
+If versioning is turned on in your config, version strings will be used to enforce better browser caching of assets.
+
+    --- !omap 
+    - source_root: public/javascripts
+    - destination_root: public/assets/javascripts
+    - suffix: js
+    - assets: 
+      - base: 
+        - files: 
+          - mootools
+        - version: 7b06
+      - stats: 
+        - files: 
+          - protovis
+          - ext_js_full
+        - version: db62
+
+These version strings are hashes of the final asset file. This means that they will only change when the contents of the asset file change. Version strings are used to enforce good browser caching habits, especially when you have a far-future expires header configured on your web server. For example, suppose you had the following asset:
+
+    <script type="text/javascript" src="/assets/milkshake.js?v=d3va"></script>
+
+When the contents of the asset change, the version will change in the query string:
+
+    <script type="text/javascript" src="/assets/milkshake.js?v=ae51"></script>
+
+Browsers will automatically re-download and cache the new asset.
+
+## To do soon
+
+* Merb view helpers
+* Sinatra helpers
+
+## To do later
+
+* Per-asset configuration overrides
+* Rails helpers
+* Watch for CoffeeScript changes and automatically compile
+* Watch for Sass changes and automatically compile
+
+## Version history
+
+* **0.0.1** - Initial release. Functioning bundler, minus the view helpers.
+
+## Contributing to rapper
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+## Copyright
+
+Copyright (c) 2011 Tyson Tate. See LICENSE.txt for further details.

data/Rakefile

@@ -0,0 +1,45 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  gem.name = "rapper"
+  gem.homepage = "http://tysontate.github.com/rapper/"
+  gem.license = "MIT"
+  gem.summary = %Q{Static asset packager and compressor with versioning and built-in view helpers.}
+  gem.description = %Q{Static asset packager and compressor with versioning and built-in view helpers. Easy to configure, easy to use, and easy to ignore when you want to. No crazy JavaScript comment DSLs, either.}
+  gem.email = "tyson@tysontate.com"
+  gem.authors = ["Tyson Tate"]
+  
+  # Runtime dependencies
+  gem.add_runtime_dependency "closure-compiler", "~> 1.0.0"
+  
+  # Development dependencies
+  gem.add_development_dependency "rspec", "~> 1.3.1"
+  gem.add_development_dependency "yard", "~> 0.6.4"
+  gem.add_development_dependency "bluecloth", "~> 2.0.10"
+  gem.add_development_dependency "bundler", "~> 1.0.0"
+  gem.add_development_dependency "jeweler", "~> 1.5.2"
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'spec'
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new do |config|
+  config.options = ["--private", "--protected"]
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/lib/rapper.rb

@@ -0,0 +1,66 @@
+require 'yaml'
+
+Dir[File.expand_path( File.dirname( __FILE__ ) + "/rapper/*.rb" )].each do |file|
+  require file
+end
+
+# No batteries included, and no strings attached /
+# 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
+    
+    include Rapper::Config
+    include Rapper::Logging
+    include Rapper::Utils
+    include Rapper::Compressors
+    include Rapper::Versioning
+    
+    # Load the configuration YAML file and set the current environment.
+    # 
+    # @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.
+    def initialize( config_path, environment )
+      @environment = environment
+      @config = {}
+      @definitions = {}
+      load_config( config_path )
+      log :verbose, "Loaded rappper with #{environment} environment from #{config_path}"
+    end
+    
+    # Package assets according to the loaded config and definitions. Defaults
+    # to packaging all asset types.
+    # 
+    # @param [<String>] types Asset types to refresh versions for.
+    def package( *types )
+      types = types.empty? ? asset_types : types
+      log :info, "Packaging #{types.join( ', ' )}"
+      
+      types.each do |type|
+        definition = @definitions[type]
+        source = File.expand_path( definition["source_root"] )
+        destination = definition["destination_root"]
+        suffix = definition["suffix"]
+        
+        definition["assets"].each do |asset|
+          name = asset.keys.first
+          spec = asset.values.first.first
+          
+          source_files = asset_component_paths( type, name )
+          destination_file = asset_path( type, name )
+          
+          log :verbose, "Joining #{definition["assets"].count} files to #{name}"
+          join_files( source_files, destination_file )
+        end
+      end
+      
+      refresh_versions( *types )
+      update_definitions( *types )
+    end
+    
+  end
+end

data/lib/rapper/compressors.rb

@@ -0,0 +1,47 @@
+require File.expand_path( File.dirname( __FILE__ ) + "/../yui/css_compressor.rb" )
+require "closure-compiler"
+
+module Rapper
+  # Compression methods for various types of assets.
+  module Compressors
+    
+    # Use Richard Hulse's port of the YUI CSS Compressor to compress the
+    # contents of a source file to a destination file.
+    # 
+    # @param [String] source Path to source CSS file.
+    # 
+    # @param [String] destination Path to destination CSS file.
+    #   written to.
+    def compress_css( source, destination )
+      log :verbose, "Compressing #{source}"
+      
+      source = readable_file( source )
+      destination = writable_file( source )
+      
+      destination.write( YUI::CSS.compress( source.read ) )
+      destination.write "\n"
+      
+      source.close && destination.close
+    end
+    
+    # Use Google's Closure Compiler to compress the JavaScript from a source
+    # file to a destination file.
+    # 
+    # @param [String] source Path to source JavaScript file.
+    # 
+    # @param [String] destination Path to destination JavaScript file.
+    def compress_js( source, destination, opts={} )
+      log :verbose, "Compressing #{source}"
+      
+      source = readable_file( source )
+      destination = writable_file( source )
+      closure = Closure::Compiler.new( opts )
+      
+      destination.write( closure.compile( destination ) )
+      destination.write "\n"
+      
+      source.close && destination.close
+    end
+    
+  end
+end

data/lib/rapper/config.rb

@@ -0,0 +1,95 @@
+require 'yaml'
+
+module Rapper
+  # Rapper configuration and definition methods.
+  module Config
+    
+    attr_accessor :environment, :config, :definitions
+    
+    protected
+    
+    # Load the Rapper configuration from a YAML file and all asset definition
+    # YAML files in the folder specified in the current environment's
+    # <code>definition_root</code> setting. The definition type is inferred
+    # from the file name. E.g. The type key for <code>javascript.yml</code>
+    # will be "javascript".
+    # 
+    # @param [String] config_path The path to the configuration YAML file.
+    def load_config( config_path )
+      @config = YAML.load_file( config_path )
+      if env_config.nil?
+        raise Rapper::Errors::InvalidEnvironment,
+          "The '#{@environment}' environment is not defined in #{config_path}"
+      elsif env_config["definition_root"].nil?
+        raise Rapper::Errors::NoDefinitionRoot,
+          "No 'definition_root' has been defined for #{@environment}"
+      end
+      definition_path = File.join( env_config["definition_root"], "*.yml" )
+      Dir[definition_path].each do |definition|
+        type = File.basename( definition, ".yml" )
+        @definitions[type] = YAML.load_file( definition )
+      end
+    end
+    
+    protected
+    
+    # Get the config setting for the given key.
+    # 
+    # @param [String] key Configuration key.
+    # 
+    # @return [String,Hash] If the current environment's config defines this
+    #   setting, return that value. If not, return the default setting. If the
+    #   default setting is a hash, return the default merged with the
+    #   environment's setting.
+    def get_config( key )
+      if default_config[key].is_a?( Hash )
+        default_config[key].merge( env_config[key] || {} )
+      else
+        env_config[key] || default_config[key]
+      end
+    end
+    
+    # Update the asset definition files. (Typically done after regenerating
+    # versions.)
+    # 
+    # @param [<String>] types Asset types to update the definition files for.
+    #   Defaults to all types.
+    def update_definitions( *types )
+      types = types.empty? ? asset_types : types
+      log :info, "Updating definitions for #{types.join( ', ' )}"
+      
+      types.each do |type|
+        log "Updating definition file for", type
+        File.open( definition_path( type ), "w" ) do |file|
+          file.puts @definitions[type].to_yaml
+        end
+      end
+    end
+    
+    private
+    
+    # @return [Hash] Default rapper configuration.
+    def default_config
+      {
+        "bundle" => true,
+        "compress" => true,
+        "tag_style" => "html5",
+        "versions" => true,
+        "closure_compiler" => {
+          "compilation_level" => "SIMPLE_OPTIMIZATIONS"
+        }
+      }
+    end
+    
+    # @return [Hash] The configuration for the currently set environment.
+    def env_config
+      @config[@environment]
+    end
+    
+    # @return [Array<String>] All defined asset types.
+    def asset_types
+      @definitions.keys
+    end
+    
+  end
+end