haml 1.8.0 → 2.0.3

data/lib/sass.rb

@@ -11,7 +11,7 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 # and implements various features that are useful
 # for creating manageable stylesheets.
 #
-# == Features 
+# == Features
 #
 # * Whitespace active
 # * Well-formatted output
@@ -20,9 +20,10 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 #
 # == Using Sass
 #
-# Sass can be used in several ways:
-# As a plugin for Ruby on Rails or Merb,
-# or as a standalone parser.
+# Sass can be used in three ways:
+# as a plugin for Ruby on Rails,
+# as a standalone Ruby module,
+# and as a command-line tool.
 # Sass is bundled with Haml,
 # so if the Haml plugin or RubyGem is installed,
 # Sass will already be installed as a plugin or gem, respectively.
@@ -32,17 +33,17 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 #
 # To enable it as a Rails plugin,
 # then run
-# 
+#
 #   haml --rails path/to/rails/app
-# 
+#
 # To enable Sass in Merb,
 # add
 #
-#   dependency "haml"
+#   dependency "merb-haml"
 #
 # to config/dependencies.rb.
 #
-# Sass templates in Rails and Merb don't quite function in the same way as views,
+# Sass templates in Rails don't quite function in the same way as views,
 # because they don't contain dynamic content,
 # and so only need to be compiled when the template file has been updated.
 # By default (see options, below),
@@ -50,6 +51,12 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 # Then, whenever necessary, they're compiled into corresponding CSS files in public/stylesheets.
 # For instance, public/stylesheets/sass/main.sass would be compiled to public/stylesheets/main.css.
 #
+# To run Sass from the commandline, just use
+#
+#   sass input.sass output.css
+#
+# Use <tt>sass --help</tt> for full documentation.
+# 
 # Using Sass in Ruby code is very simple.
 # After installing the Haml gem,
 # you can use it by running <tt>require "sass"</tt>
@@ -128,7 +135,7 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 #
 # By default, either attribute syntax may be used.
 # If you want to force one or the other,
-# see the :attribute_syntax option below.
+# see the <tt>:attribute_syntax</tt> option below.
 #
 # === Nested Rules
 #
@@ -157,12 +164,12 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 #
 #   #main
 #     :width 97%
-#     
+#
 #     p, div
 #       :font-size 2em
 #       a
 #         :font-weight bold
-#         
+#
 #     pre
 #       :font-size 3em
 #
@@ -253,6 +260,22 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 #     font-size: 30em;
 #     font-weight: bold; }
 #
+# === Rule Escaping
+#
+# In case, for whatever reason, you need to write a rule
+# that begins with a Sass-meaningful character,
+# you can escape it with a backslash (<tt>\</tt>).
+# For example:
+#
+#  #main
+#    \+div
+#      clear: both
+#
+# is compiled to:
+#
+#  #main +div {
+#    clear: both; }
+#
 # == Constants
 #
 # Sass has support for setting document-wide constants.
@@ -363,6 +386,39 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 #   #main {
 #     content: string(Hello, "Hubert" Bean.) }
 #
+# === Optional Assignment
+#
+# You can assign Sass constants if they aren't already assigned
+# using the ||= assignment operator.
+# This means that if the constant has already been assigned to,
+# it won't be re-assigned,
+# but if it doesn't have a value yet,
+# it will be given one.
+# For example:
+#
+#   !content = "First content"
+#   !content ||= "Second content?"
+#
+#   #main
+#     content = content
+#
+# is compiled to:
+#
+#   #main {
+#     content: First content; }
+#
+# However,
+#
+#   !content ||= "Second content?"
+#
+#   #main
+#     content = content
+#
+# is compiled to:
+#
+#   #main {
+#     content: Second content?; }
+#
 # === Default Concatenation
 #
 # All those plusses and quotes for concatenating strings
@@ -453,6 +509,40 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 # might compile to either,
 # depending on whether a file called "foo.sass" existed.
 #
