haml-edge 2.1.21 → 2.1.22

data/lib/sass/script.rb

@@ -1,4 +1,5 @@
 require 'strscan'
+require 'sass/script/node'
 require 'sass/script/variable'
 require 'sass/script/funcall'
 require 'sass/script/operation'
@@ -6,22 +7,43 @@ require 'sass/script/literal'
 require 'sass/script/parser'
 
 module Sass
-  # This module contains various SassScript-related functionality.
+  # SassScript is code that's embedded in Sass documents
+  # to allow for property values to be computed from variables.
+  #
+  # This module contains code that handles the parsing and evaluation of SassScript.
   module Script
-    # :stopdoc:
     # The character that begins a variable.
     VARIABLE_CHAR = ?!
 
-    # The regular expression used to parse variables
+    # The regular expression used to parse variables.
     MATCH = /^!([a-zA-Z_]\w*)\s*((?:\|\|)?=)\s*(.+)/
 
-    # The regular expression used to validate variables without matching
+    # The regular expression used to validate variables without matching.
     VALIDATE = /^![a-zA-Z_]\w*$/
 
+    # Parses and evaluates a string of SassScript.
+    #
+    # @param value [String] The SassScript
+    # @param line [Fixnum] The number of the line on which the SassScript appeared.
+    #   Used for error reporting
+    # @param offset [Fixnum] The number of characters in on `line` that the SassScript started.
+    #   Used for error reporting
+    # @param environment [Sass::Environment] The environment in which to evaluate the SassScript
+    # @return [String] The string result of evaluating the SassScript
     def self.resolve(value, line, offset, environment)
       parse(value, line, offset).perform(environment).to_s
     end
 
+    # Parses a string of SassScript
+    #
+    # @param value [String] The SassScript
+    # @param line [Fixnum] The number of the line on which the SassScript appeared.
+    #   Used for error reporting
+    # @param offset [Fixnum] The number of characters in on `line` that the SassScript started.
+    #   Used for error reporting
+    # @param filename [String] The path to the file in which the SassScript appeared.
+    #   Used for error reporting
+    # @return [Script::Node] The root node of the parse tree
     def self.parse(value, line, offset, filename = nil)
       Parser.parse(value, line, offset, filename)
     rescue Sass::SyntaxError => e
@@ -33,6 +55,5 @@ module Sass
       e.sass_line = line
       raise e
     end
-    # :startdoc:
   end
 end

data/lib/sass/tree/attr_node.rb

@@ -1,7 +1,23 @@
 module Sass::Tree
+  # A static node reprenting a CSS property.
+  #
+  # @see Sass::Tree
   class AttrNode < Node
-    attr_accessor :name, :value
-    
+    # The name of the property.
+    #
+    # @return [String]
+    attr_accessor :name
+
+    # The value of the property,
+    # either a plain string or a SassScript parse tree.
+    #
+    # @return [String, Script::Node]
+    attr_accessor :value
+
+    # @param name [String] See \{#name}
+    # @param value [String] See \{#value}
+    # @param attr_syntax [Symbol] `:new` if this property uses `a: b`-style syntax,
+    #   `:old` if it uses `:a b`-style syntax
     def initialize(name, value, attr_syntax)
       @name = name
       @value = value
@@ -9,10 +25,21 @@ module Sass::Tree
       super()
     end
 
+    # Compares the names and values of two properties.
+    #
+    # @param other [Object] The object to compare with
+    # @return [Boolean] Whether or not this node and the other object
+    #   are the same
     def ==(other)
       self.class == other.class && name == other.name && value == other.value && super
     end
 
+    # Computes the CSS for the property.
+    #
+    # @param tabs [Fixnum] The level of indentation for the CSS
+    # @param parent_name [String] The name of the parent property (e.g. `text`) or nil
+    # @return [String] The resulting CSS
+    # @raise [Sass::SyntaxError] if the attribute uses invalid syntax
     def to_s(tabs, parent_name = nil)
       if @options[:attribute_syntax] == :normal && @attr_syntax == :new
         raise Sass::SyntaxError.new("Illegal attribute syntax: can't use alternate syntax when :attribute_syntax => :normal is set.")
@@ -50,23 +77,33 @@ module Sass::Tree
     end
 
     protected
-    
+
+    # Runs any SassScript that may be embedded in the property.
+    #
+    # @param environment [Sass::Environment] The lexical environment containing
+    #   variable and mixin values
     def perform!(environment)
       @name = interpolate(@name, environment)
       @value = @value.is_a?(String) ? interpolate(@value, environment) : @value.perform(environment).to_s
       super
     end
 
-    private
-
-    def declaration
-      @attr_syntax == :new ? "#{name}: #{value}" : ":#{name} #{value}"
-    end
-
+    # Returns an error message if the given child node is invalid,
+    # and false otherwise.
+    #
+    # {AttrNode} only allows other {AttrNode}s and {CommentNode}s as children.
+    # @param child [Tree::Node] A potential child node
+    # @return [String] An error message if the child is invalid, or nil otherwise
     def invalid_child?(child)
       if !child.is_a?(AttrNode) && !child.is_a?(CommentNode)
         "Illegal nesting: Only attributes may be nested beneath attributes."
       end
     end
+
+    private
+
+    def declaration
+      @attr_syntax == :new ? "#{name}: #{value}" : ":#{name} #{value}"
+    end
   end
 end

data/lib/sass/tree/comment_node.rb

@@ -1,11 +1,27 @@
 require 'sass/tree/node'
 
 module Sass::Tree
+  # A static node representing a Sass comment (silent or loud).
+  #
+  # @see Sass::Tree
   class CommentNode < Node
