cascading_rubies 0.2.2

data/README.rdoc

@@ -0,0 +1,137 @@
+= Cascading Rubies
+
+Ruby DSL for generating CSS.
+
+I wrote this small DSL because I like the concept of Sass -- just not
+all the nuances of the syntax. I wondered how closely a Ruby DSL itself could
+resemble final CSS output. This is the fruit of my experimentation.
+
+I originally was going to call this RCSS, but that name is already taken.
+
+Please note: This is very early beta, and the syntax may change. Also, this is
+my very first DSL, and could very well be the biggest kludge you have ever seen.
+But it works, and there's good test coverage, so hey.
+
+== Syntax
+
+    header {
+      background_color '#eee'
+      margin_bottom '10px'
+      nav {
+        border '1px solid #000'
+        a(:link, :active, :visited) { color 'blue' }
+        a(:hover) { color 'red' }
+      }
+      div.search {
+        float 'right'
+      }
+    }
+    
+Output:
+
+    #header { background-color: #eee; margin-bottom: 10px; }
+    #header #nav { border: 1px solid #000; }
+    #header #nav a:link, #header #nav a:active, #header #nav a:visited { color: blue; }
+    #header #nav a:hover { color: red; }
+    #header div.search { float: right; }
+    
+Since the syntax is just Ruby, you can add comments, variables, and do just about anything
+you can in plain Ruby.
+
+=== Tags/IDs
+
+Tags are determined from the array #CascadingRubies::TAGS. If the name is present there, it is
+assumed to be a tag -- otherwise the name is output as a selector <tt>#id</tt>.
+
+=== Classes
+
+A leading underscore is used to denote a class selector, e.g. <tt>_search { }</tt> becomes
+<tt>.search { }</tt> -- or you can put a tag in front of it like so: <tt>div.search { }</tt>.
+
+=== Comma-Separated Selectors
+
+To output a comma-separated list of selectors, chain selectors together with semicolons
+or newlines, like so: <tt>li; a { }</tt>.
+
+=== Examples
+
+See files in example directory for more help.
+
+== Installation
+
+    sudo gem install cascading_rubies -s http://gemcutter.org
+    
+== Usage
+
+The gem includes a binary called +rcss+. Run it without args for usage details.
+Here are some examples:
+
+    rcss base.rcss nav.rcss           # print both rendered css files to screen
+    rcss -w base.rcss nav.rcss        # write rendered base.css and nav.css
+    rcss base.rcss nav.rcss > all.css # write to single file
+    rcss -w stylesheets               # render all .rcss files in directory
+    
+To use the library from within your own code:
+
+    require 'rubygems'
+    require 'cascading_rubies'
+    
+    css = CascadingRubies.open(path_to_file)
+    # or...
+    css = CascadingRubies.new do
+      # css here
+    end
+    
+    rendered = css.to_s
+
+== Shortcomings
+
+There are lots, no doubt. Here are few I thought up just now:
+
+* CascadingRubies#s is the method that builds selectors, so you can't specify an id #s directly
+  in the DSL. Do this instead: <tt>s('#s') { ... }</tt>
+* And there are a couple other names you can't use as ids (unless you use +s+):
+  * to\_s
+  * instance\_eval
+  * class
+  * inspect
+  * (others?)
+* You can't build a selector like div#links without using the raw selector method:
+  <tt>s('div#links') { ... }</tt>
+
+== Feedback
+
+I'd love to hear from you if you have suggestions for improvement, bug fixes,
+or whatever. Email me at tim@timmorgan.org or fork the project and send a
+pull request.
+
+To run the tests, do this:
+    ruby test/test_cascading_rubies.rb
+
+The library has been tested with Ruby 1.8.6, Ruby 1.8.7 and Ruby 1.9.1p0.
+If you find problems with your Ruby of choice, please let me know.
+
+== License
+
+The MIT License
+
+Copyright (c) 2009 Tim Morgan
+
+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/bin/rcss

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+
+$: << File.expand_path(File.dirname(__FILE__) + '/../lib')
+require 'rubygems'
+require 'cascading_rubies'
+
+WRITE_OUT = ARGV.delete('-w') || ARGV.delete('--write')
+
+def handle(path)
+  css = CascadingRubies.open(path)
+  if WRITE_OUT
+    File.open(path.sub(/\.[^\.]+$/, '.css'), 'w') { |f| f.write(css) }
+  else
+    puts css
+  end
+end
+
+ARGV.each do |path|
+  if File.directory?(path)
+    Dir[path + '/*.rcss'].each { |p| handle(p) }
+  elsif File.exist?(path)
+    handle(path)
+  else
+    puts "File or path not found: #{path}"
+    exit(1)
+  end
+end
+
+unless ARGV.any?
+  puts 'Builds CSS from Ruby -- see http://github.com/seven1m/cascading_rubies'
+  puts 'Usage: rcss [-w] path1 [path2 [...]]'
+  puts 'path can be one or more files or a directory of .rcss files'
+  puts
+  puts 'Options:'
+  puts '  -w   --write             write .css file(s) at same path'
+  puts
+end