+# === @font-face, @media, etc.
+#
+# Sass behaves as you'd expect for normal CSS @-directives.
+# For example:
+#
+#   @font-face
+#     font-family: "Bitstream Vera Sans"
+#     src: url(http://foo.bar/bvs")
+#
+# compiles to:
+#
+#   @font-face {
+#     font-family: "Bitstream Vera Sans";
+#     src: url(http://foo.bar/bvs"); }
+#
+# and
+#
+#   @media print
+#     #sidebar
+#       display: none
+#
+#     #main
+#       background-color: white
+#
+# compiles to:
+#
+#   @media print {
+#     #sidebar {
+#       display: none; }
+#
+#     #main {
+#       background-color: white; }
+#   }
+#
 # == Comments
 #
 # === Silent Comments
@@ -528,6 +618,84 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 #     background-image: url(/images/pbj.png);
 #     color: red; }
 #
+# == Mixins
+#
+# Mixins enable you to define groups of CSS attributes and
+# then include them inline in any number of selectors
+# throughout the document.
+#
+# === Defining a Mixin
+#
+# To define a mixin you use a slightly modified form of selector syntax.
+# For example the 'large-text' mixin is defined as follows:
+#
+#   =large-text
+#     :font
+#       :family Arial
+#       :size 20px
+#       :weight bold
+#     :color #ff0000
+#
+# The initial '=' marks this as a mixin rather than a standard selector.
+# The CSS rules that follow won't be included until the mixin is referenced later on.
+# Anything you can put into a standard selector,
+# you can put into a mixin definition. e.g.
+#
+#   =clearfix
+#     display: inline-block
+#     &:after
+#       content: "."
+#       display: block
+#       height: 0
+#       clear: both
+#       visibility: hidden
+#     * html &
+#       height: 1px
+#
+#
+# === Mixing it in
+#
+# Inlining a defined mixin is simple,
+# just prepend a '+' symbol to the name of a mixin defined earlier in the document.
+# So to inline the 'large-text' defined earlier,
+# we include the statment '+large-text' in our selector definition thus:
+#
+#   .page-title
+#     +large-text
+#     :padding 4px
+#     :margin
+#       :top 10px
+#
+#
+# This will produce the following CSS output:
+#
+#   .page-title {
+#     font-family: Arial;
+#     font-size: 20px;
+#     font-weight: bold;
+#     color: #ff0000;
+#     padding: 4px;
+#     margin-top: 10px;
+#   }
+#
+# Any number of mixins may be defined and there is no limit on
+# the number that can be included in a particular selector.
+#
+# Mixin definitions can also include references to other mixins defined earlier in the file.
+# E.g.
+#
+#   =highlighted-background
+#     background:
+#       color: #fc0
+#   =header-text
+#     font:
+#       size: 20px
+#
+#   =compound
+#     +highlighted-background
+#     +header-text
+#
+#
 # == Output Style
 #
 # Although the default CSS style that Sass outputs is very nice,
@@ -601,7 +769,7 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 #   #main { color: #fff; background-color: #000; }
 #   #main p { width: 10em; }
 #
-#   .huge { font-size: 10em; font-weight: bold; text-decoration: underline; } 
+#   .huge { font-size: 10em; font-weight: bold; text-decoration: underline; }
 #
 # === <tt>:compressed</tt>
 #
@@ -611,13 +779,20 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 # It's not meant to be human-readable.
 # For example:
 #
-#   #main{color:#fff;background-color:#000}#main p{width:10em}.huge{font-size:10em;font-weight:bold;text-decoration:underline} 
+#   #main{color:#fff;background-color:#000}#main p{width:10em}.huge{font-size:10em;font-weight:bold;text-decoration:underline}
 #
 # == Sass Options
 #
-# Options can be set by setting the hash <tt>Sass::Plugin.options</tt>
-# from <tt>environment.rb</tt> in Rails,
-# or by passing an options hash to Sass::Engine.
+# Options can be set by setting the <tt>Sass::Plugin.options</tt> hash
+# in <tt>environment.rb</tt> in Rails...
+#
+#   Sass::Plugin.options[:style] = :compact
+#
+# ...or by setting the <tt>Merb::Config[:sass]</tt> hash in <tt>init.rb</tt> in Merb...
+#
+#   Merb::Config[:sass][:style] = :compact
+# 
+# ...or by passing an options hash to Sass::Engine.new.
 # Available options are:
 #
 # [<tt>:style</tt>]             Sets the style of the CSS output.