+    # The lines of text nested beneath the comment.
+    #
+    # @return [Array<Sass::Engine::Line>]
     attr_accessor :lines
+
+    # The text on the same line as the comment starter.
+    #
+    # @return [String]
     attr_accessor :value
+
+    # Whether or not the comment is silent (that is, doesn't output to CSS).
+    #
+    # @return [Boolean]
     attr_accessor :silent
 
+    # @param value [String] See \{#value}
+    # @param silent [Boolean] See \{#silent}
     def initialize(value, silent)
       @lines = []
       @value = value[2..-1].strip
@@ -13,11 +29,25 @@ module Sass::Tree
       super()
     end
 
+    # Compares the contents of two comments.
+    #
+    # @param other [Object] The object to compare with
+    # @return [Boolean] Whether or not this node and the other object
+    #   are the same
     def ==(other)
       self.class == other.class && value == other.value && silent == other.silent && lines == other.lines
     end
 
-    def to_s(tabs = 0, parent_name = nil)
+    # Computes the CSS for the comment.
+    #
+    # Returns `nil` if this is a silent comment
+    # or the current style doesn't render comments.
+    #
+    # @overload to_s(tabs = 0)
+    # @param tabs [Fixnum] The level of indentation for the CSS
+    # @return [String, nil] The resulting CSS
+    # @see #invisible?
+    def to_s(tabs = 0, _ = nil)
       return if invisible?
 
       spaces = '  ' * (tabs - 1)
@@ -25,12 +55,22 @@ module Sass::Tree
         map{|l| l.sub(%r{ ?\*/ *$},'')}.join(style == :compact ? ' ' : "\n#{spaces} * ") + " */"
     end
 
+    # Returns `true` if this is a silent comment
+    # or the current style doesn't render comments.
+    #
+    # @return [Boolean]
     def invisible?
       style == :compressed || @silent
     end
 
     protected
 
+    # Removes this node from the tree if it's a silent comment.
+    #
+    # @param environment [Sass::Environment] The lexical environment containing
+    #   variable and mixin values
+    # @return [Tree::Node, Array<Tree::Node>] The resulting static nodes
+    # @see Sass::Tree
     def _perform(environment)
       return [] if @silent
       self

data/lib/sass/tree/debug_node.rb

@@ -1,6 +1,10 @@
 module Sass
   module Tree
+    # A dynamic node representing a Sass `@debug` statement.
+    #
+    # @see Sass::Tree
     class DebugNode < Node
+      # @param expr [Script::Node] The expression to print
       def initialize(expr)
         @expr = expr
         super()
@@ -8,6 +12,10 @@ module Sass
 
       protected
 
+      # Prints the expression to STDERR.
+      #
+      # @param environment [Sass::Environment] The lexical environment containing
+      #   variable and mixin values
       def _perform(environment)
         res = @expr.perform(environment)
         if filename

data/lib/sass/tree/directive_node.rb

@@ -1,12 +1,32 @@
 module Sass::Tree
+  # A static node representing an unproccessed Sass `@`-directive.
+  # Directives known to Sass, like `@for` and `@debug`,
+  # are handled by their own nodes;
+  # only CSS directives like `@media` and `@font-face` become {DirectiveNode}s.
+  #
+  # `@import` is a bit of a weird case;
+  # if it's importing a Sass file,
+  # it becomes a {FileNode},
+  # but if it's importing a plain CSS file,
+  # it becomes a {DirectiveNode}.
+  #
+  # @see Sass::Tree
   class DirectiveNode < Node
+    # The text of the directive, `@` and all.
+    #
+    # @return [String]
     attr_accessor :value
 
+    # @param value [String] See \{#value}
     def initialize(value)
       @value = value
       super()
     end
 
+    # Computes the CSS for the directive.
+    #
+    # @param tabs [Fixnum] The level of indentation for the CSS
+    # @return [String] The resulting CSS
     def to_s(tabs)
       if children.empty?
         value + ";"

data/lib/sass/tree/file_node.rb

@@ -1,11 +1,18 @@
 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
@@ -17,6 +24,11 @@ module Sass
 
       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)

data/lib/sass/tree/for_node.rb

@@ -1,7 +1,15 @@
 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
@@ -12,6 +20,13 @@ module Sass::Tree
 
     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_i
       to = @to.perform(environment).to_i

data/lib/sass/tree/if_node.rb

@@ -1,15 +1,30 @@
 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
@@ -22,6 +37,13 @@ module Sass::Tree
 
     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

data/lib/sass/tree/mixin_def_node.rb

@@ -1,14 +1,25 @@
 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
 
-      private
+      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))
         []

data/lib/sass/tree/mixin_node.rb

@@ -1,7 +1,12 @@
 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
@@ -10,6 +15,14 @@ module Sass::Tree
 
     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)
 

data/lib/sass/tree/node.rb

@@ -1,24 +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
+
+      # The name of the document on which this node appeared.
+      #
+      # @return [String]
       attr_writer :filename
+
+      # The options hash for the node.
+      # See [the Sass options documentation](../../Sass.html#sass_options).
+      #
+      # @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)
@@ -26,21 +71,54 @@ module Sass
         @children << child
       end
 
-      # We need this because Node duck types as an Array in engine.rb
+      # 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|
@@ -56,32 +134,77 @@ module Sass
       rescue Sass::SyntaxError => e; e.add_metadata(filename, line)
       end
 
+      # Runs the dynamic Sass code:
+      # mixins, variables, control structures, 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 [the Sass options documentation](../../Sass.html#output_style).
+      #
+      # @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|
@@ -98,17 +221,24 @@ module Sass
         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
 
-      private
-
-      # 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