haml 2.0.10 → 2.2.0

data/lib/sass/tree/file_node.rb

@@ -0,0 +1,41 @@
+module Sass
+  module Tree
+    # A static node that wraps the {Sass::Tree} for an `@import`ed file.
+    # It doesn't have a functional purpose other than to add the `@import`ed file
+    # to the backtrace if an error occurs.
+    class FileNode < Node
+      # @param filename [String] The name of the imported file
+      def initialize(filename)
+        @filename = filename
+        super()
+      end
+
+      # Computes the CSS for the imported file.
+      #
+      # @param args [Array] Ignored
+      def to_s(*args)
+        @to_s ||= (style == :compressed ? super().strip : super())
+      rescue Sass::SyntaxError => e
+        e.add_backtrace_entry(@filename)
+        raise e
+      end
+
+      def invisible?; to_s.empty?; end
+
+      protected
+
+      # Parses the imported file
+      # and runs the dynamic Sass for it.
+      #
+      # @param environment [Sass::Environment] The lexical environment containing
+      #   variable and mixin values
+      def perform!(environment)
+        self.children = Sass::Files.tree_for(filename, @options).children
+        self.children = perform_children(environment)
+      rescue Sass::SyntaxError => e
+        e.add_backtrace_entry(@filename)
+        raise e
+      end
+    end
+  end
+end

data/lib/sass/tree/for_node.rb

@@ -0,0 +1,48 @@
+require 'sass/tree/node'
+
+module Sass::Tree
+  # A dynamic node representing a Sass `@for` loop.
+  #
+  # @see Sass::Tree
+  class ForNode < Node
+    # @param var [String] The name of the loop variable
+    # @param from [Script::Node] The parse tree for the initial expression
+    # @param to [Script::Node] The parse tree for the final expression
+    # @param exclusive [Boolean] Whether to include `to` in the loop
+    #   or stop just before
+    def initialize(var, from, to, exclusive)
+      @var = var
+      @from = from
+      @to = to
+      @exclusive = exclusive
+      super()
+    end
+
+    protected
+
+    # Runs the child nodes once for each time through the loop,
+    # varying the variable each time.
+    #
+    # @param environment [Sass::Environment] The lexical environment containing
+    #   variable and mixin values
+    # @return [Array<Tree::Node>] The resulting static nodes
+    # @see Sass::Tree
+    def _perform(environment)
+      from = @from.perform(environment)
+      to = @to.perform(environment)
+      from.assert_int!
+      to.assert_int!
+
+      to = to.coerce(from.numerator_units, from.denominator_units)
+      range = Range.new(from.to_i, to.to_i, @exclusive)
+
+      children = []
+      environment = Sass::Environment.new(environment)
+      range.each do |i|
+        environment.set_local_var(@var, Sass::Script::Number.new(i, from.numerator_units, from.denominator_units))
+        children += perform_children(environment)
+      end
+      children
+    end
+  end
+end

data/lib/sass/tree/if_node.rb

@@ -0,0 +1,54 @@
+require 'sass/tree/node'
+
+module Sass::Tree
+  # A dynamic node representing a Sass `@if` statement.
+  #
+  # {IfNode}s are a little odd, in that they also represent `@else` and `@else if`s.
+  # This is done as a linked list:
+  # each {IfNode} has a link (\{#else}) to the next {IfNode}.
+  #
+  # @see Sass::Tree
+  class IfNode < Node
+    # The next {IfNode} in the if-else list, or `nil`.
+    #
+    # @return [IfNode]
+    attr_accessor :else
+
+    # @param expr [Script::Expr] The conditional expression.
+    #   If this is nil, this is an `@else` node, not an `@else if`
+    def initialize(expr)
+      @expr = expr
+      @last_else = self
+      super()
+    end
+
+    # Append an `@else` node to the end of the list.
+    #
+    # @param node [IfNode] The `@else` node to append
+    def add_else(node)
+      @last_else.else = node
+      @last_else = node
+    end
+
+    def options=(options)
+      super
+      self.else.options = options if self.else
+    end
+
+    protected
+
+    # Runs the child nodes if the conditional expression is true;
+    # otherwise, tries the \{#else} nodes.
+    #
+    # @param environment [Sass::Environment] The lexical environment containing
+    #   variable and mixin values
+    # @return [Array<Tree::Node>] The resulting static nodes
+    # @see Sass::Tree
+    def _perform(environment)
+      environment = Sass::Environment.new(environment)
+      return perform_children(environment) if @expr.nil? || @expr.perform(environment).to_bool
+      return @else.perform(environment) if @else
+      []
+    end
+  end
+end

