From 1bb9438ad69b6780cb71b20ae11db0699feb5155 Mon Sep 17 00:00:00 2001 From: Nathan Weizenbaum Date: Sat, 25 Apr 2009 01:16:36 -0700 Subject: [PATCH] [Sass] Convert Sass::Tree::Node docs to YARD. --- lib/sass/tree/node.rb | 115 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 109 insertions(+), 6 deletions(-) diff --git a/lib/sass/tree/node.rb b/lib/sass/tree/node.rb index d418dee3..c4bd0118 100644 --- a/lib/sass/tree/node.rb +++ b/lib/sass/tree/node.rb @@ -1,16 +1,51 @@ 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, {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] 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_accessor :filename + # @param options [Hash] An options hash; + # see [the Sass options documentation](../../Sass.html#sass_options) def initialize(options) @options = options @style = options[:style] @children = [] end + # Appends a child to the node. + # + # @param child [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) @@ -18,15 +53,34 @@ 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 {Node} duck types as an Array for {Sass::Engine}. + # + # @return [Node] The last child node def last children.last end + # Compares this node and another object (only other {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. + # + # @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 && other.children == children end + # Computes the CSS corresponding to this Sass tree. + # + # Only static-node subclasses need to implement \{#to\_s}. + # + # @return [String] 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| @@ -41,6 +95,21 @@ module Sass @style == :compressed ? result+"\n" : result[0...-1] 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 [Node] The resulting tree of static nodes + # @raise [Sass::SyntaxError] if some element of the tree is invalid + # @see Sass::Tree def perform(environment) _perform(environment) rescue Sass::SyntaxError => e @@ -50,20 +119,47 @@ module Sass 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 [Node, Array] 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] 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| @@ -80,17 +176,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 [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