@@ -634,7 +809,7 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 #                               For example: <tt>color: #0f3</tt>
 #                               or <tt>width = !main_width</tt>.
 #                               By default, either syntax is valid.
-#                               
+#
 # [<tt>:never_update</tt>]      Whether the CSS files should never be updated,
 #                               even if the template file changes.
 #                               Setting this to true may give small performance gains.
@@ -646,7 +821,7 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 #                               as opposed to only when the template has been modified.
 #                               Defaults to false.
 #                               Only has meaning within Ruby on Rails or Merb.
-#                               
+#
 # [<tt>:always_check</tt>]      Whether a Sass template should be checked for updates every
 #                               time a controller is accessed,
 #                               as opposed to only when the Rails server starts.
@@ -681,7 +856,7 @@ $LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
 #                               for Sass templates imported with the "@import" directive.
 #                               This defaults to the working directory and, in Rails or Merb,
 #                               whatever <tt>:template_location</tt> is.
-# 
+#
 module Sass; end
 
 require 'sass/engine'

data/rails/init.rb

@@ -0,0 +1 @@
+Kernel.load File.join(File.dirname(__FILE__), '..', 'init.rb')

data/test/benchmark.rb

@@ -1,95 +1,82 @@
-# There's a bizarre error where ActionController tries to load a benchmark file
-# and ends up finding this.
-# These declarations then cause it to break.
-# This only happens when running rcov, though, so we can avoid it.
-unless $0 =~ /rcov$/
-  require File.dirname(__FILE__) + '/../lib/haml'
-  require 'haml'
+#!/usr/bin/env ruby
+
+times = (ARGV.first || 1000).to_i
+
+if times == 0 # Invalid parameter
+  puts <<END
+ruby #$0 [times=1000]
+  Benchmark Haml against various other templating languages and Sass
+  on its own.
+END
+  exit 1
+end
+
+require File.dirname(__FILE__) + '/../lib/haml'
+%w[sass rubygems erb erubis markaby active_support action_controller
+   action_view haml/template].each(&method(:require))
+
+begin
+  require 'benchwarmer'
+rescue LoadError
+  # Since it's not as simple as gem install at the time of writing,
+  # we need to direct folks to the benchwarmer gem.
+  raise "The Haml benchmarks require the benchwarmer gem, available from http://github.com/wycats/benchwarmer"
 end
 
-require 'rubygems'
-require 'erb'
-require 'erubis'
-require 'markaby'
-require 'benchmark'
-require 'stringio'
-require 'open-uri'
-
-module Haml
-  # Benchmarks Haml against ERB, Erubis, and Markaby and Sass on its own.
-  def self.benchmark(runs = 100)
-    template_name = 'standard'
-    directory = File.dirname(__FILE__) + '/haml'
-    haml_template =    File.read("#{directory}/templates/#{template_name}.haml")
-    erb_template =   File.read("#{directory}/rhtml/#{template_name}.rhtml")
-    markaby_template = File.read("#{directory}/markaby/#{template_name}.mab")
-
-    puts '-'*51, "Haml and Friends: No Caching", '-'*51
-
-    times = Benchmark.bmbm do |b|
-      b.report("haml:")   { runs.times { Haml::Engine.new(haml_template).render } }
-      b.report("erb:")    { runs.times { ERB.new(erb_template, nil, '-').render } }
-      b.report("erubis:") { runs.times { Erubis::Eruby.new(erb_template).result } }
-      b.report("mab:")    { runs.times { Markaby::Template.new(markaby_template).render } }
-    end
-
-    print_result = proc do |s, n|
-      printf "%1$*2$s %3$*4$g",
-        "Haml/#{s}:", -13, times[0].to_a[5] / times[n].to_a[5], -17
-      printf "%1$*2$s %3$g\n",
-        "#{s}/Haml:", -13, times[n].to_a[5] / times[0].to_a[5]
-    end
-    
-    print_result["ERB", 1]
-    print_result["Erubis", 2]
-    print_result["Markaby", 3]
-
-    puts '', '-' * 50, 'Haml and Friends: Cached', '-' * 50
+Benchmark.warmer(times) do
+  columns :haml, :erb, :erubis, :mab
+  titles :haml => "Haml", :erb => "ERB", :erubis => "Erubis", :mab => "Markaby"
 