data/example/block_example_1.rcss

@@ -0,0 +1,7 @@
+# Wrap the code in a block like this, calling the "css" method.
+# This and the other block example should easily allow code outside the block
+# to reference Kernel level methods, require additional code, etc.
+
+css do
+  nav { color :red }
+end

data/example/block_example_2.rcss

@@ -0,0 +1,7 @@
+# Wrap the code in a block like this, calling the "CascadingRubies.css" class method.
+# This and the other block example should easily allow code outside the block
+# to reference Kernel level methods, require additional code, etc.
+
+CascadingRubies.css do
+  nav { color :red }
+end

data/example/example.rcss

@@ -0,0 +1,39 @@
+# To see output: ruby bin/rcss example/example.rcss
+
+require 'rubygems'; require 'sass'; Color = Sass::Constant::Color
+
+bg_color = Color.parse('#eee')
+footer_bg_color = bg_color.minus(Color.parse('#222'))
+
+CascadingRubies.css do
+
+  header {
+    border '1px solid black'
+    background_color bg_color
+    padding '10px'
+    _search {
+      float :right
+      margin_right '20px'
+      a { text_decoration 'none' }
+    }
+    nav do |n|
+      n.margin '10px'
+    end
+  }
+
+  s('body>#content') {
+    margin '10px'
+  }
+
+  div.bordered {
+    border '1px solid #ccc'
+  }
+
+  a(:visited) { color 'purple' }
+  a(:link, :active) { color 'blue' }
+
+  footer {
+    background_color footer_bg_color
+  }
+  
+end

data/example/no_block_example.rcss

@@ -0,0 +1,6 @@
+# Code in an rcss file does not strictly have to be wrapped in a block.
+# Unlike the two block examples, the entire file is run through instance_eval,
+# which makes using external libraries and other code a bit more difficult,
+# but allows for a super clean file.
+
+nav { color :red }

data/lib/blankslate.rb

