haml 2.0.10 → 2.2.0

data/lib/sass/css.rb

@@ -3,29 +3,28 @@ require 'sass/tree/node'
 require 'strscan'
 
 module Sass
-  # :stopdoc:
   module Tree
     class Node
-      def to_sass(opts = {})
+      # Converts a node to Sass code that will generate it.
+      #
+      # @param tabs [Fixnum] The amount of tabulation to use for the Sass code
+      # @param opts [Hash<Symbol, Object>] An options hash (see {Sass::CSS#initialize})
+      # @return [String] The Sass code corresponding to the node
+      def to_sass(tabs = 0, opts = {})
         result = ''
 
         children.each do |child|
-          result << "#{child.to_sass(0, opts)}\n"
+          result << "#{'  ' * tabs}#{child.to_sass(0, opts)}\n"
         end
 
         result
       end
     end
 
-    class ValueNode
-      def to_sass(tabs, opts = {})
-        "#{value}\n"
-      end
-    end
-
     class RuleNode
+      # @see Node#to_sass
       def to_sass(tabs, opts = {})
-        str = "\n#{'  ' * tabs}#{rule}#{children.any? { |c| c.is_a? AttrNode } ? "\n" : ''}"
+        str = "\n#{'  ' * tabs}#{rules.first}#{children.any? { |c| c.is_a? PropNode } ? "\n" : ''}"
 
         children.each do |child|
           str << "#{child.to_sass(tabs + 1, opts)}"
@@ -35,96 +34,51 @@ module Sass
       end
     end
 
-    class AttrNode
+    class PropNode
+      # @see Node#to_sass
       def to_sass(tabs, opts = {})
-        "#{'  ' * tabs}#{opts[:alternate] ? '' : ':'}#{name}#{opts[:alternate] ? ':' : ''} #{value}\n"
+        "#{'  ' * tabs}#{opts[:old] ? ':' : ''}#{name}#{opts[:old] ? '' : ':'} #{value}\n"
       end
     end
 
     class DirectiveNode
+      # @see Node#to_sass
       def to_sass(tabs, opts = {})
         "#{'  ' * tabs}#{value}#{children.map {|c| c.to_sass(tabs + 1, opts)}}\n"
       end
     end
   end
 
-  # This class is based on the Ruby 1.9 ordered hashes.
-  # It keeps the semantics and most of the efficiency of normal hashes
-  # while also keeping track of the order in which elements were set.
-  class OrderedHash
-    Node = Struct.new(:key, :value, :next, :prev)
-    include Enumerable
-
-    def initialize
-      @hash = {}
-    end
-
-    def initialize_copy(other)
-      @hash = other.instance_variable_get('@hash').clone
-    end
-
-    def [](key)
-      @hash[key] && @hash[key].value
-    end
-
-    def []=(key, value)
-      node = Node.new(key, value)
-
-      if old = @hash[key]
-        if old.prev
-          old.prev.next = old.next
-        else # old is @first and @last
-          @first = @last = nil
-        end
-      end
-
-      if @first.nil?
-        @first = @last = node
-      else
-        node.prev = @last
-        @last.next = node
-        @last = node
-      end
-
-      @hash[key] = node
-      value
-    end
-
-    def each
-      return unless @first
-      yield [@first.key, @first.value]
-      node = @first
-      yield [node.key, node.value] while node = node.next
-      self
-    end
-
-    def values
-      self.map { |k, v| v }
-    end
-  end
-
-  # :startdoc:
-
-  # This class contains the functionality used in the +css2sass+ utility,
-  # namely converting CSS documents to Sass templates.
+  # This class converts CSS documents into Sass templates.
+  # It works by parsing the CSS document into a {Sass::Tree} structure,
+  # and then applying various transformations to the structure
+  # to produce more concise and idiomatic Sass.
+  #
+  # Example usage:
+  #
+  #     Sass::CSS.new("p { color: blue }").render #=> "p\n  color: blue"
   class CSS
-
-    # Creates a new instance of Sass::CSS that will compile the given document
-    # to a Sass string when +render+ is called.
+    # @param template [String] The CSS code
+    # @option options :old [Boolean] (false)
+    #     Whether or not to output old property syntax
+    #     (`:color blue` as opposed to `color: blue`).
     def initialize(template, options = {})
       if template.is_a? IO
         template = template.read
       end
 
-      @options = options
+      @options = options.dup
+      # Backwards compatibility
+      @options[:old] = true if @options[:alternate] == false
       @template = StringScanner.new(template)
     end
 
-    # Processes the document and returns the result as a string
-    # containing the CSS template.
+    # Converts the CSS template into Sass code.
+    #
+    # @return [String] The resulting Sass code
     def render
       begin
-        build_tree.to_sass(@options).strip + "\n"
+        build_tree.to_sass(0, @options).strip + "\n"
       rescue Exception => err
         line = @template.string[0...@template.pos].split("\n").size
 
