rack-less 0.1.0

data/README.rdoc

@@ -0,0 +1,90 @@
+= Rack::Less
+
+== Description
+
+A better way to use LESS CSS in Ruby web apps.
+
+== Installation
+
+    $ gem install rack-less
+
+== Basic Usage
+
+Rack::Less is implemented as a piece of Rack middleware and can be used with
+any Rack-based application. If your application includes a rackup (`.ru`) file
+or uses Rack::Builder to construct the application pipeline, simply require
+and use as follows:
+
+    require 'rack/less'
+    use Rack::Less do
+      set :source,    'app/less'
+      set :hosted_at, '/'
+      set :compress,  true
+    end
+    run app
+
+== Using with Rails
+
+Add this to your `config/environment.rb`:
+
+    config.middleware.use Rack::Less, :compress => true
+
+You should now see `Rack::Less` listed in the middleware pipeline:
+
+    rake middleware
+    
+== Available Options
+
+* *root*["."]:
+  the app root. the reference point for the source and public options.  #TODO: default appropriately for Rails/Sinatra.
+
+* *source*['app/stylesheets']:
+  the path (relative to the root) where LESS files are located
+
+* *public*['public']:
+  the path (relative to the root) where LESS files are located
+
+* *hosted_at*['/stylesheets']:
+  the public HTTP root path for stylesheets
+
+* *cache*[false]:
+  whether to cache the compilation output to a corresponding file in the hosted_root
+
+* *compress*[false]:
+  whether to remove extraneous whitespace from compilation output
+
+* *combinations*[{}]:
+  directives for combining the ouput of one or more LESS compilations, for example:
+    set :combine, { 'app' => ['one', 'two', 'three'] }
+  will direct Rack::Less to respond to a request for app.css with the concatenated output of compiling one.less, two.less, and three.less
+  
+== Links
+
+GitHub: http://github.com/kelredd/rack-less
+    
+Less:   http://lesscss.org
+
+== License
+
+Copyright (c) 2010 Kelly Redding (mailto:kelly@kelredd.com)
+
+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/Rakefile

@@ -0,0 +1,61 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+require 'rake/testtask'
+
+require 'lib/rack/less/version'
+
+spec = Gem::Specification.new do |s|
+  s.name             = 'rack-less'
+  s.version          = RackLess::Version.to_s
+  s.has_rdoc         = true
+  s.extra_rdoc_files = %w(README.rdoc)
+  s.rdoc_options     = %w(--main README.rdoc)
+  s.summary          = "A better way to use LESS CSS in Ruby web apps."
+  s.author           = 'Kelly Redding'
+  s.email            = 'kelly@kelredd.com'
+  s.homepage         = 'http://github.com/kelredd/rack-less'
+  s.files            = %w(README.rdoc Rakefile) + Dir.glob("{lib}/**/*")
+  # s.executables    = ['rack-less']
+
+  s.add_dependency("rack", [">= 0.4"])
+  s.add_dependency("less", [">= 1.2.21"])
+
+  s.add_development_dependency("shoulda", [">= 2.10.2"])
+  s.add_development_dependency("sinatra", [">= 0.9.4"])
+  s.add_development_dependency("rack-test", [">= 0.5.3"])
+  s.add_development_dependency("webrat", [">= 0.6.0"])
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+
+  Rcov::RcovTask.new(:coverage) do |t|
+    t.libs       = ['test']
+    t.test_files = FileList["test/**/*_test.rb"]
+    t.verbose    = true
+    t.rcov_opts  = ['--text-report', "-x #{Gem.path}", '-x /Library/Ruby', '-x /usr/lib/ruby']
+  end
+  
+  task :default => :coverage
+  
+rescue LoadError
+  warn "\n**** Install rcov (sudo gem install relevance-rcov) to get coverage stats ****\n"
+  task :default => :test
+end
+
+desc 'Generate the gemspec to serve this gem'
+task :gemspec do
+  file = File.dirname(__FILE__) + "/#{spec.name}.gemspec"
+  File.open(file, 'w') {|f| f << spec.to_ruby }
+  puts "Created gemspec: #{file}"
+end

data/lib/rack/less.rb

@@ -0,0 +1,34 @@
+require 'rack'
+require 'rack/less/base'
+require 'rack/less/options'
+require 'rack/less/request'
+require 'rack/less/response'
+require 'rack/less/source'
+
+# === Usage
+#
+# Create with default configs:
+#   require 'rack/less'
+#   Rack::Less.new(app, :compress => true)
+#
+# Within a rackup file (or with Rack::Builder):
+#   require 'rack/less'
+#   use Rack::Less do
+#     set :root,     "."
+#     set :source,   'app/less'
+#     set :compress, true
+#   end
+#   run app
+
+module Rack::Less
+  MEDIA_TYPE = "text/css"
+
+  # Create a new Rack::Less middleware component 
+  # => the +options+ Hash can be used to specify default configuration values
+  # => a block can given as an alternate method for setting option values (see example above)
+  # => (see Rack::Less::Options for possible key/values)
+  def self.new(app, options={}, &block)
+    Base.new(app, options, &block)
+  end
+  
+end