data/lib/sass/tree/mixin_def_node.rb

@@ -0,0 +1,29 @@
+module Sass
+  module Tree
+    # A dynamic node representing a mixin definition.
+    #
+    # @see Sass::Tree
+    class MixinDefNode < Node
+      # @param name [String] The mixin name
+      # @param args [Array<(String, Script::Node)>] The arguments for the mixin.
+      #   Each element is a tuple containing the name of the argument
+      #   and the parse tree for the default value of the argument
+      def initialize(name, args)
+        @name = name
+        @args = args
+        super()
+      end
+
+      protected
+
+      # Loads the mixin into the environment.
+      #
+      # @param environment [Sass::Environment] The lexical environment containing
+      #   variable and mixin values
+      def _perform(environment)
+        environment.set_mixin(@name, Sass::Mixin.new(@name, @args, environment, children))
+        []
+      end
+    end
+  end
+end

data/lib/sass/tree/mixin_node.rb

@@ -0,0 +1,48 @@
+require 'sass/tree/node'
+
+module Sass::Tree
+  # A dynamic node representing a mixin include.
+  #
+  # @see Sass::Tree
+  class MixinNode < Node
+    # @param name [String] The name of the mixin
+    # @param args [Array<Script::Node>] The arguments to the mixin
+    def initialize(name, args)
+      @name = name
+      @args = args
+      super()
+    end
+
+    protected
+
+    # Runs the mixin.
+    #
+    # @param environment [Sass::Environment] The lexical environment containing
+    #   variable and mixin values
+    # @return [Array<Tree::Node>] The resulting static nodes
+    # @raise [Sass::SyntaxError] if there is no mixin with the given name
+    # @raise [Sass::SyntaxError] if an incorrect number of arguments was passed
+    # @see Sass::Tree
+    def _perform(environment)
+      raise Sass::SyntaxError.new("Undefined mixin '#{@name}'.", @line) unless mixin = environment.mixin(@name)
+
+      raise Sass::SyntaxError.new(<<END.gsub("\n", "")) if mixin.args.size < @args.size
+Mixin #{@name} takes #{mixin.args.size} argument#{'s' if mixin.args.size != 1}
+ but #{@args.size} #{@args.size == 1 ? 'was' : 'were'} passed.
+END
+
+      environment = mixin.args.zip(@args).
+        inject(Sass::Environment.new(mixin.environment)) do |env, ((name, default), value)|
+        env.set_local_var(name,
+          if value
+            value.perform(environment)
+          elsif default
+            default.perform(env)
+          end)
+        raise Sass::SyntaxError.new("Mixin #{@name} is missing parameter !#{name}.") unless env.var(name)
+        env
+      end
+      mixin.tree.map {|c| c.perform(environment)}.flatten
+    end
+  end
+end

data/lib/sass/tree/node.rb

@@ -1,15 +1,69 @@
 module Sass
+  # A namespace for nodes in the Sass parse tree.
+  #
+  # The Sass parse tree has two states.
+  # When it's first parsed, it has nodes for mixin definitions
+  # and for loops and so forth,
+  # in addition to nodes for CSS rules and properties.
+  #
+  # However, {Tree::Node#perform} returns a different sort of tree.
+  # This tree maps more closely to the resulting CSS document
+  # than it does to the original Sass document.
+  # It still has nodes for CSS rules and properties,
+  # but it doesn't have any dynamic-generation-related nodes.
+  #
+  # Nodes that only appear in the pre-perform state are called **dynamic nodes**;
+  # those that appear in both states are called **static nodes**.
   module Tree