@@ -135,8 +89,11 @@ module Sass
 
     private
 
+    # Parses the CSS template and applies various transformations
+    #
+    # @return [Tree::Node] The root node of the parsed tree
     def build_tree
-      root = Tree::Node.new(nil)
+      root = Tree::Node.new
       whitespace
       rules              root
       expand_commas      root
@@ -147,6 +104,9 @@ module Sass
       root
     end
 
+    # Parses a set of CSS rules.
+    #
+    # @param root [Tree::Node] The parent node of the rules
     def rules(root)
       while r = rule
         root << r
@@ -154,13 +114,28 @@ module Sass
       end
     end
 
+    # Parses a single CSS rule.
+    #
+    # @return [Tree::Node] The parsed rule
     def rule
-      return unless rule = @template.scan(/[^\{\};]+/)
+      rule = ""
+      loop do
+        token = @template.scan(/(?:[^\{\};\/\s]|\/[^*])+/)
+        if token.nil?
+          return if rule.empty?
+          break
+        end
+        rule << token
+        break unless @template.match?(/\s|\/\*/)
+        whitespace
+        rule << " "
+      end
+
       rule.strip!
       directive = rule[0] == ?@
 
       if directive
-        node = Tree::DirectiveNode.new(rule, nil)
+        node = Tree::DirectiveNode.new(rule)
         return node if @template.scan(/;/)
 
         assert_match /\{/
@@ -171,12 +146,15 @@ module Sass
       end
 
       assert_match /\{/
-      node = Tree::RuleNode.new(rule, nil)
-      attributes(node)
+      node = Tree::RuleNode.new(rule)
+      properties(node)
       return node
     end
 
-    def attributes(rule)
+    # Parses a set of CSS properties within a rule.
+    #
+    # @param rule [Tree::RuleNode] The parent node of the properties
+    def properties(rule)
       while @template.scan(/[^:\}\s]+/)
         name = @template[0]
         whitespace
@@ -189,12 +167,15 @@ module Sass
         end
 
         assert_match /(;|(?=\}))/
-        rule << Tree::AttrNode.new(name, value, nil)
+        rule << Tree::PropNode.new(name, value, nil)
       end
 
       assert_match /\}/
     end
 
+    # Moves the scanner over a section of whitespace or comments.
+    #
+    # @return [String] The ignored whitespace
     def whitespace
       space = @template.scan(/\s*/) || ''
 
@@ -207,37 +188,53 @@ module Sass
       return space
     end
 
+    # Moves the scanner over a regular expression,
+    # raising an exception if it doesn't match.
+    #
+    # @param re [Regexp] The regular expression to assert
     def assert_match(re)
-      if !@template.scan(re)
-        line = @template.string[0..@template.pos].count "\n"
-        # Display basic regexps as plain old strings
-        expected = re.source == Regexp.escape(re.source) ? "\"#{re.source}\"" : re.inspect
-        raise Exception.new("Invalid CSS on line #{line}: expected #{expected}")
+      if @template.scan(re)
+        whitespace
+        return
       end
-      whitespace
+
+      line = @template.string[0..@template.pos].count "\n"
+      pos = @template.pos
+
+      after = @template.string[pos - 15...pos]
+      after = "..." + after if pos >= 15
+
+      # Display basic regexps as plain old strings
+      expected = re.source == Regexp.escape(re.source) ? "\"#{re.source}\"" : re.inspect
+
+      was = @template.rest[0...15]
+      was += "..." if @template.rest.size >= 15
+      raise Exception.new(<<MESSAGE)
+Invalid CSS on line #{line + 1} after #{after.inspect}:
+  expected #{expected}, was #{was.inspect}
+MESSAGE
     end
 
     # Transform
     #
-    #   foo, bar, baz
-    #     color: blue
+    #     foo, bar, baz
+    #       color: blue
     #
     # into
     #
-    #   foo
-    #     color: blue
-    #   bar
-    #     color: blue
-    #   baz
-    #     color: blue
+    #     foo
+    #       color: blue
+    #     bar
+    #       color: blue
+    #     baz
+    #       color: blue
     #
-    # Yes, this expands the amount of code,
-    # but it's necessary to get nesting to work properly.
+    # @param root [Tree::Node] The parent node
     def expand_commas(root)
       root.children.map! do |child|
-        next child unless Tree::RuleNode === child && child.rule.include?(',')
-        child.rule.split(',').map do |rule|
-          node = Tree::RuleNode.new(rule.strip, {})
+        next child unless Tree::RuleNode === child && child.rules.first.include?(',')
+        child.rules.first.split(',').map do |rule|
+          node = Tree::RuleNode.new(rule.strip)
           node.children = child.children
           node
         end
@@ -247,71 +244,77 @@ module Sass
 
     # Make rules use parent refs so that
     #
-    #   foo
-    #     color: green
-    #   foo.bar
-    #     color: blue
+    #     foo
+    #       color: green
+    #     foo.bar
+    #       color: blue
     #
     # becomes
     #
