[Sass] Convert Sass::Tree::Node docs to YARD.
This commit is contained in:
parent
de949e134a
commit
1bb9438ad6
|
@ -1,16 +1,51 @@
|
||||||
module Sass
|
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
|
module Tree
|
||||||
|
# This class doubles as the root node of the parse tree
|
||||||
|
# and the superclass of all other parse-tree nodes.
|
||||||
class Node
|
class Node
|
||||||
|
# The child nodes of this node.
|
||||||
|
#
|
||||||
|
# @return [Array<Node>]
|
||||||
attr_accessor :children
|
attr_accessor :children
|
||||||
|
|
||||||
|
# The line of the document on which this node appeared.
|
||||||
|
#
|
||||||
|
# @return [Fixnum]
|
||||||
attr_accessor :line
|
attr_accessor :line
|
||||||
|
|
||||||
|
# The name of the document on which this node appeared.
|
||||||
|
#
|
||||||
|
# @return [String]
|
||||||
attr_accessor :filename
|
attr_accessor :filename
|
||||||
|
|
||||||
|
# @param options [Hash<Symbol, Object>] An options hash;
|
||||||
|
# see [the Sass options documentation](../../Sass.html#sass_options)
|
||||||
def initialize(options)
|
def initialize(options)
|
||||||
@options = options
|
@options = options
|
||||||
@style = options[:style]
|
@style = options[:style]
|
||||||
@children = []
|
@children = []
|
||||||
end
|
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)
|
def <<(child)
|
||||||
if msg = invalid_child?(child)
|
if msg = invalid_child?(child)
|
||||||
raise Sass::SyntaxError.new(msg, child.line)
|
raise Sass::SyntaxError.new(msg, child.line)
|
||||||
|
@ -18,15 +53,34 @@ module Sass
|
||||||
@children << child
|
@children << child
|
||||||
end
|
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
|
def last
|
||||||
children.last
|
children.last
|
||||||
end
|
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)
|
def ==(other)
|
||||||
self.class == other.class && other.children == children
|
self.class == other.class && other.children == children
|
||||||
end
|
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
|
def to_s
|
||||||
result = String.new
|
result = String.new
|
||||||
children.each do |child|
|
children.each do |child|
|
||||||
|
@ -41,6 +95,21 @@ module Sass
|
||||||
@style == :compressed ? result+"\n" : result[0...-1]
|
@style == :compressed ? result+"\n" : result[0...-1]
|
||||||
end
|
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)
|
def perform(environment)
|
||||||
_perform(environment)
|
_perform(environment)
|
||||||
rescue Sass::SyntaxError => e
|
rescue Sass::SyntaxError => e
|
||||||
|
@ -50,20 +119,47 @@ module Sass
|
||||||
|
|
||||||
protected
|
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<Node>] The resulting static nodes
|
||||||
|
# @see #perform
|
||||||
|
# @see Sass::Tree
|
||||||
def _perform(environment)
|
def _perform(environment)
|
||||||
node = dup
|
node = dup
|
||||||
node.perform!(environment)
|
node.perform!(environment)
|
||||||
node
|
node
|
||||||
end
|
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)
|
def perform!(environment)
|
||||||
self.children = perform_children(Environment.new(environment))
|
self.children = perform_children(Environment.new(environment))
|
||||||
end
|
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<Node>] The resulting static nodes
|
||||||
def perform_children(environment)
|
def perform_children(environment)
|
||||||
children.map {|c| c.perform(environment)}.flatten
|
children.map {|c| c.perform(environment)}.flatten
|
||||||
end
|
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)
|
def interpolate(text, environment)
|
||||||
res = ''
|
res = ''
|
||||||
rest = Haml::Shared.handle_interpolation text do |scan|
|
rest = Haml::Shared.handle_interpolation text do |scan|
|
||||||
|
@ -80,17 +176,24 @@ module Sass
|
||||||
res + rest
|
res + rest
|
||||||
end
|
end
|
||||||
|
|
||||||
|
# @see Haml::Shared.balance
|
||||||
|
# @raise [Sass::SyntaxError] if the brackets aren't balanced
|
||||||
def balance(*args)
|
def balance(*args)
|
||||||
res = Haml::Shared.balance(*args)
|
res = Haml::Shared.balance(*args)
|
||||||
return res if res
|
return res if res
|
||||||
raise Sass::SyntaxError.new("Unbalanced brackets.", line)
|
raise Sass::SyntaxError.new("Unbalanced brackets.", line)
|
||||||
end
|
end
|
||||||
|
|
||||||
private
|
# Returns an error message if the given child node is invalid,
|
||||||
|
# and false otherwise.
|
||||||
# This method should be overridden by subclasses to return an error message
|
#
|
||||||
# if the given child node is invalid,
|
# By default, all child nodes are valid.
|
||||||
# and false or nil otherwise.
|
# 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)
|
def invalid_child?(child)
|
||||||
false
|
false
|
||||||
end
|
end
|
||||||
|
|
Loading…
Reference in New Issue