haml-edge 2.1.21 → 2.1.22

data/lib/haml/html.rb

@@ -6,13 +6,19 @@ require 'hpricot'
 require 'cgi'
 
 module Haml
-  # This class contains the functionality used in the +html2haml+ utility,
-  # namely converting HTML documents to Haml templates.
-  # It depends on Hpricot for HTML parsing (http://code.whytheluckystiff.net/hpricot/).
+  # Converts HTML documents into Haml templates.
+  # Depends on [Hpricot](http://code.whytheluckystiff.net/hpricot/) for HTML parsing.
+  #
+  # Example usage:
+  #
+  #     Haml::Engine.new("<a href='http://google.com'>Blat</a>").render
+  #       #=> "%a{:href => 'http://google.com'} Blat"
   class HTML
-    # Creates a new instance of Haml::HTML that will compile the given template,
-    # which can either be a string containing HTML or an Hpricot node,
-    # to a Haml string when +render+ is called.
+    # @param template [String, Hpricot::Node] The HTML template to convert
+    # @option options :rhtml [Boolean] (false) Whether or not to parse
+    #   ERB's `<%= %>` and `<% %>` into Haml's `=` and `-`
+    # @option options :xhtml [Boolean] (false) Whether or not to parse
+    #   the HTML strictly as XHTML
     def initialize(template, options = {})
       @options = options
 
@@ -40,9 +46,13 @@ module Haml
     end
     alias_method :to_haml, :render
 
+    # Haml monkeypatches various Hpricot classes
+    # to add methods for conversion to Haml.
     module ::Hpricot::Node
-      # Returns the Haml representation of the given node,
-      # at the given tabulation.
+      # Returns the Haml representation of the given node.
+      #
+      # @param tabs [Fixnum] The indentation level of the resulting Haml.
+      # @option options (see Haml::HTML#initialize)
       def to_haml(tabs, options)
         parse_text(self.to_s, tabs)
       end
@@ -68,29 +78,35 @@ module Haml
       end
     end
 
-    # :stopdoc:
-
     TEXT_REGEXP = /^(\s*).*$/
 
+    # @see Hpricot::Node
     class ::Hpricot::Doc
+      # @see Hpricot::Node#to_haml
       def to_haml(tabs, options)
         (children || []).inject('') {|s, c| s << c.to_haml(0, options)}
       end
     end
 
+    # @see Hpricot::Node
     class ::Hpricot::XMLDecl
+      # @see Hpricot::Node#to_haml
       def to_haml(tabs, options)
         "#{tabulate(tabs)}!!! XML\n"
       end
     end
 
+    # @see Hpricot::Node
     class ::Hpricot::CData
+      # @see Hpricot::Node#to_haml
       def to_haml(tabs, options)
         "#{tabulate(tabs)}:cdata\n#{parse_text(self.content, tabs + 1)}"
       end
     end
 
+    # @see Hpricot::Node
     class ::Hpricot::DocType