+  template_name = 'standard'
+  directory = File.dirname(__FILE__) + '/haml'
+  haml_template    = File.read("#{directory}/templates/#{template_name}.haml")
+  erb_template     = File.read("#{directory}/rhtml/#{template_name}.rhtml")
+  markaby_template = File.read("#{directory}/markaby/#{template_name}.mab")
+
+  report "Uncached" do
+    haml   { Haml::Engine.new(haml_template).render }
+    erb    { ERB.new(erb_template, nil, '-').result }
+    erubis { Erubis::Eruby.new(erb_template).result }
+    mab    { Markaby::Template.new(markaby_template).render }
+  end
+
+  report "Cached" do
     obj = Object.new
+
     Haml::Engine.new(haml_template).def_method(obj, :haml)
-    erb = ERB.new(erb_template, nil, '-')
-    obj.instance_eval("def erb; #{erb.src}; end")
     Erubis::Eruby.new(erb_template).def_method(obj, :erubis)
-    times = Benchmark.bmbm do |b|
-      b.report("haml:")   { runs.times { obj.haml      } }
-      b.report("erb:")    { runs.times { obj.erb       } }
-      b.report("erubis:") { runs.times { obj.erubis    } }
-    end    
+    obj.instance_eval("def erb; #{ERB.new(erb_template, nil, '-').src}; end")
 
-    print_result["ERB", 1]
-    print_result["Erubis", 2]
-
-    puts '', '-' * 50, 'Haml and ERB: Via ActionView', '-' * 50
-
-    require 'active_support'
-    require 'action_controller'
-    require 'action_view'
-    require 'haml/template'
+    haml   { obj.haml }
+    erb    { obj.erb }
+    erubis { obj.erubis }
+  end
 
+  report "ActionView" do
     @base = ActionView::Base.new(File.dirname(__FILE__))
-    times = Benchmark.bmbm do |b|
-      b.report("haml:") { runs.times { @base.render 'haml/templates/standard' } }
-      b.report("erb:")  { runs.times { @base.render 'haml/rhtml/standard'     } }
-    end
 
-    print_result["ERB", 1]
+    # To cache the template
+    @base.render 'haml/templates/standard'
+    @base.render 'haml/rhtml/standard'
 
-    puts '', '-' * 50, 'Haml and ERB: Via ActionView with deep partials', '-' * 50
+    haml { @base.render 'haml/templates/standard' }
+    erb  { @base.render 'haml/rhtml/standard' }
+  end
 
+  report "ActionView with deep partials" do
     @base = ActionView::Base.new(File.dirname(__FILE__))
-    times = Benchmark.bmbm do |b|
-      b.report("haml:") { runs.times { @base.render 'haml/templates/action_view' } }
-      b.report("erb:")  { runs.times { @base.render 'haml/rhtml/action_view'     } }
-    end
-
-    print_result["ERB", 1]
-    
-    puts '', '-' * 50, 'Sass', '-' * 50
-    sass_template = File.read("#{File.dirname(__FILE__)}/sass/templates/complex.sass")
-    
-    Benchmark.bmbm do |b|
-      b.report("sass:") { runs.times { Sass::Engine.new(sass_template).render } }
-    end
+
+    # To cache the template
+    @base.render 'haml/templates/action_view'
+    @base.render 'haml/rhtml/action_view'
+
+    haml { @base.render 'haml/templates/action_view' }
+    erb  { @base.render 'haml/rhtml/action_view' }
   end
 end
+
+Benchmark.warmer(times) do
+  sass_template = File.read("#{File.dirname(__FILE__)}/sass/templates/complex.sass")
+
+  report("Sass") { Sass::Engine.new(sass_template).render }
+end