@@ -0,0 +1,113 @@
+#!/usr/bin/env ruby
+#--
+# Copyright 2004, 2006 by Jim Weirich (jim@weirichhouse.org).
+# All rights reserved.
+
+# Permission is granted for use, copying, modification, distribution,
+# and distribution of modified versions of this work as long as the
+# above copyright notice is included.
+#++
+
+######################################################################
+# BlankSlate provides an abstract base class with no predefined
+# methods (except for <tt>\_\_send__</tt> and <tt>\_\_id__</tt>).
+# BlankSlate is useful as a base class when writing classes that
+# depend upon <tt>method_missing</tt> (e.g. dynamic proxies).
+#
+class BlankSlate #:nodoc:
+  class << self
+    
+    # Hide the method named +name+ in the BlankSlate class.  Don't
+    # hide +instance_eval+ or any method beginning with "__".
+    def hide(name)
+      if instance_methods.include?(name.to_s) and
+        name !~ /^(__|instance_eval)/
+        @hidden_methods ||= {}
+        @hidden_methods[name.to_sym] = instance_method(name)
+        undef_method name
+      end
+    end
+
+    def find_hidden_method(name)
+      @hidden_methods ||= {}
+      @hidden_methods[name] || superclass.find_hidden_method(name)
+    end
+
+    # Redefine a previously hidden method so that it may be called on a blank
+    # slate object.
+    def reveal(name)
+      bound_method = nil
+      unbound_method = find_hidden_method(name)
+      fail "Don't know how to reveal method '#{name}'" unless unbound_method
+      define_method(name) do |*args|
+        bound_method ||= unbound_method.bind(self)
+        bound_method.call(*args)
+      end
+    end
+  end
+  
+  instance_methods.each { |m| hide(m) }
+end
+
+######################################################################
+# Since Ruby is very dynamic, methods added to the ancestors of
+# BlankSlate <em>after BlankSlate is defined</em> will show up in the
+# list of available BlankSlate methods.  We handle this by defining a
+# hook in the Object and Kernel classes that will hide any method
+# defined after BlankSlate has been loaded.
+#
+module Kernel
+  class << self
+    alias_method :blank_slate_method_added, :method_added
+
+    # Detect method additions to Kernel and remove them in the
+    # BlankSlate class.
+    def method_added(name)
+      result = blank_slate_method_added(name)
+      return result if self != Kernel
+      BlankSlate.hide(name)
+      result
+    end
+  end
+end
+
+######################################################################
+# Same as above, except in Object.
+#
+class Object
+  class << self
+    alias_method :blank_slate_method_added, :method_added
+
+    # Detect method additions to Object and remove them in the
+    # BlankSlate class.
+    def method_added(name)
+      result = blank_slate_method_added(name)
+      return result if self != Object
+      BlankSlate.hide(name)
+      result
+    end
+
+    def find_hidden_method(name)
+      nil
+    end
+  end
+end
+
+######################################################################
+# Also, modules included into Object need to be scanned and have their
+# instance methods removed from blank slate.  In theory, modules
+# included into Kernel would have to be removed as well, but a
+# "feature" of Ruby prevents late includes into modules from being
+# exposed in the first place.
+#
+class Module
+  alias blankslate_original_append_features append_features
+  def append_features(mod)
+    result = blankslate_original_append_features(mod)
+    return result if mod != Object
+    instance_methods.each do |name|
+      BlankSlate.hide(name)
+    end
+    result
+  end
+end

data/lib/cascading_rubies.rb