+      # @see Hpricot::Node#to_haml
       def to_haml(tabs, options)
         attrs = public_id.scan(/DTD\s+([^\s]+)\s*([^\s]*)\s*([^\s]*)\s*\/\//)[0]
         if attrs == nil
@@ -121,17 +137,21 @@ module Haml
       end
     end
 
+    # @see Hpricot::Node
     class ::Hpricot::Comment
+      # @see Hpricot::Node#to_haml
       def to_haml(tabs, options)
         "#{tabulate(tabs)}/\n#{parse_text(self.content, tabs + 1)}"
       end
     end
 
+    # @see Hpricot::Node
     class ::Hpricot::Elem
+      # @see Hpricot::Node#to_haml
       def to_haml(tabs, options)
         output = "#{tabulate(tabs)}"
         if options[:rhtml] && name[0...5] == 'haml:'
-          return output + HTML.send("haml_tag_#{name[5..-1]}", CGI.unescapeHTML(self.inner_text))
+          return output + send("haml_tag_#{name[5..-1]}", CGI.unescapeHTML(self.inner_text))
         end
 
         output += "%#{name}" unless name == 'div' &&
@@ -170,7 +190,15 @@ module Haml
           end
         end
       end
-      
+
+      def haml_tag_loud(text)
+        "= #{text.gsub(/\n\s*/, ' ').strip}\n"
+      end
+
+      def haml_tag_silent(text)
+        text.split("\n").map { |line| "- #{line.strip}\n" }.join
+      end
+
       def static_attribute?(name, options)
         attributes[name] and !dynamic_attribute?(name, options)
       end
@@ -199,14 +227,6 @@ module Haml
       end
     end
 
-    def self.haml_tag_loud(text)
-      "= #{text.gsub(/\n\s*/, ' ').strip}\n"
-    end
-
-    def self.haml_tag_silent(text)
-      text.split("\n").map { |line| "- #{line.strip}\n" }.join
-    end
-
     private
 
     def match_to_html(string, regex, tag)
@@ -214,6 +234,5 @@ module Haml
         "<haml:#{tag}>#{CGI.escapeHTML($1)}</haml:#{tag}>"
       end
     end
-    # :startdoc:
   end
 end

data/lib/haml/precompiler.rb

@@ -2,6 +2,8 @@ require 'strscan'
 require 'haml/shared'
 
 module Haml
+  # Handles the internal pre-compilation from Haml into Ruby code,
+  # which then runs the final creation of the HTML string.
   module Precompiler
     include Haml::Util
 

data/lib/haml/shared.rb

@@ -1,17 +1,43 @@
 require 'strscan'
 
-# :stopdoc:
 module Haml
-  # This module contains functionality that's shared across Haml and Sass.
+  # This module contains functionality that's shared between Haml and Sass.
   module Shared
     extend self
 
+    # Scans through a string looking for the interoplation-opening `#{`
+    # and, when it's found, yields the scanner to the calling code
+    # so it can handle it properly.
+    #
+    # The scanner will have any backslashes immediately in front of the `#{`
+    # as the second capture group (`scan[2]`),
+    # and the text prior to that as the first (`scan[1]`).
+    #
+    # @yieldparam scan [StringScanner] The scanner scanning through the string
+    # @return [String] The text remaining in the scanner after all `#{`s have been processed
     def handle_interpolation(str)
       scan = StringScanner.new(str)
       yield scan while scan.scan(/(.*?)(\\*)\#\{/)
       scan.rest
     end
 
+    # Moves a scanner through a balanced pair of characters.
+    # For example:
+    #
+    #     Foo (Bar (Baz bang) bop) (Bang (bop bip))
+    #     ^                       ^
+    #     from                    to
+    #
+    # @param scanner [StringScanner] The string scanner to move
+    # @param start [Character] The character opening the balanced pair.
+    #   A `Fixnum` in 1.8, a `String` in 1.9
+    # @param finish [Character] The character closing the balanced pair.
+    #   A `Fixnum` in 1.8, a `String` in 1.9
+    # @param count [Fixnum] The number of opening characters matched
+    #   before calling this method
+    # @return [(String, String)] The string matched within the balanced pair
+    #   and the rest of the string.
+    #   `["Foo (Bar (Baz bang) bop)", " (Bang (bop bip))"]` in the example above.
     def balance(scanner, start, finish, count = 0)
       str = ''
       scanner = StringScanner.new(scanner) unless scanner.is_a? StringScanner
@@ -24,6 +50,12 @@ module Haml
       end
     end
 
+    # Formats a string for use in error messages about indentation.
+    #
+    # @param indentation [String] The string used for indentation
+    # @param was [Boolean] Whether or not to add `"was"` or `"were"`
+    #   (depending on how many characters were in `indentation`)
+    # @return [String] The name of the indentation (e.g. `"12 spaces"`, `"1 tab"`)
     def human_indentation(indentation, was = false)
       if !indentation.include?(?\t)
         noun = 'space'
@@ -44,4 +76,3 @@ module Haml
     end
   end
 end
-# :startdoc:

data/lib/haml/template/patch.rb

@@ -9,7 +9,7 @@
 # The documentation can be found
 # here[http://rubyonrails.org/api/classes/ActionView/Base.html].
 module ActionView
-  class Base # :nodoc:
+  class Base
     def delegate_template_exists_with_haml(template_path)
       template_exists?(template_path, :haml) && [:haml]
     end

data/lib/haml/template/plugin.rb

@@ -1,4 +1,3 @@
-# :stopdoc:
 # This file makes Haml work with Rails
 # using the > 2.0.1 template handler API.
 
@@ -70,4 +69,3 @@ if ActionView::TemplateError.instance_method(:initialize).arity == 5
     end
   end
 end
-# :startdoc:

data/lib/haml/template.rb

@@ -1,10 +1,15 @@
 require 'haml/engine'
 
 module Haml
+  # The class that keeps track of the global options for Haml within Rails.
   module Template
     extend self
 
     @options = {}
+    # The options hash for Haml when used within Rails.
+    # See [the Haml options documentation](../Haml.html#haml_options).
+    #
+    # @return [Hash<Symbol, Object>]
     attr_accessor :options
   end
 end

data/lib/haml/util.rb

@@ -3,32 +3,94 @@ require 'set'
 require 'enumerator'
 
 module Haml
+  # A module containing various useful functions.
   module Util
     extend self
 
+    # An array of ints representing the Ruby version number.
     RUBY_VERSION = ::RUBY_VERSION.split(".").map {|s| s.to_i}
 
-    # Returns the path of file relative to the Haml root.
+    # Returns the path of a file relative to the Haml root directory.
+    #
+    # @param file [String] The filename relative to the Haml root
+    # @return [String] The filename relative to the the working directory
     def scope(file)
       File.expand_path File.join(File.dirname(__FILE__), '..', '..', file)
     end
 
+    # Converts an array of `[key, value]` pairs to a hash.
+    # For example:
+    #
+    #     to_hash([[:foo, "bar"], [:baz, "bang"]])
+    #       #=> {:foo => "bar", :baz => "bang"}
+    #
+    # @param arr [Array<(Object, Object)>] An array of pairs
+    # @return [Hash] A hash
     def to_hash(arr)
       arr.compact.inject({}) {|h, (k, v)| h[k] = v; h}
     end
 
+    # Maps the keys in a hash according to a block.
+    # For example:
+    #
+    #     map_keys({:foo => "bar", :baz => "bang"}) {|k| k.to_s}
+    #       #=> {"foo" => "bar", "baz" => "bang"}
+    #
+    # @param hash [Hash] The hash to map
+    # @yield [key] A block in which the keys are transformed
+    # @yieldparam key [Object] The key that should be mapped
+    # @yieldreturn [Object] The new value for the key
+    # @return [Hash] The mapped hash
+    # @see #map_vals
+    # @see #map_hash
     def map_keys(hash)
       to_hash(hash.map {|k, v| [yield(k), v]})
     end
 
+    # Maps the values in a hash according to a block.
+    # For example:
+    #
+    #     map_values({:foo => "bar", :baz => "bang"}) {|v| v.to_sym}
+    #       #=> {:foo => :bar, :baz => :bang}
+    #
+    # @param hash [Hash] The hash to map
+    # @yield [value] A block in which the values are transformed
+    # @yieldparam value [Object] The value that should be mapped
+    # @yieldreturn [Object] The new value for the value
+    # @return [Hash] The mapped hash
+    # @see #map_keys
+    # @see #map_hash
     def map_vals(hash)
       to_hash(hash.map {|k, v| [k, yield(v)]})
     end
 
+    # Maps the key-value pairs of a hash according to a block.
+    # For example:
+    #
+    #     map_hash({:foo => "bar", :baz => "bang"}) {|k, v| [k.to_s, v.to_sym]}
+    #       #=> {"foo" => :bar, "baz" => :bang}
+    #
+    # @param hash [Hash] The hash to map
+    # @yield [key, value] A block in which the key-value pairs are transformed
+    # @yieldparam [key] The hash key
+    # @yieldparam [value] The hash value
+    # @yieldreturn [(Object, Object)] The new value for the `[key, value]` pair
+    # @return [Hash] The mapped hash
+    # @see #map_keys
+    # @see #map_vals
     def map_hash(hash, &block)
       to_hash(hash.map(&block))
     end
 
+    # Computes the powerset of the given array.
+    # This is the set of all subsets of the array.
+    # For example:
+    #
+    #     powerset([1, 2, 3]) #=>
+    #       Set[Set[], Set[1], Set[2], Set[3], Set[1, 2], Set[2, 3], Set[1, 3], Set[1, 2, 3]]
+    #
+    # @param arr [Enumerable]
+    # @return [Set<Set>] The subsets of `arr`
     def powerset(arr)
       arr.inject([Set.new].to_set) do |powerset, el|
         new_powerset = Set.new
@@ -40,6 +102,15 @@ module Haml
       end
     end
 
+    # Concatenates all strings that are adjacent in an array,
+    # while leaving other elements as they are.
+    # For example:
+    #
+    #     merge_adjacent_strings([1, "foo", "bar", 2, "baz"])
+    #       #=> [1, "foobar", 2, "baz"]
+    #
+    # @param enum [Enumerable]
+    # @return [Array] The enumerable with strings merged
     def merge_adjacent_strings(enum)
       e = enum.inject([]) do |a, e|
         if e.is_a?(String) && a.last.is_a?(String)
@@ -51,29 +122,88 @@ module Haml
       end
     end
 
+    # Whether or not this is running under Ruby 1.8 or lower.
+    #
+    # @return [Boolean]
     def ruby1_8?
       Haml::Util::RUBY_VERSION[0] == 1 && Haml::Util::RUBY_VERSION[1] < 9
     end
 
+    # Checks to see if a class has a given method.
+    # For example:
+    #
+    #     Haml::Util.has?(:public_instance_method, String, :gsub) #=> true
+    #
+    # Method collections like `Class#instance_methods`
+    # return strings in Ruby 1.8 and symbols in Ruby 1.9 and on,
+    # so this handles checking for them in a compatible way.
+    #
+    # @param attr [#to_s] The (singular) name of the method-collection method
+    #   (e.g. `:instance_methods`, `:private_methods`)
+    # @param klass [Module] The class to check the methods of which to check
+    # @param method [String, Symbol] The name of the method do check for
+    # @return [Boolean] Whether or not the given collection has the given method
     def has?(attr, klass, method)
       klass.send("#{attr}s").include?(ruby1_8? ? method.to_s : method.to_sym)
     end
 
+    # A version of `Enumerable#enum_with_index` that works in Ruby 1.8 and 1.9.
+    #
+    # @param enum [Enumerable] The enumerable to get the enumerator for
+    # @return [Enumerator] The with-index enumerator
     def enum_with_index(enum)
       ruby1_8? ? enum.enum_with_index : enum.each_with_index
     end
 
+    # The context in which the ERB for \{#def\_static\_method} will be run.
     class StaticConditionalContext
+      # @param set [#include?] The set of variables that are defined for this context.
       def initialize(set)
         @set = set
       end
 
+      # Checks whether or not a variable is defined for this context.
+      #
+      # @param name [Symbol] The name of the variable
+      # @return [Boolean]
       def method_missing(name, *args, &block)
         super unless args.empty? && block.nil?
         @set.include?(name)
       end
     end
 
+    # This is used for methods in {Haml::Buffer} that need to be very fast,
+    # and take a lot of boolean parameters
+    # that are known at compile-time.
+    # Instead of passing the parameters in normally,
+    # a separate method is defined for every possible combination of those parameters;
+    # these are then called using \{#static\_method\_name}.
+    #
+    # To define a static method, an ERB template for the method is provided.
+    # All conditionals based on the static parameters
+    # are done as embedded Ruby within this template.
+    # For example:
+    #
+    #     def_static_method(Foo, :my_static_method, [:foo, :bar], :baz, :bang, <<RUBY)
+    #       <% if baz && bang %>
+    #         return foo + bar
+    #       <% elsif baz || bang %>
+    #         return foo - bar
+    #       <% else %>
+    #         return 17
+    #       <% end %>
+    #     RUBY
+    #
+    # \{#static\_method\_name} can be used to call static methods.
+    #
+    # @overload def_static_method(klass, name, args, *vars, erb)
+    # @param klass [Module] The class on which to define the static method
+    # @param name [#to_s] The (base) name of the static method
+    # @param args [Array<Symbol>] The names of the arguments to the defined methods
+    #   (**not** to the ERB template)
+    # @param vars [Array<Symbol>] The names of the static boolean variables
+    #   to be made available to the ERB template
+    # @param erb [String] The template for the method code
     def def_static_method(klass, name, args, *vars)
       erb = vars.pop
       powerset(vars).each do |set|
@@ -86,6 +216,11 @@ METHOD
       end
     end
 
+    # Computes the name for a method defined via \{#def\_static\_method}.
+    #
+    # @param name [String] The base name of the static method
+    # @param vars [Array<Boolean>] The static variable assignment
+    # @return [String] The real name of the static method
     def static_method_name(name, *vars)
       "#{name}_#{vars.map {|v| !!v}.join('_')}"
     end

data/lib/haml/version.rb

@@ -1,14 +1,26 @@
 require 'haml/util'
 
 module Haml
+  # Handles Haml version-reporting.
+  # Haml not only reports the standard three version numbers,
+  # but its Git revision hash as well,
+  # if it was installed from Git.
   module Version
     include Haml::Util
 
     # Returns a hash representing the version of Haml.
-    # The :major, :minor, and :teeny keys have their respective numbers.
-    # The :string key contains a human-readable string representation of the version.
-    # If Haml is checked out from Git,
-    # the :rev key will have the revision hash.
+    # The `:major`, `:minor`, and `:teeny` keys have their respective numbers as Fixnums.
+    # The `:string` key contains a human-readable string representation of the version.
+    # If Haml is checked out from Git, the `:rev` key will have the revision hash.
+    # For example:
+    #
+    #     {
+    #       :string=>"2.1.0.9616393",
+    #       :rev => "9616393b8924ef36639c7e82aa88a51a24d16949",
+    #       :major => 2, :minor => 1, :teeny => 0
+    #     }
+    #
+    # @return [Hash<Symbol, String/Symbol>] The version hash
     def version
       return @@version if defined?(@@version)