data/lib/rack/less/base.rb

@@ -0,0 +1,69 @@
+require 'rack/less/options'
+require 'rack/less/request'
+require 'rack/less/response'
+
+module Rack::Less
+  class Base
+    include Rack::Less::Options
+
+    def initialize(app, options={})
+      @app = app
+      initialize_options options
+      yield self if block_given?
+      validate_options
+    end
+
+    # The Rack call interface. The receiver acts as a prototype and runs
+    # each request in a clone object unless the +rack.run_once+ variable is
+    # set in the environment.
+    # ripped from: http://github.com/rtomayko/rack-cache/blob/master/lib/rack/cache/context.rb
+    def call(env)
+      if env['rack.run_once']
+        call! env
+      else
+        clone.call! env
+      end
+    end
+
+    # The real Rack call interface.
+    # if LESS CSS is being requested, this is an endpoint:
+    # => generate the compiled css
+    # => respond appropriately
+    # Otherwise, call on up to the app as normal
+    def call!(env)
+      @default_options.each { |k,v| env[k] ||= v }
+      @env = env
+      # TODO: get this going
+      
+      if (@request = Request.new(@env.dup.freeze)).for_less?
+        Response.new(@env.dup.freeze, @request.source.to_css).to_rack
+      else
+        @app.call(env)
+      end
+    end
+    
+    private
+    
+    def validate_options
+      # ensure a root path is specified and does exists
+      unless options.has_key?(option_name(:root)) and !options(:root).nil?
+        raise(ArgumentError, "no :root option set")
+      end
+      unless File.exists?(options(:root))
+        raise(ArgumentError, "the :root path ('#{options(:root)}') does not exist") 
+      end
+
+      set :root, File.expand_path(options(:root))
+
+      # ensure a source path is specified and does exists
+      unless options.has_key?(option_name(:source)) and !options(:source).nil?
+        raise(ArgumentError, "no :source option set")
+      end
+      source_path = File.join(options(:root), options(:source))
+      unless File.exists?(source_path)
+        raise(ArgumentError, "the :source path ('#{source_path}') does not exist") 
+      end
+    end
+
+  end
+end

data/lib/rack/less/options.rb

@@ -0,0 +1,128 @@
+module Rack::Less
+  module Options
+    
+    # Handles options and configuration for Rack::Less
+    # Available options:
+    # => root
+    #    the app root. the reference point for the
+    #    source and public options
+    # => source
+    #    the path (relative to the root) where
+    #    LESS files are located
+    # => public
+    #    the path (relative to the root) where
+    #    static files are served
+    # => hosted_at
+    #    the public HTTP root path for stylesheets
+    # => cache
+    #    whether to cache the compilation output to a
+    #    corresponding file in the hosted_root
+    # => compress
+    #    whether to remove extraneous whitespace from
+    #    compilation output
+    # => combine
+    #    expects a hash containing directives for combining
+    #    the ouput of one or more LESS compilations, for example:
+    #    { 'app' => ['one', 'two', 'three']}
+    #    will respond to a request for app.css with the concatenated
+    #    output of compiling one.less, two.less, and three.less
+    
+    # Note: the following code is more or less a rip from:
+    # => http://github.com/rtomayko/rack-cache/blob/master/lib/rack/cache/options.rb
+    # => thanks to rtomayko, I thought this approach was really smart and the credit is his.
+    
+    RACK_ENV_NS = "rack-less"
+    
+    module ClassMethods
+      
+      def defaults
+        {
+          option_name(:root)      => ".",
+          option_name(:source)    => 'app/stylesheets',
+          option_name(:public)    => 'public',
+          option_name(:hosted_at) => '/stylesheets',
+          option_name(:cache)     => false,
+          option_name(:compress)  => false,
+          option_name(:combine)   => {}
+        }
+      end
+
+      # Rack::Less uses the Rack Environment to store option values. All options
+      # are stored in the Rack Environment as "<RACK_ENV_PREFIX>.<option>", where
+      # <option> is the option name.
+      def option_name(key)
+        case key
+        when Symbol ; "#{RACK_ENV_NS}.#{key}"
+        when String ; key
+        else raise ArgumentError
+        end
+      end
+      
+    end
+    
+    module InstanceMethods
+      
+      # Rack::Less uses the Rack Environment to store option values. All options
+      # are stored in the Rack Environment as "<RACK_ENV_PREFIX>.<option>", where
+      # <option> is the option name.
+      def option_name(key)
+        self.class.option_name(key)
+      end
+      
+      # The underlying options Hash. During initialization (or outside of a
+      # request), this is a default values Hash. During a request, this is the
+      # Rack environment Hash. The default values Hash is merged in underneath
+      # the Rack environment before each request is processed.
+      # => if a key is passed, the option value for the key is returned
+      def options(key=nil)
+        if key
+          (@env || @default_options)[option_name(key)]
+        else
+          @env || @default_options
+        end
+      end
+
+      # Set multiple options at once.
+      def options=(hash={})
+        hash.each { |key,value| write_option(key, value) }
+      end 
+
+      # Set an option. When +option+ is a Symbol, it is set in the Rack
+      # Environment as "rack-cache.option". When +option+ is a String, it
+      # exactly as specified. The +option+ argument may also be a Hash in
+      # which case each key/value pair is merged into the environment as if
+      # the #set method were called on each.
+      def set(option, value=nil, &block)
+        if block_given?
+          write_option option, block
+        elsif value.nil?
+          self.options = option.to_hash
+        else
+          write_option option, value
+        end
+      end
+
+      private
+
+      def initialize_options(options={})
+        @default_options = self.class.defaults
+        self.options = options
+      end
+
+      def read_option(key)
+        options[option_name(key)]
+      end
+
+      def write_option(key, value)
+        options[option_name(key)] = value
+      end
+
+    end
+    
+    def self.included(receiver)
+      receiver.extend         ClassMethods
+      receiver.send :include, InstanceMethods
+    end
+    
+  end
+end