@@ -0,0 +1,144 @@
+# Ruby DSL for generating CSS.
+# Copyright (c) 2009 Tim Morgan
+
+require File.dirname(__FILE__) + '/blankslate'
+
+class CascadingRubies < BlankSlate #:doc:
+
+  [:class, :respond_to?, :inspect].each { |m| reveal(m) rescue nil }
+  undef_method(:p)
+  
+  # List of tags taken from http://www.w3schools.com/tags/default.asp
+  TAGS = %w(a abbr acronym address applet area b base basefont bdo big blockquote body br button caption center cite code col colgroup dd del dir div dfn dl dt em fieldset font form frame frameset h1 h2 h3 h4 h5 h6 head hr html i iframe img input ins isindex kbd label legend li link map meta noframes noscript object ol optgroup option p param pre q samp script select small span strike strong style sub sup table tbody td textarea tfoot th thead title tr tt u ul var xmp)
+
+  attr_reader :__selectors, :__css, :__context_name, :__has_children #:nodoc:
+
+  # Creates a CascadingRubies object. Normally, you should not pass in any arguments,
+  # except a block of style definitions. The block can optionally take a single argument --
+  # if so, the newly created object is yielded to the block, and instance_eval is not used.
+  # 
+  # Each block in the style definitions is effectively going to trigger a new object to
+  # be created, so the block argument is optional <em>for each block</em>, and the determination to
+  # use instance_eval is subsequently <em>per block</em>:
+  #     CascadingRubies.new do |css|
+  #       css.header do |header|
+  #         header.background_color '#ccc'
+  #       end
+  #       css.p {
+  #         margin_bottom '15px'
+  #       }
+  #     end
+  #
+  # If you do not pass a block (or even if you do), you can execute additional style definitions
+  # by either calling methods directly on the object:
+  #     obj = CascadingRubies.new
+  #     obj.nav { margin '10px'; a { color :red } }
+  # or you can instance_eval another block of code:
+  #     obj.instance_eval do
+  #       p { margin_bottom '15px' }
+  #     end
+  def initialize(context_name=nil, selectors=[], classed=false, &dsl_code)
+    @__context_name = context_name
+    @__css = ''
+    @__selectors = selectors
+    @__classed = classed # if true, method_missing calls are css class selectors -- not id selectors
+    if dsl_code.nil?
+      # do nothing
+    elsif dsl_code.arity == 1
+      dsl_code[self]
+    else
+      instance_eval(&dsl_code)
+    end
+  end
+  
+  # Create a new style "selector" without going through method_missing.
+  # Use this to create style definitions that cannot be created with the DSL directly, e.g.
+  # * <tt>s('##s') { color :blue }</tt> => <tt>##s { color: blue; }</tt>
+  # * <tt>s('div##search') { margin 0 }</tt> => <tt>div##search { margin: 0; }</tt>
+  def s(selector, *args, &dsl_code)
+    if args.any? and dsl_code.nil? # css rule
+      @__css << "#{selector}: #{args.join(' ')}; "
+    else
+      if args.any? and dsl_code # pseudo-class selector
+        selector_name = args.map do |arg|
+          [[@__context_name, selector].compact.join(' '), ':' + arg.to_s].join('')
+        end.join(', ')
+      else # regular selector
+        selector_name = [@__context_name, selector].compact.join(@__classed ? '' : ' ')
+      end
+      if @__bare and not @__bare.__has_children # e.g. li; a { }
+        selector_name = "#{@__bare.__context_name}, #{selector_name}"
+      end
+      if dsl_code
+        compiled = self.class.new(selector_name, &dsl_code)
+        @__selectors << "#{selector_name} { #{compiled.__css}}" unless compiled.__css.empty?
+        @__selectors += compiled.__selectors
+        @__bare = nil
+      else # e.g. div.something
+        @__bare = self.class.new(selector_name, @__selectors, true, &dsl_code)
+      end
+    end
+  end
+  
+  def method_missing(method_name, *args, &dsl_code) #:nodoc:
+    @__has_children = true
+    selector = dsl_code ? __method_name_to_selector(method_name) : __dashify(method_name)
+    s(selector, *args, &dsl_code)
+  end
+
+  # Returns the complete CSS style definitions as a string.
+  def to_s
+    @__selectors.join("\n")
+  end
+  
+  # Creates a CascadingRubies object, then opens the file and executes the style
+  # definitions in the context of the object. Returns the newly created object.
+  def self.open(path)
+    if (code = File.read(path)) =~ /^css do|CascadingRubies\.css do/
+      eval(code)
+    else
+      css(code)
+    end
+    @obj
+  end
+  
+  # Wraps the creation of a CascadingRubies object and doing the instance_eval execution
+  # in a neat package for use inside rcss files. An rcss file can use the optional block
+  # syntax to wrap style definitions, allowing code to be run outside the instance_eval
+  # confines. Use this method in an .rcss file like so:
+  #     css do
+  #       a { color :red }
+  #     end
+  # or:
+  #     CascadingRubies.css do
+  #       a { color :red }
+  #     end
+  def self.css(code=nil, &block)
+    @obj = self.new
+    if code
+      @obj.instance_eval(code)
+    else
+      @obj.instance_eval(&block)
+    end
+  end
+  
+  private
+  
+    def __method_name_to_selector(method_name)
+      selector = method_name.to_s
+      if selector.sub!(/^_/, '.')
+        __dashify(selector)
+      elsif TAGS.include?(selector)
+        __dashify(selector)
+      elsif @__classed
+        '.' + __dashify(selector)
+      else
+        '#' + __dashify(selector)
+      end
+    end
+    
+    def __dashify(name)
+      name.to_s.gsub(/_/, '-').downcase
+    end
+
+end

data/test/test_cascading_rubies.rb