-    #   foo
-    #     color: green
-    #     &.bar
-    #       color: blue
+    #     foo
+    #       color: green
+    #       &.bar
+    #         color: blue
     #
     # This has the side effect of nesting rules,
     # so that
     #
-    #   foo
-    #     color: green
-    #   foo bar
-    #     color: red
-    #   foo baz
-    #     color: blue
+    #     foo
+    #       color: green
+    #     foo bar
+    #       color: red
+    #     foo baz
+    #       color: blue
     #
     # becomes
     #
-    #   foo
-    #     color: green
-    #     & bar
-    #       color: red
-    #     & baz
-    #       color: blue
+    #     foo
+    #       color: green
+    #       & bar
+    #         color: red
+    #       & baz
+    #         color: blue
     #
+    # @param root [Tree::Node] The parent node
     def parent_ref_rules(root)
-      rules = OrderedHash.new
+      current_rule = nil
       root.children.select { |c| Tree::RuleNode === c }.each do |child|
         root.children.delete child
-        first, rest = child.rule.scan(/^(&?(?: .|[^ ])[^.#: \[]*)([.#: \[].*)?$/).first
-        rules[first] ||= Tree::RuleNode.new(first, nil)
+        first, rest = child.rules.first.scan(/^(&?(?: .|[^ ])[^.#: \[]*)([.#: \[].*)?$/).first
+
+        if current_rule.nil? || current_rule.rules.first != first
+          current_rule = Tree::RuleNode.new(first)
+          root << current_rule
+        end
+
         if rest
-          child.rule = "&" + rest
-          rules[first] << child
+          child.rules = ["&" + rest]
+          current_rule << child
         else
-          rules[first].children += child.children
+          current_rule.children += child.children
         end
       end
 
-      rules.values.each { |v| parent_ref_rules(v) }
-      root.children += rules.values
+      root.children.each { |v| parent_ref_rules(v) }
     end
 
     # Remove useless parent refs so that
     #
-    #   foo
-    #     & bar
-    #       color: blue
+    #     foo
+    #       & bar
+    #         color: blue
     #
     # becomes
     #
-    #   foo
-    #     bar
-    #       color: blue
+    #     foo
+    #       bar
+    #         color: blue
     #
+    # @param root [Tree::Node] The parent node
     def remove_parent_refs(root)
       root.children.each do |child|
         if child.is_a?(Tree::RuleNode)
-          child.rule.gsub! /^& +/, ''
+          child.rules.first.gsub! /^& +/, ''
           remove_parent_refs child
         end
       end
@@ -319,39 +322,43 @@ module Sass
 
     # Flatten rules so that
     #
-    #   foo
-    #     bar
-    #       baz
+    #     foo
+    #       bar
     #         color: red
     #
     # becomes
     #
-    #   foo bar baz
-    #     color: red
+    #     foo bar
+    #       color: red
     #
     # and
     #
-    #   foo
-    #     &.bar
-    #       color: blue
+    #     foo
+    #       &.bar
+    #         color: blue
     #
     # becomes
     #
-    #   foo.bar
-    #     color: blue
+    #     foo.bar
+    #       color: blue
     #
+    # @param root [Tree::Node] The parent node
     def flatten_rules(root)
       root.children.each { |child| flatten_rule(child) if child.is_a?(Tree::RuleNode) }
     end
 
+    # Flattens a single rule
+    #
+    # @param rule [Tree::RuleNode] The candidate for flattening
+    # @see #flatten_rules
     def flatten_rule(rule)
       while rule.children.size == 1 && rule.children.first.is_a?(Tree::RuleNode)
         child = rule.children.first
 
-        if child.rule[0] == ?&
-          rule.rule = child.rule.gsub /^&/, rule.rule
+        if child.rules.first[0] == ?&
+          rule.rules = [child.rules.first.gsub(/^&/, rule.rules.first)]
         else
-          rule.rule = "#{rule.rule} #{child.rule}"
+          rule.rules = ["#{rule.rules.first} #{child.rules.first}"]
         end
 
         rule.children = child.children
@@ -362,25 +369,26 @@ module Sass
 
     # Transform
     #
-    #   foo
-    #     bar
-    #       color: blue
-    #     baz
-    #       color: blue
+    #     foo
+    #       bar
+    #         color: blue
+    #       baz
+    #         color: blue
     #
     # into
     #
-    #   foo
-    #     bar, baz
-    #       color: blue
+    #     foo
+    #       bar, baz
+    #         color: blue
     #
+    # @param rule [Tree::RuleNode] The candidate for flattening
     def fold_commas(root)
       prev_rule = nil
       root.children.map! do |child|
         next child unless child.is_a?(Tree::RuleNode)
 
         if prev_rule && prev_rule.children == child.children
-          prev_rule.rule << ", #{child.rule}"
+          prev_rule.rules.first << ", #{child.rules.first}"
           next nil
         end