jwhitmire-haml 2.1.0.1

data/README.rdoc

@@ -0,0 +1,332 @@
+= Haml and Sass
+
+Haml and Sass are templating engines
+for the two most common types of documents on the web:
+HTML and CSS, respectively.
+They are designed to make it both easier and more pleasant
+to code HTML and CSS documents,
+by eliminating redundancy,
+reflecting the underlying structure that the document represents,
+and providing elegant, easily understandable, and powerful syntax.
+
+== Using
+
+There are several ways to use Haml and Sass.
+They can be used as a plugin for Rails or Merb,
+or embedded on their own in other applications.
+The first step of all of these is to install the Haml gem:
+
+  gem install haml
+
+To install Haml and Sass as a Rails plugin,
+just run <tt>haml --rails path/to/rails/app</tt>
+and both Haml and Sass will be installed.
+Views with the <tt>.haml</tt> (or <tt>.html.haml</tt> for edge)
+extension will automatically use Haml.
+Sass is a little more complicated;
+<tt>.sass</tt> files should be placed in public/stylesheets/sass,
+where they'll be automatically compiled
+to corresponding CSS files in public/stylesheets when needed
+(the Sass template directory is customizable...
+see the Sass module docs for details).
+
+For Merb, <tt>.html.haml</tt> views will work without any further modification.
+To enable Sass, you also need to add a dependency.
+To do so, just add
+
+  dependency "merb-haml"
+
+to config/dependencies.rb (or config/init.rb in a flat/very flat Merb application).
+Then it'll work just like it does in Rails.
+
+To use Haml and Sass programatically,
+check out the RDocs for the Haml and Sass modules.
+
+== Formatting
+
+=== Haml
+
+The most basic element of Haml
+is a shorthand for creating HTML tags:
+
+  %tagname{:attr1 => 'value1', :attr2 => 'value2'} Contents
+
+No end-tag is needed; Haml handles that automatically.
+Adding <tt>class</tt> and <tt>id</tt> attributes is even easier.
+Haml uses the same syntax as the CSS that styles the document:
+
+  %tagname#id.class
+
+In fact, when you're using the <tt><div></tt> tag,
+it becomes <em>even easier</em>.
+Because <tt><div></tt> is such a common element,
+a tag without a name defaults to a div. So
+
+  #foo Hello!
+
+becomes
+
+  <div id='foo'>Hello!</div>
+
+Haml uses indentation
+to bring the individual elements to represent the HTML structure.
+A tag's children are indented beneath than the parent tag.
+Again, a closing tag is automatically added.
+For example:
+
+  %ul
+    %li Salt
+    %li Pepper
+
+becomes:
+
+  <ul>
+    <li>Salt</li>
+    <li>Pepper</li>
+  </ul>
+
+You can also put plain text as a child of an element:
+
+  %p
+    Hello,
+    World!
+
+It's also possible to embed Ruby code into Haml documents.
+An equals sign, <tt>=</tt>, will output the result of the code.
+A hyphen, <tt>-</tt>, will run the code but not output the result.
+You can even use control statements
+like <tt>if</tt> and <tt>while</tt>:
+
+  %p
+    Date/Time:
+    - now = DateTime.now
+    %strong= now
+    - if now > DateTime.parse("December 31, 2006")
+      = "Happy new " + "year!"
+
+Haml provides far more tools than those presented here.
+Check out the reference documentation in the Haml module.
+
+=== Sass
+
+At its most basic,
+Sass is just another way of writing CSS.
+Although it's very much like normal CSS,
+the basic syntax offers a few helpful features:
+tabulation indicates the attributes in a rule,
+rather than non-DRY brackets;
+and newlines indicate the end of an attribute,
+rather than a semicolon.
+For example:
+
+  #main
+    :background-color #f00
+    :width 98%
+
+becomes:
+
+  #main {
+    background-color: #f00;
+    width: 98% }
+
+However, Sass provides much more than a way to make CSS look nice.
+In CSS, it's important to have accurate selectors,
+so your styles don't just apply to everything.
+However, in order to do this,
+you need to use nested element selectors.
+These get very ugly very quickly.
+I'm sure everyone's had to write something like
+"#main .sidebar .top p h1 a",
+followed by
+"#main .sidebar .top p h1 a:visited" and
+"#main .sidebar .top p h1 a:hover".
+Well, Sass gets rid of that.
+Like Haml, it uses indentation to indicate the structure of the document.
+So, what was:
+
+  #main {
+    width: 90%;
+  }
+  #main p {
+    border-style: solid;
+    border-width: 1px;
+    border-color: #00f;
+  }
+  #main p a {
+    text-decoration: none;
+    font-weight: bold;
+  }
+  #main p a:hover {
+    text-decoration: underline;
+  }
+
+becomes:
+
+  #main
+    :width 90%
+    p
+      :border-style solid
+      :border-width 1px
+      :border-color #00f
+      a
+        :text-decoration none
+        :font-weight bold
+      a:hover
+        :text-decoration underline
+
+Pretty nice, no? Well, it gets better.
+One of the main complaints against CSS is that it doesn't allow variables.
+What if have a color or a width you re-use all the time?
+In CSS, you just have to re-type it each time,
+which is a nightmare when you decide to change it later.
+Not so for Sass!
+You can use the "!" character to set variables.
+Then, if you put "=" after your attribute name,
+you can set it to a variable.
+For example:
+
+  !note_bg= #55aaff
+
+  #main
+    :width 70%
+    .note
+      :background-color= !note_bg
+    p
+      :width 5em
+      :background-color= !note_bg
+
+becomes:
+
+  #main {
+    width: 70%; }
+    #main .note {
+      background-color: #55aaff; }
+    #main p {
+      width: 5em;
+      background-color: #55aaff; }
+
+You can even do simple arithmetic operations with variables,
+adding numbers and even colors together:
+
+  !main_bg= #46ar12
+  !main_width= 40em
+
+  #main
+    :background-color= !main_bg
+    :width= !main_width
+    .sidebar
+      :background-color= !main_bg + #333333
+      :width= !main_width - 25em
+
+becomes:
+
+  #main {
+    background-color: #46a312;
+    width: 40em; }
+    #main .sidebar {
+      background-color: #79d645;
+      width: 15em; }
+
+Taking the idea of variables a bit further are mixins.
+These let you group whole swathes of CSS attributes into a single
+directive and then include those anywhere you want:
+
+  =blue-border
+    :border
+      :color blue
+      :width 2px
+      :style dotted
+
+  .comment
+    +blue-border
+    :padding 2px
+    :margin 10px 0
+
+  .reply
+    +blue-border
+
+becomes:
+
+  .comment {
+    border-color: blue;
+    border-width: 2px;
+    border-style: dotted;
+    padding: 2px;
+    margin: 10px 0;
+  }
+
+  .reply {
+    border-color: blue;
+    border-width: 2px;
+    border-style: dotted;
+  }
+
+A comprehensive list of features is in
+the documentation for the Sass module.
+
+== Indentation
+
+Indentation can be made up of one or more tabs or spaces.
+However, indentation must be consistent within a given document.
+Hard tabs and spaces can't be mixed,
+and the same number of tabs or spaces must be used throughout.
+
+== Executables
+
+The Haml gem includes several executables that are useful
+for dealing with Haml and Sass from the command line.
+
+=== +haml+
+
+The +haml+ executable transforms a source Haml file into HTML.
+See <tt>haml --help</tt> for further information and options.
+
+=== +sass+
+
+The +sass+ executable transforms a source Sass file into CSS.
+See <tt>sass --help</tt> for further information and options.
+
+=== <tt>html2haml</tt>
+
+The <tt>html2haml</tt> executable attempts to transform HTML,
+optionally with ERB markup, into Haml code.
+Since HTML is so variable, this transformation is not always perfect;
+it's a good idea to have a human check the output of this tool.
+See <tt>html2haml --help</tt> for further information and options.
+
+=== <tt>css2sass</tt>
+
+The <tt>css2sass</tt> executable attempts to transform CSS into Sass code.
+This transformation attempts to use Sass nesting where possible.
+See <tt>css2sass --help</tt> for further information and options.
+
+== Authors
+
+Haml and Sass are designed by Hampton Catlin (hcatlin) and he is the author
+of the original implementation. However, Hampton doesn't even know his way
+around the code anymore and mostly just concentrates on the language issues.
+Hampton lives in Toronto, Ontario (though he's an American by birth) and
+is a partner at Unspace Interactive.
+
+Nathan Weizenbaum is the primary maintainer and architect of the "modern" Ruby
+implementation of Haml. His hard work has kept the project alive by endlessly
+answering forum posts, fixing bugs, refactoring, finding speed improvements,
+writing documentation, implementing new features, and getting Hampton
+coffee (a fitting task for a boy-genius). Nathan lives in Seattle, Washington and
+while not being a student at University of Washington he consults for
+Unspace Interactive and Microsoft.
+
+Chris Eppstein is a core contributor to Sass and the creator of Compass, the first
+Sass-based framework. Chris focuses on making Sass more powerful, easy to use, and
+on ways to speed its adoption through the web development community. Chris lives in
+San Jose, CA with his wife and daughter. He is the Software Architect for Caring.com,
+a website devoted to the 34 Million caregivers whose parents are sick or elderly,
+that uses Haml and Sass.
+
+If you use this software, you must pay Hampton a compliment. And
+buy Nathan some jelly beans. Maybe pet a kitten. Yeah. Pet that kitty.
+
+Some of the work on Haml was supported by Unspace Interactive.
+
+Beyond that, the implementation is licensed under the MIT License.
+Ok, fine, I guess that means compliments aren't *required*.

data/bin/css2sass

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require File.dirname(__FILE__) + '/../lib/haml'
+require 'haml/exec'
+
+opts = Haml::Exec::CSS2Sass.new(ARGV)
+opts.parse!

data/bin/haml

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# The command line Haml parser.
+
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
+require 'haml'
+require 'haml/exec'
+
+opts = Haml::Exec::Haml.new(ARGV)
+opts.parse!

data/bin/html2haml

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require File.dirname(__FILE__) + '/../lib/haml'
+require 'haml/exec'
+
+opts = Haml::Exec::HTML2Haml.new(ARGV)
+opts.parse!

data/bin/sass

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# The command line Sass parser.
+
+require File.dirname(__FILE__) + '/../lib/haml'
+require 'haml/exec'
+
+opts = Haml::Exec::Sass.new(ARGV)
+opts.parse!

data/lib/haml/buffer.rb

@@ -0,0 +1,255 @@
+module Haml
+  # This class is used only internally. It holds the buffer of XHTML that
+  # is eventually output by Haml::Engine's to_html method. It's called
+  # from within the precompiled code, and helps reduce the amount of
+  # processing done within instance_eval'd code.
+  class Buffer
+    include Haml::Helpers
+    include Haml::Util
+
+    # The string that holds the compiled XHTML. This is aliased as
+    # _erbout for compatibility with ERB-specific code.
+    attr_accessor :buffer
+
+    # The options hash passed in from Haml::Engine.
+    attr_accessor :options
+
+    # The Buffer for the enclosing Haml document.
+    # This is set for partials and similar sorts of nested templates.
+    # It's nil at the top level (see #toplevel?).
+    attr_accessor :upper
+
+    # See #active?
+    attr_writer :active
+
+    # True if the format is XHTML
+    def xhtml?
+      not html?
+    end
+
+    # True if the format is any flavor of HTML
+    def html?
+      html4? or html5?
+    end
+
+    # True if the format is HTML4
+    def html4?
+      @options[:format] == :html4
+    end
+
+    # True if the format is HTML5
+    def html5?
+      @options[:format] == :html5
+    end
+
+    # True if this buffer is a top-level template,
+    # as opposed to a nested partial.
+    def toplevel?
+      upper.nil?
+    end
+
+    # True if this buffer is currently being used to render a Haml template.
+    # However, this returns false if a subtemplate is being rendered,
+    # even if it's a subtemplate of this buffer's template.
+    def active?
+      @active
+    end
+
+    # Gets the current tabulation of the document.
+    def tabulation
+      @real_tabs + @tabulation
+    end
+
+    # Sets the current tabulation of the document.
+    def tabulation=(val)
+      val = val - @real_tabs
+      @tabulation = val > -1 ? val : 0
+    end
+
+    # Creates a new buffer.
+    def initialize(upper = nil, options = {})
+      @active = true
+      @upper = upper
+      @options = {
+        :attr_wrapper => "'",
+        :ugly => false,
+        :format => :xhtml
+      }.merge options
+      @buffer = ""
+      @tabulation = 0
+
+      # The number of tabs that Engine thinks we should have
+      # @real_tabs + @tabulation is the number of tabs actually output
+      @real_tabs = 0
+    end
+
+    def push_text(text, tab_change, dont_tab_up)
+      if @tabulation > 0
+        # Have to push every line in by the extra user set tabulation.
+        # Don't push lines with just whitespace, though,
+        # because that screws up precompiled indentation.
+        text.gsub!(/^(?!\s+$)/m, tabs)
+        text.sub!(tabs, '') if dont_tab_up
+      end
+
+      @buffer << text
+      @real_tabs += tab_change
+    end
+
+    def adjust_tabs(tab_change)
+      @real_tabs += tab_change
+    end
+
+    Haml::Util.def_static_method(self, :format_script, [:result],
+                                 :preserve_script, :in_tag, :preserve_tag, :escape_html,
+                                 :nuke_inner_whitespace, :interpolated, :ugly, <<RUBY)
+      <% unless ugly %>
+        # If we're interpolated,
+        # then the custom tabulation is handled in #push_text.
+        # The easiest way to avoid it here is to reset @tabulation.
+        <% if interpolated %>
+          old_tabulation = @tabulation
+          @tabulation = 0
+        <% end %>
+
+        tabulation = @real_tabs
+        result = result.to_s.<% if nuke_inner_whitespace %>strip<% else %>rstrip<% end %>
+      <% else %>
+        result = result.to_s<% if nuke_inner_whitespace %>.strip<% end %>
+      <% end %>
+
+      <% if escape_html %> result = html_escape(result) <% end %>
+
+      <% if preserve_tag %>
+        result = Haml::Helpers.preserve(result)
+      <% elsif preserve_script %>
+        result = Haml::Helpers.find_and_preserve(result, options[:preserve])
+      <% end %>
+
+      <% if ugly %>
+        return result
+      <% else %>
+
+        has_newline = result.include?("\\n") 
+        <% if in_tag && !nuke_inner_whitespace %>
+          <% unless preserve_tag %> if !has_newline <% end %>
+          @real_tabs -= 1
+          <% if interpolated %> @tabulation = old_tabulation <% end %>
+          return result
+          <% unless preserve_tag %> end <% end %>
+        <% end %>
+
+        # Precompiled tabulation may be wrong
+        <% if !interpolated && !in_tag %>
+          result = tabs + result if @tabulation > 0
+        <% end %>
+
+        if has_newline
+          result = result.gsub "\\n", "\\n" + tabs(tabulation)
+
+          # Add tabulation if it wasn't precompiled
+          <% if in_tag && !nuke_inner_whitespace %> result = tabs(tabulation) + result <% end %>
+        end
+
+        <% if in_tag && !nuke_inner_whitespace %>
+          result = "\\n\#{result}\\n\#{tabs(tabulation-1)}"
+          @real_tabs -= 1
+        <% end %>
+        <% if interpolated %> @tabulation = old_tabulation <% end %>
+        result
+      <% end %>
+RUBY
+
+    # Takes the various information about the opening tag for an
+    # element, formats it, and adds it to the buffer.
+    def open_tag(name, self_closing, try_one_line, preserve_tag, escape_html, class_id,
+                 nuke_outer_whitespace, nuke_inner_whitespace, obj_ref, content, *attributes_hashes)
+      tabulation = @real_tabs
+
+      attributes = class_id
+      attributes_hashes.each do |old|
+        self.class.merge_attrs(attributes, to_hash(old.map {|k, v| [k.to_s, v]}))
+      end
+      self.class.merge_attrs(attributes, parse_object_ref(obj_ref)) if obj_ref
+
+      if self_closing && xhtml?
+        str = " />" + (nuke_outer_whitespace ? "" : "\n")
+      else
+        str = ">" + ((if self_closing && html?
+                        nuke_outer_whitespace
+                      else
+                        try_one_line || preserve_tag || nuke_inner_whitespace
+                      end) ? "" : "\n")
+      end
+
+      attributes = Precompiler.build_attributes(html?, @options[:attr_wrapper], attributes)
+      @buffer << "#{nuke_outer_whitespace || @options[:ugly] ? '' : tabs(tabulation)}<#{name}#{attributes}#{str}"
+
+      if content
+        @buffer << "#{content}</#{name}>" << (nuke_outer_whitespace ? "" : "\n")
+        return
+      end
+
+      @real_tabs += 1 unless self_closing || nuke_inner_whitespace
+    end
+
+    def self.merge_attrs(to, from)
+      if to['id'] && from['id']
+        to['id'] << '_' << from.delete('id')
+      elsif to['id'] || from['id']
+        from['id'] ||= to['id']
+      end
+
+      if to['class'] && from['class']
+        # Make sure we don't duplicate class names
+        from['class'] = (from['class'].split(' ') | to['class'].split(' ')).join(' ')
+      elsif to['class'] || from['class']
+        from['class'] ||= to['class']
+      end
+
+      to.merge!(from)
+    end
+
+    private
+
+    # Some of these methods are exposed as public class methods
+    # so they can be re-used in helpers.
+
+    @@tab_cache = {}
+    # Gets <tt>count</tt> tabs. Mostly for internal use.
+    def tabs(count = 0)
+      tabs = [count + @tabulation, 0].max
+      @@tab_cache[tabs] ||= '  ' * tabs
+    end
+
+    # Takes an array of objects and uses the class and id of the first
+    # one to create an attributes hash.
+    # The second object, if present, is used as a prefix,
+    # just like you can do with dom_id() and dom_class() in Rails
+    def parse_object_ref(ref)
+      prefix = ref[1]
+      ref = ref[0]
+      # Let's make sure the value isn't nil. If it is, return the default Hash.
+      return {} if ref.nil?
+      class_name = underscore(ref.class)
+      id = "#{class_name}_#{ref.id || 'new'}"
+      if prefix
+        class_name = "#{ prefix }_#{ class_name}"
+        id = "#{ prefix }_#{ id }"
+      end
+
+      {'id' => id, 'class' => class_name}
+    end
+
+    # Changes a word from camel case to underscores.
+    # Based on the method of the same name in Rails' Inflector,
+    # but copied here so it'll run properly without Rails.
+    def underscore(camel_cased_word)
+      camel_cased_word.to_s.gsub(/::/, '_').
+        gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+        gsub(/([a-z\d])([A-Z])/,'\1_\2').
+        tr("-", "_").
+        downcase
+    end
+  end
+end