+    # This class doubles as the root node of the parse tree
+    # and the superclass of all other parse-tree nodes.
     class Node
+      # The child nodes of this node.
+      #
+      # @return [Array<Tree::Node>]
       attr_accessor :children
+
+      # The line of the document on which this node appeared.
+      #
+      # @return [Fixnum]
       attr_accessor :line
-      attr_accessor :filename
 
-      def initialize(style)
-        @style = style
+      # The name of the document on which this node appeared.
+      #
+      # @return [String]
+      attr_writer :filename
+
+      # The options hash for the node.
+      # See {file:SASS_REFERENCE.md#sass_options the Sass options documentation}.
+      #
+      # @return [Hash<Symbol, Object>]
+      attr_reader :options
+
+      def initialize
         @children = []
       end
 
+      # Sets the options hash for the node and all its children.
+      #
+      # @param options [Hash<Symbol, Object>] The options
+      # @see #options
+      def options=(options)
+        children.each {|c| c.options = options}
+        @options = options
+      end
+
+      # The name of the document on which this node appeared.
+      #
+      # @return [String]
+      def filename
+        @filename || @options[:filename]
+      end
+
+      # Appends a child to the node.
+      #
+      # @param child [Tree::Node] The child node
+      # @raise [Sass::SyntaxError] if `child` is invalid
+      # @see #invalid_child?
       def <<(child)
         if msg = invalid_child?(child)
           raise Sass::SyntaxError.new(msg, child.line)
@@ -17,27 +71,176 @@ module Sass
         @children << child
       end
 
+      # Return the last child node.
+      #
+      # We need this because {Tree::Node} duck types as an Array for {Sass::Engine}.
+      #
+      # @return [Tree::Node] The last child node
+      def last
+        children.last
+      end
+
+      # Compares this node and another object (only other {Tree::Node}s will be equal).
+      # This does a structural comparison;
+      # if the contents of the nodes and all the child nodes are equivalent,
+      # then the nodes are as well.
+      #
+      # Only static nodes need to override this.
+      #
+      # @param other [Object] The object to compare with
+      # @return [Boolean] Whether or not this node and the other object
+      #   are the same
+      # @see Sass::Tree
       def ==(other)
         self.class == other.class && other.children == children
       end
 
+      # Runs the dynamic Sass code *and* computes the CSS for the tree.
+      #
+      # @see #perform
+      # @see #to_s
+      def render
+        perform(Environment.new).to_s
+      end
+
+      # True if \{#to\_s} will return `nil`;
+      # that is, if the node shouldn't be rendered.
+      # Should only be called in a static tree.
+      #
+      # @return [Boolean]
+      def invisible?; false; end
+
+      # Computes the CSS corresponding to this Sass tree.
+      #
+      # Only static-node subclasses need to implement \{#to\_s}.
+      #
+      # This may return `nil`, but it will only do so if \{#invisible?} is true.
+      #
+      # @return [String, nil] The resulting CSS
+      # @raise [Sass::SyntaxError] if some element of the tree is invalid
+      # @see Sass::Tree
       def to_s
         result = String.new
         children.each do |child|
-          if child.is_a? AttrNode
-            raise SyntaxError.new('Attributes aren\'t allowed at the root of a document.', child.line)
+          if child.is_a? PropNode
+            raise Sass::SyntaxError.new('Properties aren\'t allowed at the root of a document.', child.line)
           else
-            result << "#{child.to_s(1)}" + (@style == :compressed ? '' : "\n")
+            next if child.invisible?
+            child_str = child.to_s(1)
+            result << child_str + (style == :compressed ? '' : "\n")
           end
         end
-        @style == :compressed ? result+"\n" : result[0...-1]
+        result.rstrip!
+        return "" if result.empty?
+        return result + "\n"
+      rescue Sass::SyntaxError => e; e.add_metadata(filename, line)
       end
 