data/lib/rack/less/request.rb

@@ -0,0 +1,72 @@
+require 'rack/request'
+require 'rack/less'
+require 'rack/less/options'
+require 'rack/less/source'
+
+module Rack::Less
+
+  # Provides access to the HTTP request.
+  # Request objects respond to everything defined by Rack::Request
+  # as well as some additional convenience methods defined here
+  # => from: http://github.com/rtomayko/rack-cache/blob/master/lib/rack/cache/request.rb
+
+  class Request < Rack::Request
+    include Rack::Less::Options
+    
+    CSS_PATH_REGEX = /\A.*\/(\w+)\.(\w+)\Z/
+    CSS_PATH_FORMATS = ['css']
+
+    # The HTTP request method. This is the standard implementation of this
+    # method but is respecified here due to libraries that attempt to modify
+    # the behavior to respect POST tunnel method specifiers. We always want
+    # the real request method.
+    def request_method
+      @env['REQUEST_METHOD']
+    end
+    
+    def path_info
+      @env['PATH_INFO']
+    end
+    
+    # TODO: test these
+    def path_resource_name
+      path_info =~ CSS_PATH_REGEX ? path_info.match(CSS_PATH_REGEX)[1] : nil
+    end
+    
+    def path_resource_format
+      path_info =~ CSS_PATH_REGEX ? path_info.match(CSS_PATH_REGEX)[2] : nil
+    end
+
+    # The Rack::Less::Source that the request is for
+    def source
+      @source ||= begin
+        cache = if options(:cache)
+          File.join(options(:root), options(:public), options(:hosted_at))
+        else
+          nil
+        end
+        source_opts = {
+          :folder   => File.join(options(:root), options(:source)),
+          :cache    => cache,
+          :compress => options(:compress),
+          :combine  => options(:combine)
+        }
+        Source.new(path_resource_name, source_opts)
+      end
+    end
+
+    def for_css?
+      media_type == Rack::Less::MEDIA_TYPE ||
+      CSS_PATH_FORMATS.include?(path_resource_format)
+    end
+
+    # Determine if the request is for existing LESS CSS file
+    # This will be called on every request so speed is an issue
+    # => first check if the request is a GET on a css resource (fast)
+    # => then check for less source files that match the request (slow)
+    def for_less?
+      get? && for_css? && !source.files.empty?
+    end
+    
+  end
+end

data/lib/rack/less/response.rb

