rcss 0.3.0

data/CHANGES

@@ -0,0 +1,9 @@
+= Version 0.3.0
+* Initial public release
+* Server side constants/variables (no include support yet)
+* Documentation
+
+= Version 0.2.1
+* ERB evaluation
+* Supports server-side classes using 'extends' attribute
+* Gem-based distribution

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2005 Lukasz 'Bragi Ragnarson' Piestrzeniewicz
+
+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

@@ -0,0 +1,351 @@
+= Rcss - CSS Server-side Constants for Ruby/Rails
+
+Information for version 0.3.0
+
+Rcss implements CSS-SSC in Ruby.
+
+Main features:
+
+* Create rich CSS files using:
+
+  * ERB templates
+
+  * Server-side constants
+
+  * Server-side classes (preliminary)
+
+* Simply add Rcss files to any Rails application
+
+* Process Rcss files off-line using command line executable
+
+== Introduction
+
+Rcss addresses issue of CSS maintainability. Even a minor change in complex 
+stylesheet usually requires using search-and-replace. A simple way to fix this 
+flaw is to allow some kind of constant/variable substitution inside CSS. Using 
+Rcss you can achieve that in three ways:
+
+=== ERB templates
+
+ERB templating is the most flexible solution. It uses standard ERB syntax (the 
+same you can find in rhtml files). ERB allows you to inlude in the CSS values 
+defined in controller. This gives access to database through ActiveRecord and
+allows database-driven CSS themes.
+
+Strengths
+
+* Access to application data (through ActiveRecord)
+* Flexible Ruby syntax (allowing programmatic CSS)
+
+Weaknesses
+
+* Syntax unfamiliar to CSS designers
+* A bit ugly and sometimes error-prone embedding
+* Not portable
+
+Example
+
+  <% template_color = "#000"
+     template_background = "#fff"
+     template_highlight = "#fa3"
+  %> 
+  body {
+  	color: <%= template_color %>;
+  	background-color: <%= template_background %>;  	
+  }
+  
+  h1 {
+  	color: <%= template_background %>;
+  	background-color: <%= template_highlight %>;
+  }
+
+=== Server-side Constants
+
+Server-side Constants were originaly developed by Shaun Inman in PHP. SSC 
+extends CSS syntax in a simple way. SCC is cross-platform and easy to use.
+
+Rcss differs from original implementation in two ways :
+
+* Constants may have complex values (including spaces and commas)
+* Includes are not implemented
+
+Strengths
+
+* Simple syntax
+* SSC-CSS files can be used in both Rails and PHP applications
+
+Weaknesses
+
+* Only simple constant substitution
+
+Example
+
+  @server constants {
+    template_color: #000;
+    template_background: #fff;
+    template_highlight: #fa3;
+
+    // Rcss specific (note spaces and commas)
+    template_font: "Trebuchet MS", "Bitstream Vera Sans", helvetica, sans-serif;
+  }
+
+  body {
+  	color: template_color;
+  	background-color: template_background;
+  	font-family: template_font;
+  }
+  
+  h1 {
+  	color: template_background;
+  	background-color: template_highlight;
+  	font-family: template_font;
+  }
+
+=== Server-side Classes (preliminary)
+
+*Warning* This functionality is subject to rapid change and future versions 
+might not be compatible with current implementation.
+
+Server-side Classes add multiple inheritence to CSS selectors. Now you can 
+'virtual', server-side selectors and use them to extend normal selectors. It is 
+just a simple way of inheriting several attributes at once. Together with two
+technics described above they give a very powerfull tool to create maintainable 
+CSS files.
+
+Strengths
+
+* Simple syntax
+* Specify multiple related attributes at the same time
+
+Weaknesses
+
+* Syntax is subject to change
+* No templating yet
+
+Example
+
+  @server &serif_font {
+  	font-family: "Trebuchet MS", "Bitstream Vera Sans", helvetica, sans-serif;
+  }
+  
+  @server &highlighted {
+    color: #000;
+    background-color: #fa3;
+  }
+
+  h1 {
+  	extends: &highlighted;
+  	extends: &serif_font;
+  }
+  
+  #menu {
+  	extends: &highlighted;
+  }
+
+== Installation
+
+Download and install Rcss with the following command:
+
+   gem install --remote rcss
+   
+== Usage
+
+=== Command line
+
+NAME
+     rcss - process rich CSS files
+
+SYNOPSIS
+     rcss [RcssFile]
+     
+DESCRIPTION
+     Reads and processes rich CSS files. Processed file is printed to standard
+     output. If no file is given standard input is processed instead.
+            
+EXAMPLE
+     rcss default.rcss >default.css
+
+     Will read contents of default.rcss file, evaluate ERB templates, server 
+     side constants and classes. Output will be redirected to default.css file.
+     
+=== Rails
+
+Using Rcss in Rails environment requires several steps.
+
+1. Modify your <code>config/environment.rb</code> file and add following line:
+
+    require 'rcss'
+  
+2. Create controller that will be serving Rcss files. Create 
+   <code>app/controllers/rcss_controller.rb</code> file with following content:
+   
+    class RcssController < ApplicationController
+      def render_rcss
+        if params[:rcss] =~ /\.css$/
+          template = $`
+	    else
+	      template = params[:rcss]
+        end
+        render :action => template, :type => 'rcss', :layout => false
+      end
+    end
+
+3. For convenience add route entries that will handle Rcss files. Modify file
+   <code>config/routes.rb</code> and add following lines *before* the default route:
+   
+     map.connect 'rcss/:rcss', :controller => 'rcss', :action => 'render_rcss'
+     map.rcss 'rcss/:rcss', :controller => 'rcss', :action => 'render_rcss'
+
+4. Create following test Rcss file <code>app/views/rcss/test.rcss</code>:
+
+    <% test_color = "#000" %>
+
+    @server constants {
+      test_background: #fff;
+    }
+    
+    @server &test_class {
+      color: <%= test_color %>;
+      background-color: test_background;
+    }
+    
+    body {
+      extends: &test_class;
+    }
+
+5. Start your Rails application
+
+    $ ruby scripts/server
+    
+   Point your browser to location: http://localhost:3000/rcss/test.css
+   You should see following content:
+   
+     body {
+       color: #000;
+       background-color: #fff;
+     }
+
+== Rcss Syntax
+
+Rcss file is processed in three stages:
+
+1. The ERB template is applied
+2. Server-side constants are gathered 
+3. Server-side constants are evaluated
+4. Server-side classes are gathered 
+5. Server-side classes are evaluated
+
+=== Server-side Constants Syntax
+
+SSC block has following template:
+
+  @server constants {
+    constant_name: value;
+  }
+
+Also for compatibility older version is supported:
+
+  @server variables {
+    variable_name: value;
+  }
+
+There might be several constants/variables blocks in the same file. It does not 
+matter where in CSS file they appear, their contents are still applied to whole 
+file. 
+
+When a constant is redefined only later occurence is taken into account so:
+
+  template_color: #fff;
+  ...
+  template_color: #000;
+  
+...will result in <code>template_color</code> having value <code>#000</code> in all places.
+
+To use constant's value simply type it's name anywhere in the code:
+  
+  body {
+    color: constant_name;
+  }
+  
+*Note* that since enything can be constant's value it is also possible to use it
+to hold attribute or even selector:
+
+  @server constants {
+  	body: #fff;
+  }
+  
+  body {
+  	color: body;
+  }
+
+This will be evaluated to
+
+  #fff {
+    color: #fff;
+  }
+  
+..which probably is not what one might expect. For that reason avoid using CSS 
+selector and attribute names as constant names.
+
+=== Server-side Classes Syntax
+
+Server-side classes are defined using following template:
+
+  @server &class_name {
+  	// normal CSS content
+  }
+  
+The ampersand <code>&</code> before class name is mandatory.
+
+To include server-side class in CSS selector use *extends* attribute:
+
+  body {
+    extends: &class_name;
+  }
+  
+Server-side classes may also extend existing ones:
+
+  @server &highlighted {
+    background-color: #fec;
+    color: #fff;
+  }
+  
+  @server &header {
+    extends: &highlighted;
+    font-weight: bold;
+  }
+  
+  h1 {
+    extends: &header;
+  }
+  
+  #menu {
+    extends: &highlighted;
+  }
+  
+In case of complex extending order in which server-side classes appear in 
+the file is important. Class must be already declared before it is used - 
+otherwise it will be evaluated to an empty string.
+
+== Credits
+
+[<b>Shaun Inman</b>] For the original PHP version of CSS-SSC
+
+== License
+
+Rcss is available under an MIT-style license.
+
+:include: MIT-LICENSE
+
+== Other stuff
+
+Author:: Lukasz 'Bragi Ragnason' Piestrzeniewicz <bragi dot ragnarson at gmail dot com>
+Requires:: Ruby 1.8.0 or later
+           Rails 0.13.0 or later
+
+== Warranty
+
+This software is provided "as is" and without any express or
+implied warranties, including, without limitation, the implied
+warranties of merchantibility and fitness for a particular
+purpose.

data/Rakefile

@@ -0,0 +1,97 @@
+require 'rake'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require File.dirname(__FILE__) + '/lib/rcss'
+
+PKG_VERSION = Rcss::VERSION
+PKG_NAME = "rcss"
+RUBY_FORGE_PROJECT = "rcss"
+RUBY_FORGE_USER = "bragi"
+PKG_FILES = FileList[
+  'README',
+  'CHANGES',
+  'TODO',
+  'MIT-LICENSE',
+  'Rakefile',
+  'lib/**/*.rb',
+  'bin/**/*',
+  'test/**/*'
+]
+
+desc "Builds everything"
+task :default => [:test, :gem, :rdoc]
+
+task :gem => :test
+
+rd = Rake::RDocTask.new("rdoc") { |rdoc|
+  rdoc.rdoc_dir = 'html'
+  rdoc.title    = "Rcss - CSS Server-side Constants for Ruby/Rails"
+  rdoc.options << '--line-numbers' << '--inline-source' << '--main' << 'README'
+  rdoc.rdoc_files.include('README', 'MIT-LICENSE', 'TODO', 'CHANGES')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+}
+
+spec = Gem::Specification.new do |s|
+
+  #### Basic information.
+  s.name = PKG_NAME
+  s.version = PKG_VERSION
+  s.summary = "Rcss - CSS Server-side Constants for Ruby/Rails"
+  s.description = <<-TXT
+    No more search-and-replace in CSS files. Use your familiar ERB syntax (the
+    same you use in rhtml files) to deliver constants to CSS files. You can 
+    even extract values for constants from database using ActiveRecord.
+    
+    * Familiar ERB syntax
+    
+    * Extend your classes with multiple attributes with ease
+  TXT
+  s.files = PKG_FILES.to_a
+  s.executables << 'rcss'
+  
+  ## Load-time details
+  s.autorequire = 'rcss'
+  ## Author and project details
+  s.author = "Bragi Ragnarson"
+  s.email = "bragi.ragnarson@gmail.com"
+  s.rubyforge_project = RUBY_FORGE_PROJECT
+  s.homepage = "http://rcss.rubyforge.org"
+  
+  #### Documentation and testing.
+
+  s.has_rdoc = true
+  # s.extra_rdoc_files = rd.rdoc_files.reject { |fn| fn =~ /\.rb$/ }.to_a
+  s.rdoc_options <<
+    '--title' <<  'Rcss - CSS Server-side Constants for Ruby/Rails' <<
+    '--main' << 'README' <<
+    '--line-numbers'
+  s.extra_rdoc_files = rd.rdoc_files.reject { |fn| fn =~ /\.rb$/ }.to_a
+    
+end
+
+task :test do |t|
+  puts "Testing"
+  Dir[ 'test/data/*.in.rcss' ].each do |testfile|
+    testname = testfile.gsub(/test\/data\/(.*)\.in\.rcss/, '\1')
+    rcss = Rcss::Ssc.new(File.read(testfile)).to_css
+    css = File.read(testfile.gsub(/\.in\.rcss/ , ".out.css"))
+    rcss.gsub!(/^\s*\n/, "")
+    css.gsub!(/^\s*\n/, "")
+    if rcss == css
+      puts "Test \"#{testname}\" passed"
+    else
+      puts "Test \"#{testname}\" failed"
+      puts "--- RESULT ---"
+      puts rcss
+      puts "--- EXPECTED ---"
+      puts css
+      puts "---"
+      raise
+    end
+  end
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_zip = true
+  pkg.need_tar = true
+end

data/TODO

@@ -0,0 +1,8 @@
+= Rcss TODO list
+
+== Future development
+* Implement Server-side Templates
+* Generator for controller
+
+== Fixes
+* Modify Rakefile to support package task

data/bin/rcss

@@ -0,0 +1,7 @@
+begin
+  require 'rcss'
+rescue LoadError
+  require 'rubygems'
+  require_gem 'rcss'
+end
+puts Rcss::Ssc.new( ARGF.read ).to_css

data/lib/rcss.rb

@@ -0,0 +1,120 @@
+require 'erb'
+
+require 'rubygems'
+
+module Rcss #:nodoc:
+
+  VERSION = "0.3.0"
+
+  # Implements CSS-SSC in Ruby.
+  #
+  # Main features:
+  #
+  # * Create rich CSS files using:
+  #
+  #   * ERB templates
+  #
+  #   * Server-side constants
+  #
+  #   * Server-side classes (preliminary)
+  #
+  # * Simply add Rcss files to any Rails application
+  #
+  # * Process Rcss files off-line using command line executable
+  #
+  class Ssc < String
+  
+    @@SERVER_CONSTANTS = /@server\s+(?:variables|constants)\s*\{\s*([^\}]+)\s*\}\s*/m
+    
+    @@SERVER_CONSTANT = /([^:\s]+)\s*:\s*([^;]+)\s*;/m
+    
+    @@SERVER_CLASS = /@server\s+(\&\w?[-_\w\d]*)\s+\{([^\}]*)\}/m
+
+    @@EXTENDS_ATTRIBUTE = /extends\s*:\s*(\&\w?[-_\w\d]*);/m
+    
+    def initialize(string) # :nodoc:
+      super(string)      
+    end
+    
+    def parse(text, binding) # :nodoc:
+      classes = Hash.new
+      constants = Hash.new
+      
+      # Apply ERB as it has the highest priority
+      rcss = ERB.new(text, nil, '-').result(binding)
+      
+      # Apply SSC in two steps:
+      
+      # 1. Find and collect all server-side constants
+      rcss.gsub!(@@SERVER_CONSTANTS) do
+        $1.scan(@@SERVER_CONSTANT) do
+          constants[$1]=$2 
+        end
+        ""
+      end
+      
+      # 2. Substitute constants with values
+      rcss.gsub!(/[^:;\s]+/) do
+        constants[$&] or $&
+      end
+      
+      # Apply server-side classes
+      rcss.gsub!(@@SERVER_CLASS) do 
+        class_name = $1
+        body = $2
+        body.gsub!(@@EXTENDS_ATTRIBUTE) { classes[$1] }
+        classes[class_name] = body.strip
+        ""
+      end
+      rcss.gsub!(@@EXTENDS_ATTRIBUTE) { classes[$1] }
+      
+      rcss
+    end
+    
+    # Generates CSS from Rcss contents
+    #
+    # When binding is provided it is used to evaluate ERB template
+    #
+    #  template = <<-TXT
+    #    @server constants { my_color: #fff; }
+    #    body { color: my_color; }
+    #  TXT
+    #  rcss = Rcss::Ssc.new(template)
+    #  rcss.to_css
+    #    #=> "body { color: #fff; }
+    #
+    def to_css(binding=nil)
+      parse(self.dup, binding)
+    end
+
+    private :parse
+  end
+  
+  # Rails handler for Rcss files
+  class RcssHandler
+    include ERB::Util
+    
+    def initialize(action_view) #:nodoc:
+      @action_view = action_view
+    end
+    
+    # Renders given template using local_assigns for evaluation
+    #
+    # Modifies response headers:
+    #
+    #  Content-Type: text/css
+    #
+    def render(template, local_assigns)
+      @action_view.controller.headers["Content-Type"] = 'text/css'
+      b = binding
+  
+      local_assigns.stringify_keys!
+      local_assigns.each { |key, value| eval "#{key} = local_assigns[\"#{key}\"]", b }
+      Ssc.new(template).to_css(b)
+    end
+  end
+end
+
+if Object.const_defined? "ActionView"
+  ActionView::Base::register_template_handler 'rcss', Rcss::RcssHandler
+end

data/test/data/erb.in.rcss

@@ -0,0 +1,5 @@
+<% color = "#fff" %>
+body {
+	font-family: Tahoma, helvetica, sans-serif;	
+	color: <%= color %>;
+}

data/test/data/erb.out.css

@@ -0,0 +1,4 @@
+body {
+	font-family: Tahoma, helvetica, sans-serif;	
+	color: #fff;
+}

data/test/data/extend.in.rcss

@@ -0,0 +1,19 @@
+@server &trebuchet_font {
+    font-family: "Trebuchet MS", arial, helvetica, sans-serif;
+}
+
+@server &header {
+    extends: &trebuchet_font;
+    background-color: #fff;
+    color: #f00;
+}
+
+body {
+    extends: &trebuchet_font;
+    color: #000;
+}
+
+h1 {
+    extends: &header;
+    font-weight: bold;
+}

data/test/data/extend.out.css

@@ -0,0 +1,11 @@
+body {
+    font-family: "Trebuchet MS", arial, helvetica, sans-serif;
+    color: #000;
+}
+
+h1 {
+    font-family: "Trebuchet MS", arial, helvetica, sans-serif;
+    background-color: #fff;
+    color: #f00;
+    font-weight: bold;
+}

data/test/data/simple.in.rcss

@@ -0,0 +1,3 @@
+body {
+	font-family: Tahoma, helvetica, sans-serif;	
+}

data/test/data/simple.out.css

@@ -0,0 +1,3 @@
+body {
+	font-family: Tahoma, helvetica, sans-serif;	
+}

data/test/data/ssc-complex.in.rcss

@@ -0,0 +1,23 @@
+@server constants {
+	my_color : #fff;
+	common-font: Tahoma, helvetica, sans-serif;
+	common-font-fixed: Courier, fixed;
+}
+
+@server variables {
+	my_other_color : #f00;
+}
+
+body {
+	font-family: common-font;
+	color: my_color;
+	background-color: my_other_color;
+}
+
+pre {
+	font-family: common-font-fixed;
+}
+
+@server constants {	my_color : #0f0; common-font: helvetica; }
+
+h1 { color: my_color; font-family: common-font; }

data/test/data/ssc-complex.out.css

@@ -0,0 +1,11 @@
+body {
+	font-family: helvetica;
+	color: #0f0;
+	background-color: #f00;
+}
+
+pre {
+	font-family: Courier, fixed;
+}
+
+h1 { color: #0f0; font-family: helvetica; }

data/test/data/ssc-simple.in.rcss

@@ -0,0 +1,8 @@
+@server constants {
+	my_color : #fff;
+}
+
+body {
+	font-family: Tahoma, helvetica, sans-serif;	
+	color: my_color;
+}

data/test/data/ssc-simple.out.css

@@ -0,0 +1,4 @@
+body {
+	font-family: Tahoma, helvetica, sans-serif;	
+	color: #fff;
+}

metadata

@@ -0,0 +1,69 @@
+!ruby/object:Gem::Specification 
+rubygems_version: 0.8.11
+specification_version: 1
+name: rcss
+version: !ruby/object:Gem::Version 
+  version: 0.3.0
+date: 2005-10-18 00:00:00 +02:00
+summary: Rcss - CSS Server-side Constants for Ruby/Rails
+require_paths: 
+- lib
+email: bragi.ragnarson@gmail.com
+homepage: http://rcss.rubyforge.org
+rubyforge_project: rcss
+description: No more search-and-replace in CSS files. Use your familiar ERB syntax (the same you use in rhtml files) to deliver constants to CSS files. You can  even extract values for constants from database using ActiveRecord.  * Familiar ERB syntax  * Extend your classes with multiple attributes with ease
+autorequire: rcss
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+authors: 
+- Bragi Ragnarson
+files: 
+- README
+- CHANGES
+- TODO
+- MIT-LICENSE
+- Rakefile
+- lib/rcss.rb
+- bin/rcss
+- test/data
+- test/data/ssc-simple.in.rcss
+- test/data/ssc-complex.in.rcss
+- test/data/ssc-simple.out.css
+- test/data/ssc-complex.out.css
+- test/data/erb.in.rcss
+- test/data/erb.out.css
+- test/data/extend.in.rcss
+- test/data/extend.out.css
+- test/data/simple.in.rcss
+- test/data/simple.out.css
+test_files: []
+
+rdoc_options: 
+- --title
+- Rcss - CSS Server-side Constants for Ruby/Rails
+- --main
+- README
+- --line-numbers
+extra_rdoc_files: 
+- README
+- MIT-LICENSE
+- TODO
+- CHANGES
+executables: 
+- rcss
+extensions: []
+
+requirements: []
+
+dependencies: []
+