-      private
+      # Runs the dynamic Sass code:
+      # mixins, variables, control directives, and so forth.
+      # This doesn't modify this node or any of its children.
+      #
+      # \{#perform} shouldn't be overridden directly;
+      # if you want to return a new node (or list of nodes),
+      # override \{#\_perform};
+      # if you want to destructively modify this node,
+      # override \{#perform!}.
+      #
+      # @param environment [Sass::Environment] The lexical environment containing
+      #   variable and mixin values
+      # @return [Tree::Node] The resulting tree of static nodes
+      # @raise [Sass::SyntaxError] if some element of the tree is invalid
+      # @see Sass::Tree
+      def perform(environment)
+        environment.options = @options if self.class == Tree::Node
+        _perform(environment)
+      rescue Sass::SyntaxError => e; e.add_metadata(filename, line)
+      end
+
+      # The output style. See {file:SASS_REFERENCE.md#sass_options the Sass options documentation}.
+      #
+      # @return [Symbol]
+      def style
+        @options[:style]
+      end
+
+      protected
+
+      # Runs any dynamic Sass code in this particular node.
+      # This doesn't modify this node or any of its children.
+      #
+      # @param environment [Sass::Environment] The lexical environment containing
+      #   variable and mixin values
+      # @return [Tree::Node, Array<Tree::Node>] The resulting static nodes
+      # @see #perform
+      # @see Sass::Tree
+      def _perform(environment)
+        node = dup
+        node.perform!(environment)
+        node
+      end
+
+      # Destructively runs dynamic Sass code in this particular node.
+      # This *does* modify this node,
+      # but will be run non-destructively by \{#\_perform\}.
+      #
+      # @param environment [Sass::Environment] The lexical environment containing
+      #   variable and mixin values
+      # @see #perform
+      def perform!(environment)
+        self.children = perform_children(Environment.new(environment))
+      end
+
+      # Non-destructively runs \{#perform} on all children of the current node.
+      #
+      # @param environment [Sass::Environment] The lexical environment containing
+      #   variable and mixin values
+      # @return [Array<Tree::Node>] The resulting static nodes
+      def perform_children(environment)
+        children.map {|c| c.perform(environment)}.flatten
+      end
+
+      # Replaces SassScript in a chunk of text (via `#{}`)
+      # with the resulting value.
+      #
+      # @param text [String] The text to interpolate
+      # @param environment [Sass::Environment] The lexical environment containing
+      #   variable and mixin values
+      # @return [String] The interpolated text
+      def interpolate(text, environment)
+        res = ''
+        rest = Haml::Shared.handle_interpolation text do |scan|
+          escapes = scan[2].size
+          res << scan.matched[0...-2 - escapes]
+          if escapes % 2 == 1
+            res << "\\" * (escapes - 1) << '#{'
+          else
+            res << "\\" * [0, escapes - 1].max
+            res << Script::Parser.new(scan, line, scan.pos - scan.matched_size, filename).
+              parse_interpolated.perform(environment).to_s
+          end
+        end
+        res + rest
+      end
+
+      # @see Haml::Shared.balance
+      # @raise [Sass::SyntaxError] if the brackets aren't balanced
+      def balance(*args)
+        res = Haml::Shared.balance(*args)
+        return res if res
+        raise Sass::SyntaxError.new("Unbalanced brackets.", line)
+      end
 
-      # This method should be overridden by subclasses to return an error message
-      # if the given child node is invalid,
-      # and false or nil otherwise.
+      # Returns an error message if the given child node is invalid,
+      # and false otherwise.
+      #
+      # By default, all child nodes are valid.
+      # This is expected to be overriden by subclasses
+      # for which some children are invalid.
+      #
+      # @param child [Tree::Node] A potential child node
+      # @return [Boolean, String] Whether or not the child node is valid,
+      #   as well as the error message to display if it is invalid
       def invalid_child?(child)
         false
       end