@@ -0,0 +1,45 @@
+require 'rack/response'
+require 'rack/utils'
+
+module Rack::Less
+
+  # Given some generated css, mimicks a Rack::Response
+  # => call to_rack to build standard rack response parameters
+  class Response
+    include Rack::Less::Options
+    include Rack::Response::Helpers
+
+    # Rack response tuple accessors.
+    attr_accessor :status, :headers, :body
+    
+    class << self
+
+      # Calculate appropriate content_length
+      def content_length(body)
+        if body.respond_to?(:bytesize)
+          body.bytesize
+        else
+          body.size
+        end
+      end
+      
+    end
+
+    # Create a Response instance given the env
+    # and some generated css.
+    def initialize(env, css)
+      @env = env
+      @body = css
+      @status = 200 # OK
+      @headers = Rack::Utils::HeaderHash.new
+
+      headers["Content-Type"] = Rack::Less::MEDIA_TYPE
+      headers["Content-Length"] = self.class.content_length(body).to_s
+    end
+    
+    def to_rack
+      [status, headers.to_hash, body]
+    end
+
+  end
+end

data/lib/rack/less/source.rb

@@ -0,0 +1,98 @@
+require 'less'
+
+module Rack::Less
+
+  # The engine for compiling LESS CSS
+  # Given the name of the less source file you want
+  # to compile and a path to the source files,
+  # will returns corresponding compiled LESS CSS
+  class Source
+    
+    # prefer source files with the .less extension
+    # but also accept files with the .css extension
+    PREFERRED_EXTENSIONS = [:less, :css]
+    
+    attr_reader :css_name
+    
+    def initialize(css_name, options={})
+      @css_name = css_name
+      @compress = options[:compress]
+      @cache    = options[:cache]
+      @folder   = get_required_path(options, :folder)
+      @combine  = options[:combine] || {}
+    end
+    
+    def compress?
+      !!@compress
+    end
+    def cache?
+      !@cache.nil?
+    end
+    
+    # Use named css sources before using combine directive sources
+    def files
+      @files ||= (css_sources.empty? ? combined_sources : css_sources)
+    end
+    
+    def compiled
+      @compiled ||= begin
+        compiled_css = files.collect do |file_path|
+          Less::Engine.new(File.new(file_path)).to_css
+        end.join("\n")
+        
+        compiled_css.delete!("\n") if compress?
+        if cache? && !File.exists?(cf = File.join(@cache, "#{@css_name}.css"))
+          FileUtils.mkdir_p(@cache)
+          File.open(cf, "w") do |file|
+            file.write(compiled_css)
+          end
+        end
+        
+        compiled_css
+      end
+    end
+    alias_method :to_css, :compiled
+    alias_method :css, :compiled
+    
+    protected
+    
+    # Preferred, existing source files matching the css name
+    def css_sources
+      @css_sources ||= preferred_sources([@css_name])
+    end
+    
+    # Preferred, existing source files matching a corresponding
+    # combine directive, if any
+    def combined_sources
+      @combined_sources ||= preferred_sources(@combine[@css_name] || [])
+    end
+    
+    private
+    
+    # Given a list of file names, return a list of
+    # existing source files with the corresponding names
+    # honoring the preferred extension list
+    def preferred_sources(file_names)
+      file_names.collect do |name|
+        PREFERRED_EXTENSIONS.inject(nil) do |source_file, extension|
+          source_file || begin
+            path = File.join(@folder, "#{name}.#{extension}")
+            File.exists?(path) ? path : nil
+          end
+        end
+      end.compact
+    end
+    
+    def get_required_path(options, path_key)
+      unless options.has_key?(path_key)
+        raise(ArgumentError, "no :#{path_key} option specified")
+      end
+      unless File.exists?(options[path_key])
+        raise(ArgumentError, "the :#{path_key} ('#{options[path_key]}') does not exist") 
+      end
+      options[path_key]
+    end
+    
+  end
+  
+end

data/lib/rack/less/version.rb

@@ -0,0 +1,13 @@
+module RackLess
+  module Version
+    
+    MAJOR = 0
+    MINOR = 1
+    TINY  = 0
+    
+    def self.to_s # :nodoc:
+      [MAJOR, MINOR, TINY].join('.')
+    end
+    
+  end
+end

metadata

@@ -0,0 +1,123 @@
+--- !ruby/object:Gem::Specification 
+name: rack-less
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Kelly Redding
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-02-08 00:00:00 -06:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rack
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0.4"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: less
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.2.21
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: shoulda
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.10.2
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: sinatra
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.9.4
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: rack-test
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.5.3
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: webrat
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.6.0
+    version: 
+description: 
+email: kelly@kelredd.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- README.rdoc
+- Rakefile
+- lib/rack/less/base.rb
+- lib/rack/less/options.rb
+- lib/rack/less/request.rb
+- lib/rack/less/response.rb
+- lib/rack/less/source.rb
+- lib/rack/less/version.rb
+- lib/rack/less.rb
+has_rdoc: true
+homepage: http://github.com/kelredd/rack-less
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: A better way to use LESS CSS in Ruby web apps.
+test_files: []
+