stylist 0.1.0

data/.document

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

data/.gitignore

@@ -0,0 +1,12 @@
+.DS_Store
+**/.DS_Store
+pkg
+doc
+rdoc
+coverage
+*.swp
+*.tmproj
+tmtags
+*~
+\#*
+.\#*

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Tisho Georgiev
+
+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.md

@@ -0,0 +1,236 @@
+Stylist
+=======
+
+
+	 ____    __             ___                 __         
+	/\  _`\ /\ \__         /\_ \    __         /\ \        
+	\ \,\L\_\ \ ,_\  __  __\//\ \  /\_\    ____\ \ \___    
+	 \/_\__ \\ \ \/ /\ \/\ \ \ \ \ \/\ \  /',__\\ \  _ `\  
+	   /\ \L\ \ \ \_\ \ \_\ \ \_\ \_\ \ \/\__, `\\ \ \ \ \ 
+	   \ `\____\ \__\\/`____ \/\____\\ \_\/\____/ \ \_\ \_\
+	    \/_____/\/__/ `/___/> \/____/ \/_/\/___/   \/_/\/_/
+	                     /\___/                            
+	                     \/__/
+
+
+_Stylist_ provides powerful stylesheet management for your Rails app. You can organize your .css files by media, add, remove or prepend stylesheets in the stylesheets stack from your controllers and views, and process them using [Less](http://lesscss.org) or [Sass](http://sass-lang.com/). And as if that wasn't awesome enough, you can even minify them using [YUI Compressor](http://developer.yahoo.com/yui/compressor) and bundle them into completely incomprehensible, but bandwidth-friendly mega-stylesheets.
+
+Install
+=======
+
+Rails 2.x
+-------
+
+Put this in your `environment.rb` file:
+
+	config.gem 'stylist'
+	
+That's it. `rake gems:install` and you're done.
+
+Rails 3
+-------
+
+Add this to your `Gemfile`:
+
+	gem 'stylist'
+
+That's it. `bundle install` and you're good to go.
+
+How It Works
+=======
+
+The inner-workings of Stylist are actually pretty simple. Stylist keeps track of stylesheets you intend to use on a given page by storing them in a `Hash` with media types as keys. When you call `render_stylesheets` in your views, it processes all stylesheets in the hash and passes the resulting file paths to Rails's `stylesheet_link_tag`. It takes advantage of Rails's asset caching features by bundling the stylesheets in files with names like `all-[unique hash of collection].css`.
+
+Usage
+=======
+
+In order to use Stylist, you have to add this to the part of your layout file(s) responsible for `<link>` tag generation (where your `stylesheet_link_tag` used to be):
+
+	views/layouts/application.html.haml
+	-----------------------------------
+	
+	%html
+		%head
+			%title My Awesome App
+			- css :base
+			= render_stylesheets
+		%body	
+			= yield
+
+This will make sure that the stylesheets stack always has the `:base` stylesheet expansion group loaded before everything else and will then render the necessary `<link>` tags. The above example is using [Haml](http://haml-lang.com), but fear not if you're using regular ERB templates. Just write `<%= render_stylesheets %>`, instead of `= render_stylesheets` and `<% css :base %>`, instead of `- css :base`.
+
+After you've done that, you can start manipulating the stylesheet stack from whatever view and/or controller you like.
+
+The `css` Helper
+-------
+
+The `css` helper is used to manipulate the current stylesheet stack. You can use it in both controllers and views.
+
+Examples
+------
+
+These can be written either in your views inside `<% %>` tags, or directly in your controller actions or filters. Every method accepts a `:media => :type` argument to specify what stylesheet stack should be manipulated. When omitted, the default media stack is used.
+
+*		`css 'list_view', 'foo_details'`
+		Adds `list_view.css` and `foo_details.css` to the stack.
+	
+*		`css.remove('grid').prepend('grid_iphone').append('mobile')` 	
+		Removes `grid.css`, prepends `grid_iphone.css` to the front of the stack and then appends `mobile.css` to the end.
+		
+*		`css '-grid', 'grid_iphone+', 'mobile'`
+		The short, ninja version of the above example.
+		
+* 	`css :print, :media => :print`
+		Adds the stylesheets, registered in the `:print` stylesheet expansion group, to the print media stack.
+
+Working with Less/Sass
+-------
+
+If you've used the special route/controller approach up til now, you can safely get rid of it. Stylist will automatically find any files in the stack that have `.less` or `.sass` sources, "compile" and cache them. If you decide to update the source files, just reload the page. Stylist will detect if you've made any changes to the original files and re-compile them.
+
+Working with the YUI Compressor
+-------
+
+It's important to note that `:yui_compressor` should be _the last processor_ that your files should go through. That's because for every file it minifies, YUI Compressor generates a corresponding `filename-min.css` and then replaces the path in the original collection with the minified one. This is done to make sure you never overwrite your original files with minified ones. It also means that you probably don't want to have anything `-min.css` in your public stylesheets dir.
+
+Configuration
+=======
+
+You can provide additional configuration options to _Stylist_ by using its `Stylist.configure` method. Say you want to process your stylesheets with _Less_. Put this in `config/initializers/stylist.rb`:
+
+	Stylist.configure do |config|
+		config.process_with :less
+	end
+
+Global Configuration Options
+------
+
+`process_with`
+-----
+
+Accepts an array of processors that each file will pass through before being linked on the page. Currently, _Stylist_ has support for _Less_, _Sass_ and _YUI Compressor_ built in. In order to use them, pass either `:less`, `:sass`, `:yui_compressor` or a combination of them to `process_with`. For example, if you want to have your stylesheets processes with _Sass_, and then minified with _YUI Compressor_, you'd have the following config block:
+
+	Stylist.configure do |config|
+		config.process_with :sass, :yui_compressor
+	end
+
+Additionally, you can pass your own processor classes to `process_with`. Just make sure they respond to a `process!` method. More on this later.	
+
+`default_media`
+-----
+
+This is where your stylesheets will end up when you don't specify which media type they should respond to. Defaults to `:all`
+
+`public_stylesheets_path`
+-----
+
+This one is pretty self-explanatory. It's a `Pathname` instance that defaults to `your_app/public/stylesheets`.
+
+Less-Specific Configuration Options
+------
+
+`less.source_path`
+-----
+
+This is where all your `.lss` or `.less` source files reside. Defaults to `your_app/app/stylesheets`.
+
+`less.compress`
+-----
+
+When this options is set to `true`, the _Less_ processor will automatically strip all newlines in the resulting CSS file. On by default.
+
+Sass-Specific Configuration Options
+------
+
+`sass.source_path`
+-----
+
+This is where all your `.sass` source files reside. Defaults to `your_app/app/stylesheets`.
+
+`sass.compress`
+-----
+
+When this options is set to `true`, the _Sass_ processor will automatically strip all newlines in the resulting CSS file. On by default.
+
+YUICompressor-Specific Configuration Options
+------
+
+`yui_compressor.path_to_jar`
+-----
+
+The path to your `yuicompressor-x.x.x.jar` file. Doesn't default to anything, so make sure you set it if you want to use the compressor.
+
+`yui_compressor.path_to_java`
+-----
+
+The path to your `java` executable. Defaults to just `java` and expects to pick it up from your environment, but it's not anywhere in your `$PATH`, make sure you set this option.
+
+`yui_compressor.charset`
+-----
+
+The character set used to read the stylesheet files. Defaults to `utf-8`.
+
+`yui_compressor.line_break`
+-----
+
+The number of characters after which YUI Compressor will try to put a line break. Equivalent to the `--line-break` option when running YUI Compressor from the command line. `nil` by default (so no line breaks).
+
+`yui_compressor.production_only`
+-----
+
+When set to `true` the _YUI Compressor_ processor will only attempt to minify a collection of CSS files when your app is running in a production environment. On by default.
+
+Rolling Your Own Processor
+=======
+
+The basics (`lib/stylist/rainbows_and_unicorns_processor.rb`):
+
+	module Stylist
+		module Processors
+		
+			class RainbowsAndUnicornsProcessor < Processor
+				class << self
+				
+					# This method will be called automatically when you add your processor
+					# to the config.process_with array. It has access to the Stylist configuration
+					# object called 'configuration'.
+					
+					def configure
+						configuration.add_option_group :rainbows_and_unicorns, { :unicorns => true, :rainbows => true }
+					end
+					
+					# Called from 'render_stylesheets'. Passes the collection hash as an argument.
+					
+					def	process!(collection)
+						# TODO: Add unicorns and rainbows in every stylesheet
+						# ...
+					end
+					
+				end
+			end
+			
+		end
+	end
+
+Then in your `initializers/stylist.rb`:
+
+	Stylist.configure do |config|
+		config.process_with :rainbows_and_unicorns
+		config.rainbows_and_unicorns.rainbows = false
+	end
+	
+If you choose to not make `RainbowsAndUnicornsProcessor` part of `Stylist::Processors`, make sure you pass it to `config.process_with` as a class, instead of a symbol. Stylist will automatically try to expand symbols and strings to `Stylist::Processors::SomeStringProcessor`.
+
+The base `Stylist::Processors::Processor` class also lets you use an `expand_stylesheet_sources(*sources)` method that you can use to explode stylesheet expansions into a series of filepaths.
+
+If you choose to create your own processor, I strongly advise you to look at one of the built-in ones for reference.
+
+Credits
+=======
+
+Stylist was extracted with little modification from the loving embrace of the [TransFS](http://transfs.com) codebase, which to this day helps businesses quickly and easily compare the best credit card processors. For more open-source love from [TFS](htp://transfs.com), please take a look at [AppConfig](http://github.com/tisho/app_config) and [FunnelCake](http://github.com/jkrall/funnel_cake).
+
+License
+=======
+
+Copyright (c) 2010 Tisho Georgiev, released under the MIT license

data/Rakefile

@@ -0,0 +1,82 @@
+require 'rubygems'
+require 'rake'
+require File.dirname(__FILE__) + "/lib/stylist/version.rb"
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "stylist"
+    gem.version = Stylist::VERSION::STRING
+    gem.summary = %Q{Powerful stylesheet management for your Rails app.}
+    gem.description = %Q{Stylist provides powerful stylesheet management for your Rails app. You can organize your CSS files by media, add, remove or prepend stylesheets in the stylesheets stack from your controllers and views, and process them using Less or Sass. And as if that wasn't awesome enough, you can even minify them using YUI Compressor and bundle them into completely incomprehensible, but bandwidth-friendly mega-stylesheets.}
+    gem.email = "tihomir.georgiev@gmail.com"
+    gem.homepage = "http://github.com/tisho/stylist"
+    gem.authors = ["Tisho Georgiev"]
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    gem.add_development_dependency "rails", ">= 2.3"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+namespace :spec do
+  desc 'Run RSpec code examples within a Rails 2 environment.'
+  task :rails2 do
+    RakeFileUtils.verbose(verbose) do
+      spec_files = FileList['spec/**/*_spec.rb'].to_a
+      lib_path = ['lib', 'spec']
+      spec_script = Gem.bin_path('rspec', 'spec', '~> 1.2')
+      
+      unless spec_files.empty?
+        cmd_parts = ['RAILS_VERSION=2', RUBY]
+        cmd_parts << '-Ilib'
+        cmd_parts << '-Ispec'
+        cmd_parts << %["#{spec_script}"]
+        cmd_parts += spec_files.collect { |fn| %["#{fn}"] }
+        cmd = cmd_parts.join(" ")
+        puts cmd if verbose
+        unless system(cmd)
+          raise("Command #{cmd} failed")
+        end
+      end    
+    end
+  end
+  
+  desc 'Run RSpec code examples within a Rails 3 environment.'
+  task :rails3 do
+    RAILS_VERSION = 3
+    RakeFileUtils.verbose(verbose) do
+      spec_files = FileList['spec/**/*_spec.rb'].to_a
+      lib_path = ['lib', 'spec']
+      
+      unless spec_files.empty?
+        cmd_parts = ['RAILS_VERSION=3', RUBY]
+        cmd_parts << '-Ilib'
+        cmd_parts << '-Ispec'
+        cmd_parts += spec_files.collect { |fn| %["#{fn}"] }
+        cmd = cmd_parts.join(" ")
+        puts cmd if verbose
+        unless system(cmd)
+          raise("Command #{cmd} failed")
+        end
+      end    
+    end
+  end
+end
+
+desc "Run RSpec code examples first in Rails 2, then in a Rails 3 environment."
+task :spec => [:check_dependencies, 'spec:rails2', 'spec:rails3']
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "stylist #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/init.rb

@@ -0,0 +1 @@
+require 'stylist'

data/lib/stylist/configuration.rb

@@ -0,0 +1,56 @@
+module Stylist
+  class << self
+    attr_accessor :configuration
+  end
+  
+  def self.configure
+    self.configuration ||= Configuration.new
+    yield(configuration)
+  end
+  
+  class Configuration
+    attr_reader :processors
+    attr_accessor :public_stylesheets_path, :default_media
+
+    def initialize
+      @default_media = :all
+      @processors = []
+      @public_stylesheets_path = "#{defined?(Rails.public_path) ? Rails.public_path : 'public'}/stylesheets"
+    end
+    
+    def metaclass
+      class << self; self; end
+    end
+    
+    def add_option_group(group_name, options={})
+      group = instance_variable_set "@#{group_name}", Configuration.new
+      metaclass.class_eval <<-EOC
+        attr_reader :#{group_name}
+      EOC
+      
+      options.each_pair { |key, value| group.add_option(key, value) }
+    end
+    
+    def add_option(key, default_value=nil)
+      metaclass.class_eval <<-EOC
+        attr_accessor :#{key}
+      EOC
+      
+      instance_variable_set "@#{key}", default_value
+    end
+    
+    def process_with(*processors)
+      @processors = processors.collect do |processor|
+        if processor.is_a? Class
+          processor_class = processor
+        else
+          class_name = processor.to_s.strip.camelize.sub(/(Processor)?$/, 'Processor')
+          processor_class = class_name.constantize rescue "::Stylist::Processors::#{class_name}".constantize
+        end
+      end.compact
+      
+      @processors.each { |processor| processor.configure if processor.respond_to?(:configure) }
+    end
+    
+  end
+end

data/lib/stylist/controller_mixin.rb

@@ -0,0 +1,19 @@
+module Stylist
+  module ControllerMixin
+    
+    def self.included(base)
+      base.class_eval do
+        include       InstanceMethods
+        before_filter { Stylist.stylesheets.reset! }
+    	  helper_method :css
+      end
+    end
+    
+    module InstanceMethods
+      def css(*args)
+        Stylist.stylesheets.manipulate *args
+      end
+    end
+    
+  end
+end

data/lib/stylist/processor.rb

@@ -0,0 +1,35 @@
+module Stylist
+  module Processors
+    class Processor
+      
+      class << self
+        def configuration; Stylist.configuration; end
+        
+        def process!(collection)
+          # Provide your own implementation
+        end
+        
+        def expand_stylesheet_sources(*sources)
+          expansions = defined?(ActionView::Helpers::AssetTagHelper) ? ActionView::Helpers::AssetTagHelper.send(:class_variable_get, :@@stylesheet_expansions) : {}
+
+          sources.flatten.collect do |source|
+            case source
+            when Symbol
+              expansions[source] || raise(ArgumentError, "No expansion found for #{source.inspect}")
+            else
+              source
+            end
+          end.flatten.collect do |source|
+            source_ext = File.extname(source)[1..-1]
+            if (source_ext.blank? || ('css' != source_ext))
+              source += ".css"
+            end
+
+            Rails.root.join(configuration.public_stylesheets_path, source)
+          end
+        end
+      end
+      
+    end
+  end
+end

data/lib/stylist/processors/less_processor.rb

@@ -0,0 +1,42 @@
+require 'less' unless defined?(::Less)
+
+module Stylist
+  module Processors
+    class LessProcessor < Processor
+      class << self
+        def configure
+          configuration.add_option_group :less, { :source_path => ::Rails.root.join('app/stylesheets'), :compress => true }
+        end
+        
+        def process!(collection)
+          stylesheets_to_process(collection).each do |stylesheet|
+            source_path = source_path_for(stylesheet)
+            
+            if source_path && source_path.exist?
+              engine = File.open(source_path) {|f| ::Less::Engine.new(f) }
+              css = engine.to_css
+              css.delete!("\n") if configuration.less.compress
+              File.open(stylesheet, "w") { |f| f.puts css }
+            end
+          end
+        end
+        
+        def source_path_for(file)
+          Pathname.glob(File.join(configuration.less.source_path, File.basename(file, '.css')+'.{css,less,lss}'))[0]
+        end
+
+        def stylesheets_to_process(collection)
+          expand_stylesheet_sources(collection.values.flatten).select do |file|
+            (File.exists?(file) and source_has_been_changed?(file)) or not File.exists?(file)
+          end
+        end
+
+        def source_has_been_changed?(file)
+          source_path = source_path_for(file)
+          source_path && (File.new(source_path).mtime >= File.new(file).mtime)
+        end
+      end
+      
+    end
+  end
+end

data/lib/stylist/processors/sass_processor.rb

@@ -0,0 +1,41 @@
+module Stylist
+  module Processors
+    class SassProcessor < Processor
+      
+      class << self
+        def configure
+          configuration.add_option_group :sass, { :source_path => ::Rails.root.join('app/stylesheets'), :compress => true }
+        end
+        
+        def process!(collection)
+          stylesheets_to_process(collection).each do |stylesheet|
+            source_path = source_path_for(stylesheet)
+            if source_path && source_path.exist?
+              puts "Processing #{source_path}..."
+              engine = File.open(source_path) {|f| ::Sass::Engine.new(f.read) }
+              css = engine.to_css
+              css.delete!("\n") if configuration.sass.compress
+              File.open(stylesheet, "w") { |f| f.puts css }
+            end
+          end
+        end
+        
+        def source_path_for(file)
+          Pathname.glob(File.join(configuration.sass.source_path, File.basename(file, '.css')+'.sass'))[0]
+        end
+
+        def stylesheets_to_process(collection)
+          expand_stylesheet_sources(collection.values.flatten).select do |file|
+            (File.exists?(file) and source_has_been_changed?(file)) or not File.exists?(file)
+          end
+        end
+
+        def source_has_been_changed?(file)
+          source_path = source_path_for(file)
+          source_path && (File.new(source_path).mtime >= File.new(file).mtime)
+        end
+      end
+      
+    end
+  end
+end

data/lib/stylist/processors/yui_compressor_processor.rb

@@ -0,0 +1,62 @@
+module Stylist
+  module Processors
+    class YuiCompressorProcessor < Processor
+      class MinificationCommandFailed < StandardError; end
+        
+      class << self
+        def configure
+          configuration.add_option_group :yui_compressor, { :path_to_jar => nil, :path_to_java => 'java', :charset => 'utf-8', :line_break => nil, :production_only => true }
+        end
+        
+        def process!(collection)
+          return if configuration.yui_compressor.production_only and not Rails.env.production?
+          
+          stylesheets_to_process(collection).each do |stylesheet|
+            minify(stylesheet)
+          end
+          replace_files_in_collection_with_minified_files(collection)
+        end
+        
+        def replace_files_in_collection_with_minified_files(collection)
+          collection.each_pair do |media, stylesheets|
+            collection[media] = expand_stylesheet_sources(stylesheets).map { |stylesheet| minified_stylesheet_name_for(stylesheet).basename.to_s }
+          end
+        end
+        
+        def minify(stylesheet)
+          config = configuration.yui_compressor
+          command = [config.path_to_java, '-jar', config.path_to_jar, '-o', minified_stylesheet_name_for(stylesheet), *command_options] << stylesheet
+          unless system(*command) 
+            raise MinificationCommandFailed, "Oops! Minification command failed with error code: #{$?}. The command executed was: #{command.join ' '}"
+          end
+        end
+        
+        def command_options
+          config = configuration.yui_compressor
+          { :type => 'css', :charset => config.charset, :line_break => nil }.inject([]) do |options, (name, argument)|
+            options.concat(["--#{name.to_s.gsub '_', '-'}", argument.to_s]) if argument
+            options
+          end
+        end
+        
+        def minified_stylesheet_name_for(stylesheet)
+          dir, filename = stylesheet.split
+          dir.join([filename.basename(filename.extname), '.min', filename.extname].join)
+        end
+        
+        def stylesheets_to_process(collection)
+          expand_stylesheet_sources(collection.values.flatten).select do |source_file|
+            minified_file = minified_stylesheet_name_for(source_file)
+            (minified_file.exist? and source_has_been_changed?(source_file)) or (source_file.exist? and not minified_file.exist?)
+          end
+        end
+
+        def source_has_been_changed?(file)
+          minified_path = minified_stylesheet_name_for(file)
+          minified_path.exist? && (File.new(file).mtime >= File.new(minified_path).mtime)
+        end        
+      end
+    
+    end
+  end
+end

data/lib/stylist/railtie.rb

@@ -0,0 +1,17 @@
+module Stylist
+  class Railtie < Rails::Railtie
+    railtie_name :stylist
+    
+    initializer :configure_stylist_defaults, :before => :load_application_initializers do |app|
+      if defined? ::Haml
+        require 'stylist/processors/sass_processor'
+        ::Stylist.configure { |config| config.process_with :sass }
+      end
+
+      if defined? ::Less
+        require 'stylist/processors/less_processor'
+        ::Stylist.configure { |config| config.process_with :less }
+      end      
+    end
+  end
+end