module Sass
# A namespace for nodes in the Sass parse tree.
#
# The Sass parse tree has three states: dynamic, static Sass, and static CSS.
#
# When it's first parsed, a Sass document is in the dynamic state.
# It has nodes for mixin definitions and `@for` loops and so forth,
# in addition to nodes for CSS rules and properties.
# Nodes that only appear in this state are called **dynamic nodes**.
#
# {Tree::Node#perform} returns a static Sass tree, which is different.
# It still has nodes for CSS rules and properties
# but it doesn't have any dynamic-generation-related nodes.
# The nodes in this state are in the same structure as the Sass document:
# rules and properties are nested beneath one another.
# Nodes that can be in this state or in the dynamic state
# are called **static nodes**.
#
# {Tree::Node#cssize} then returns a static CSS tree.
# This is like a static Sass tree,
# but the structure exactly mirrors that of the generated CSS.
# Rules and properties can't be nested beneath one another in this state.
#
# Finally, {Tree::Node#to_s} can be called on a static CSS tree
# to get the actual CSS code as a string.
module Tree
# The abstract superclass of all parse-tree nodes.
class Node
include Enumerable
# The child nodes of this node.
#
# @return [Array<Tree::Node>]
attr_accessor :children
# Whether or not this node has child nodes.
# This may be true even when \{#children} is empty,
# in which case this node has an empty block (e.g. `{}`).
#
# @return [Boolean]
attr_accessor :has_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 {file:SASS_REFERENCE.md#sass_options the Sass options documentation}.
#
# @return [{Symbol => Object}]
attr_reader :options
def initialize
@children = []
end
# Sets the options hash for the node and all its children.
#
# @param options [{Symbol => Object}] The options
# @see #options
def options=(options)
children.each {|c| c.options = options}
@options = options
end
# @private
def children=(children)
self.has_children ||= !children.empty?
@children = children
end
# The name of the document on which this node appeared.
#
# @return [String]
def filename
@filename || (@options && @options[:filename])
end
# Appends a child to the node.
#
# @param child [Tree::Node, Array<Tree::Node>] The child node or nodes
# @raise [Sass::SyntaxError] if `child` is invalid
# @see #invalid_child?
def <<(child)
return if child.nil?
if child.is_a?(Array)
child.each {|c| self << c}
else
check_child! child
self.has_children = true
@children << child
end
end
# Raises an error if the given child node is invalid.
#
# @param child [Tree::Node] The child node
# @raise [Sass::SyntaxError] if `child` is invalid
# @see #invalid_child?
def check_child!(child)
if msg = invalid_child?(child)
raise Sass::SyntaxError.new(msg, :line => child.line)
end
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
# 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
# The output style. See {file:SASS_REFERENCE.md#sass_options the Sass options documentation}.
#
# @return [Symbol]
def style
@options[:style]
end
# Computes the CSS corresponding to this static CSS tree.
#
# \{#to_s} shouldn't be overridden directly; instead, override \{#\_to\_s}.
# Only static-node subclasses need to implement \{#to\_s}.
#
# This may return `nil`, but it will only do so if \{#invisible?} is true.
#
# @param args [Array] Passed on to \{#\_to\_s}
# @return [String, nil] The resulting CSS
# @see Sass::Tree
def to_s(opts = nil)
_to_s(opts)
rescue Sass::SyntaxError => e
e.modify_backtrace(:filename => filename, :line => line)
raise e
end
# Converts a static CSS tree (e.g. the output of \{#cssize})
# into another static CSS tree,
# with the given extensions applied to all relevant {RuleNode}s.
#
# @todo Link this to the reference documentation on `@extend`
# when such a thing exists.
#
# @param extends [Sass::Util::SubsetMap{Selector::Simple => Selector::Sequence}]
# The extensions to perform on this tree
# @return [Tree::Node] The resulting tree of static CSS nodes.
# @raise [Sass::SyntaxError] Only if there's a programmer error
# and this is not a static CSS tree
def do_extend(extends)
node = dup
node.children = children.map {|c| c.do_extend(extends)}
node
rescue Sass::SyntaxError => e
e.modify_backtrace(:filename => filename, :line => line)
raise e
end
# Converts a static Sass tree (e.g. the output of \{#perform})
# into a static CSS tree.
#
# \{#cssize} shouldn't be overridden directly;
# instead, override \{#\_cssize} or \{#cssize!}.
#
# @param extends [Sass::Util::SubsetMap{Selector::Simple => Selector::Sequence}]
# The extensions defined for this tree
# @param parent [Node, nil] The parent node of this node.
# This should only be non-nil if the parent is the same class as this node
# @return [Tree::Node] The resulting tree of static nodes
# @raise [Sass::SyntaxError] if some element of the tree is invalid
# @see Sass::Tree
def cssize(extends, parent = nil)
_cssize(extends, (parent if parent.class == self.class))
rescue Sass::SyntaxError => e
e.modify_backtrace(:filename => filename, :line => line)
raise e
end
# Converts a dynamic tree into a static Sass tree.
# That is, 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;
# instead, override \{#\_perform} or \{#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)
_perform(environment)
rescue Sass::SyntaxError => e
e.modify_backtrace(:filename => filename, :line => line)
raise e
end
# Iterates through each node in the tree rooted at this node
# in a pre-order walk.
#
# @yield node
# @yieldparam node [Node] a node in the tree
def each(&block)
yield self
children.each {|c| c.each(&block)}
end
# 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 [{Symbol => Object}] An options hash (see {Sass::CSS#initialize})
# @return [String] The Sass code corresponding to the node
def to_sass(tabs = 0, opts = {})
to_src(tabs, opts, :sass)
end
# Converts a node to SCSS code that will generate it.
#
# @param tabs [Fixnum] The amount of tabulation to use for the SCSS code
# @param opts [{Symbol => Object}] An options hash (see {Sass::CSS#initialize})
# @return [String] The Sass code corresponding to the node
def to_scss(tabs = 0, opts = {})
to_src(tabs, opts, :scss)
end
# Names of options that are saved when the node is serialized and cached.
SAVED_OPTIONS = [:importer]
# Ensures that only {SAVED_OPTIONS} get saved.
def _around_dump
old_options = @options
old_children = @children
@options = {}
SAVED_OPTIONS.each do |opt|
@options[opt] = old_options[opt]
end
@options = Sass::Util.dump(@options)
@children = Sass::Util.dump(@children)
yield
ensure
@options = old_options
@children = old_children
end
# Ensures that only {SAVED_OPTIONS} get saved.
def _after_load
@options = Sass::Util.load(@options)
@children = Sass::Util.load(@children)
end
protected
# Computes the CSS corresponding to this particular Sass node.
#
# This method should never raise {Sass::SyntaxError}s.
# Such errors will not be properly annotated with Sass backtrace information.
# All error conditions should be checked in earlier transformations,
# such as \{#cssize} and \{#perform}.
#
# @param args [Array] ignored
# @return [String, nil] The resulting CSS
# @see #to_s
# @see Sass::Tree
def _to_s
Sass::Util.abstract(self)
end
# Converts this static Sass node into a static CSS node,
# returning the new node.
# This doesn't modify this node or any of its children.
#
# @param extends [Sass::Util::SubsetMap{Selector::Simple => Selector::Sequence}]
# The extensions defined for this tree
# @param parent [Node, nil] The parent node of this node.
# This should only be non-nil if the parent is the same class as this node
# @return [Tree::Node, Array<Tree::Node>] The resulting static CSS nodes
# @raise [Sass::SyntaxError] if some element of the tree is invalid
# @see #cssize
# @see Sass::Tree
def _cssize(extends, parent)
node = dup
node.cssize!(extends, parent)
node
end
# Destructively converts this static Sass node into a static CSS node.
# This *does* modify this node,
# but will be run non-destructively by \{#\_cssize\}.
#
# @param extends [Sass::Util::SubsetMap{Selector::Simple => Selector::Sequence}]
# The extensions defined for this tree
# @param parent [Node, nil] The parent node of this node.
# This should only be non-nil if the parent is the same class as this node
# @see #cssize
def cssize!(extends, parent)
self.children = children.map {|c| c.cssize(extends, self)}.flatten
end
# 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
# with the resulting value.
#
# @param text [Array<String, Sass::Script::Node>] The text to interpolate
# @param environment [Sass::Environment] The lexical environment containing
# variable and mixin values
# @return [String] The interpolated text
def run_interp(text, environment)
text.map do |r|
next r if r.is_a?(String)
val = r.perform(environment)
# Interpolated strings should never render with quotes
next val.value if val.is_a?(Sass::Script::String)
val.to_s
end.join.strip
end
# @see Sass::Shared.balance
# @raise [Sass::SyntaxError] if the brackets aren't balanced
def balance(*args)
res = Sass::Shared.balance(*args)
return res if res
raise Sass::SyntaxError.new("Unbalanced brackets.", :line => line)
end
# Returns an error message if the given child node is invalid,
# and false otherwise.
#
# By default, all child nodes except those only allowed under specific nodes
# ({Tree::MixinDefNode}, {Tree::ImportNode}, {Tree::ExtendNode}) 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)
case child
when Tree::MixinDefNode
"Mixins may only be defined at the root of a document."
when Tree::ImportNode
"Import directives may only be used at the root of a document."
when Tree::ExtendNode
"Extend directives may only be used within rules."
end
end
# Converts a node to Sass or SCSS code that will generate it.
#
# This method is called by the default \{#to\_sass} and \{#to\_scss} methods,
# so that the same code can be used for both with minor variations.
#
# @param tabs [Fixnum] The amount of tabulation to use for the SCSS code
# @param opts [{Symbol => Object}] An options hash (see {Sass::CSS#initialize})
# @param fmt [Symbol] `:sass` or `:scss`
# @return [String] The Sass or SCSS code corresponding to the node
def to_src(tabs, opts, fmt)
Sass::Util.abstract(self)
end
# Converts the children of this node to a Sass or SCSS string.
# This will return the trailing newline for the previous line,
# including brackets if this is SCSS.
#
# @param tabs [Fixnum] The amount of tabulation to use for the Sass code
# @param opts [{Symbol => Object}] An options hash (see {Sass::CSS#initialize})
# @param fmt [Symbol] `:sass` or `:scss`
# @return [String] The Sass or SCSS code corresponding to the children
def children_to_src(tabs, opts, fmt)
return fmt == :sass ? "\n" : " {}\n" if children.empty?
(fmt == :sass ? "\n" : " {\n") +
children.map {|c| c.send("to_#{fmt}", tabs + 1, opts)}.join.rstrip +
(fmt == :sass ? "\n" : " }\n")
end
# Converts a selector to a Sass or SCSS string.
#
# @param sel [Array<String, Sass::Script::Node>] The selector to convert
# @param tabs [Fixnum] The indentation of the selector
# @param opts [{Symbol => Object}] An options hash (see {Sass::CSS#initialize})
# @param fmt [Symbol] `:sass` or `:scss`
# @return [String] The Sass or SCSS code corresponding to the selector
def selector_to_src(sel, tabs, opts, fmt)
fmt == :sass ? selector_to_sass(sel, opts) : selector_to_scss(sel, tabs, opts)
end
# Converts a selector to a Sass string.
#
# @param sel [Array<String, Sass::Script::Node>] The selector to convert
# @param opts [{Symbol => Object}] An options hash (see {Sass::CSS#initialize})
# @return [String] The Sass code corresponding to the selector
def selector_to_sass(sel, opts)
sel.map do |r|
if r.is_a?(String)
r.gsub(/(,[ \t]*)?\n\s*/) {$1 ? $1 + "\n" : " "}
else
"\#{#{r.to_sass(opts)}}"
end
end.join
end
# Converts a selector to a SCSS string.
#
# @param sel [Array<String, Sass::Script::Node>] The selector to convert
# @param tabs [Fixnum] The indentation of the selector
# @param opts [{Symbol => Object}] An options hash (see {Sass::CSS#initialize})
# @return [String] The SCSS code corresponding to the selector
def selector_to_scss(sel, tabs, opts)
sel.map {|r| r.is_a?(String) ? r : "\#{#{r.to_sass(opts)}}"}.
join.gsub(/^[ \t]*/, ' ' * tabs)
end
# Convert any underscores in a string into hyphens,
# but only if the `:dasherize` option is set.
#
# @param s [String] The string to convert
# @param opts [{Symbol => Object}] The options hash
# @return [String] The converted string
def dasherize(s, opts)
if opts[:dasherize]
s.gsub('_', '-')
else
s
end
end
# Returns a semicolon if this is SCSS, or an empty string if this is Sass.
#
# @param fmt [Symbol] `:sass` or `:scss`
# @return [String] A semicolon or the empty string
def semi(fmt)
fmt == :sass ? "" : ";"
end
end
end
end