@@ -0,0 +1,138 @@
+$: << File.expand_path(File.dirname(__FILE__) + '/../lib')
+
+require 'cascading_rubies'
+require 'test/unit'
+
+class TestCascadingRubies < Test::Unit::TestCase
+  
+  # selectors
+
+  def test_id_selector
+    assert_produces "#nav { color: red; }", "nav { color :red }"
+  end
+  
+  def test_class_selector
+    assert_produces ".links { color: red; }", "_links { color :red }"
+  end
+  
+  def test_class_selector_with_tag
+    assert_produces "div.links { color: red; }", "div.links { color :red }"
+  end
+  
+  def test_tag_selector
+    assert_produces "div { color: red; }", "div { color :red }"
+  end
+  
+  def test_raw_selector
+    assert_produces "body>#content { color: red; }", "s('body>#content') { color :red }"
+    assert_produces "#s { color: red; }", "s('#s') { color :red }"
+  end
+  
+  def test_pseudo_class_selector
+    assert_produces "a:link { color: red; }", "a(:link) { color :red }"
+    assert_produces "a:hover, a:active { color: red; }", "a(:hover, :active) { color :red }"
+  end
+  
+  def test_multiple_comma_separated_selectors
+    assert_produces "#nav li, #nav a { color: red; }", "nav { li; a { color :red } }" # double
+    assert_produces "#nav li, #nav div, #nav a { color: red; }", "nav { li; div; a { color :red } }" # triple
+    output = <<-CSS
+      #nav li, #nav a:link, #nav a:visited { color: red; }
+      #nav a { color: green; }
+    CSS
+    code = <<-CSS
+      nav {
+        li; a(:link, :visited) {
+          color :red
+        }
+        a {
+          color :green
+        }
+      }
+    CSS
+    assert_produces output.gsub(/^\s+/, '').chomp, code # following selector isn't affected
+  end
+  
+  def test_empty_selectors_not_printed
+    assert_produces "#nav li { color: red; }", "nav { li { color :red } }"
+  end
+  
+  # nesting
+  
+  def test_nested_selectors
+    output = <<-CSS
+      #header { color: red; }
+      #header #nav { color: blue; }
+      #header #nav a { color: green; }
+    CSS
+    code = <<-CSS
+      header {
+        color :red
+        nav {
+          color :blue
+          a {
+            color :green
+          }
+        }
+      }
+    CSS
+    assert_produces output.gsub(/^\s+/, '').chomp, code
+  end
+  
+  def test_nested_pseudo_class_selector
+    output = <<-CSS
+      #header { color: red; }
+      #header a:link { color: blue; }
+    CSS
+    code = <<-CSS
+      header {
+        color :red
+        a(:link) {
+          color :blue
+        }
+      }
+    CSS
+    assert_produces output.gsub(/^\s+/, '').chomp, code
+  end
+  
+  # rules
+  
+  def test_underscores_replaced_with_dashes
+    assert_produces "a { text-decoration: none; }", "a { text_decoration 'none' }"
+  end
+  
+  def test_symbols_as_values
+    assert_produces "a { text-decoration: none; }", "a { text_decoration :none }"
+  end
+  
+  # misc
+  
+  def test_use_p_tag
+    assert_produces "p { color: red; }", "p { color :red }"
+  end
+  
+  def test_puts
+    assert_produces "a { color: red; }", "a { color :red }"
+    assert_nothing_raised do
+      puts @css
+    end
+  end
+  
+  def test_examples
+    Dir[File.dirname(__FILE__) + '/../example/*.rcss'].each do |path|
+      assert_nothing_raised do
+        @css = CascadingRubies.open(path)
+      end
+      assert @css.to_s != ''
+    end
+  end
+  
+  private
+    
+    def assert_produces(output, code)
+      @css = CascadingRubies.new
+      @css.instance_eval(code)
+      assert_equal output, @css.to_s
+    end
+
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification 
+name: cascading_rubies
+version: !ruby/object:Gem::Version 
+  version: 0.2.2
+platform: ruby
+authors: 
+- Tim Morgan
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-10-21 00:00:00 -05:00
+default_executable: 
+dependencies: []
+
+description: 
+email: tim@timmorgan.org
+executables: 
+- rcss
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.rdoc
+- lib/cascading_rubies.rb
+- lib/blankslate.rb
+- bin/rcss
+- test/test_cascading_rubies.rb
+- example/example.rcss
+- example/block_example_1.rcss
+- example/block_example_2.rcss
+- example/no_block_example.rcss
+has_rdoc: true
+homepage: http://github.com/seven1m/cascading_rubies
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+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: Ruby DSL for generating CSS.
+test_files: []
+