Class | Sass::Engine |
In: |
lib/sass/engine.rb
|
Parent: | Object |
This class handles the parsing and compilation of the Sass template. Example usage:
template = File.load('stylesheets/sassy.sass') sass_engine = Sass::Engine.new(template) output = sass_engine.render puts output
PROPERTY_CHAR | = | ?: | The character that begins a CSS property. | |
SCRIPT_CHAR | = | ?= | The character that designates that a property should be assigned to a SassScript expression. | |
COMMENT_CHAR | = | ?/ | The character that designates the beginning of a comment, either Sass or CSS. | |
SASS_COMMENT_CHAR | = | ?/ | The character that follows the general COMMENT_CHAR and designates a Sass comment, which is not output as a CSS comment. | |
CSS_COMMENT_CHAR | = | ?* | The character that follows the general COMMENT_CHAR and designates a CSS comment, which is embedded in the CSS document. | |
DIRECTIVE_CHAR | = | ?@ | The character used to denote a compiler directive. | |
ESCAPE_CHAR | = | ?\\ | Designates a non-parsed rule. | |
MIXIN_DEFINITION_CHAR | = | ?= | Designates block as mixin definition rather than CSS rules to output | |
MIXIN_INCLUDE_CHAR | = | ?+ | Includes named mixin declared using MIXIN_DEFINITION_CHAR | |
PROPERTY_NEW_MATCHER | = | /^[^\s:"\[]+\s*[=:](\s|$)/ | The regex that matches properties of the form `name: prop`. | |
PROPERTY_NEW | = | /^([^\s=:"]+)(\s*=|:)(?:\s+|$)(.*)/ | The regex that matches and extracts data from properties of the form `name: prop`. | |
PROPERTY_OLD | = | /^:([^\s=:"]+)\s*(=?)(?:\s+|$)(.*)/ | The regex that matches and extracts data from properties of the form `:name prop`. | |
DEFAULT_OPTIONS | = | { :style => :nested, :load_paths => ['.'], :cache => true, :cache_location => './.sass-cache', }.freeze | The default options for Sass::Engine. |
@param template [String] The Sass template. @param options [{Symbol => Object}] An options hash;
see {file:SASS_REFERENCE.md#sass_options the Sass options documentation}
# File lib/sass/engine.rb, line 131 131: def initialize(template, options={}) 132: @options = DEFAULT_OPTIONS.merge(options.reject {|k, v| v.nil?}) 133: @template = template 134: 135: # Backwards compatibility 136: @options[:property_syntax] ||= @options[:attribute_syntax] 137: case @options[:property_syntax] 138: when :alternate; @options[:property_syntax] = :new 139: when :normal; @options[:property_syntax] = :old 140: end 141: end
Render the template to CSS.
@return [String] The CSS @raise [Sass::SyntaxError] if there‘s an error in the document
# File lib/sass/engine.rb, line 147 147: def render 148: to_tree.render 149: end
Parses the document into its parse tree.
@return [Sass::Tree::Node] The root of the parse tree. @raise [Sass::SyntaxError] if there‘s an error in the document
# File lib/sass/engine.rb, line 157 157: def to_tree 158: root = Tree::Node.new 159: append_children(root, tree(tabulate(@template)).first, true) 160: root.options = @options 161: root 162: rescue SyntaxError => e; e.add_metadata(@options[:filename], @line) 163: end
# File lib/sass/engine.rb, line 250 250: def append_children(parent, children, root) 251: continued_rule = nil 252: children.each do |line| 253: child = build_tree(parent, line, root) 254: 255: if child.is_a?(Tree::RuleNode) && child.continued? 256: raise SyntaxError.new("Rules can't end in commas.", child.line) unless child.children.empty? 257: if continued_rule 258: continued_rule.add_rules child 259: else 260: continued_rule = child 261: end 262: next 263: end 264: 265: if continued_rule 266: raise SyntaxError.new("Rules can't end in commas.", continued_rule.line) unless child.is_a?(Tree::RuleNode) 267: continued_rule.add_rules child 268: continued_rule.children = child.children 269: continued_rule, child = nil, continued_rule 270: end 271: 272: check_for_no_children(child) 273: validate_and_append_child(parent, child, line, root) 274: end 275: 276: raise SyntaxError.new("Rules can't end in commas.", continued_rule.line) if continued_rule 277: 278: parent 279: end
# File lib/sass/engine.rb, line 229 229: def build_tree(parent, line, root = false) 230: @line = line.index 231: node_or_nodes = parse_line(parent, line, root) 232: 233: Array(node_or_nodes).each do |node| 234: # Node is a symbol if it's non-outputting, like a variable assignment 235: next unless node.is_a? Tree::Node 236: 237: node.line = line.index 238: node.filename = line.filename 239: 240: if node.is_a?(Tree::CommentNode) 241: node.lines = line.children 242: else 243: append_children(node, line.children, false) 244: end 245: end 246: 247: node_or_nodes 248: end
# File lib/sass/engine.rb, line 299 299: def check_for_no_children(node) 300: return unless node.is_a?(Tree::RuleNode) && node.children.empty? 301: warning = (node.rules.size == 1) ? "WARNING on line \#{node.line}\#{\" of \#{node.filename}\" if node.filename}:\nSelector \#{node.rules.first.inspect} doesn't have any properties and will not be rendered.\n" : "\nWARNING on line \#{node.line}\#{\" of \#{node.filename}\" if node.filename}:\nSelector\n \#{node.rules.join(\"\\n \")}\ndoesn't have any properties and will not be rendered.\n" 302: 303: warn(warning.strip) 304: end
# File lib/sass/engine.rb, line 378 378: def parse_comment(line) 379: if line[1] == CSS_COMMENT_CHAR || line[1] == SASS_COMMENT_CHAR 380: Tree::CommentNode.new(line, line[1] == SASS_COMMENT_CHAR) 381: else 382: Tree::RuleNode.new(line) 383: end 384: end
# File lib/sass/engine.rb, line 386 386: def parse_directive(parent, line, root) 387: directive, whitespace, value = line.text[1..-1].split(/(\s+)/, 2) 388: offset = directive.size + whitespace.size + 1 if whitespace 389: 390: # If value begins with url( or ", 391: # it's a CSS @import rule and we don't want to touch it. 392: if directive == "import" && value !~ /^(url\(|")/ 393: raise SyntaxError.new("Illegal nesting: Nothing may be nested beneath import directives.", @line + 1) unless line.children.empty? 394: value.split(/,\s*/).map {|f| Tree::ImportNode.new(f)} 395: elsif directive == "for" 396: parse_for(line, root, value) 397: elsif directive == "else" 398: parse_else(parent, line, value) 399: elsif directive == "while" 400: raise SyntaxError.new("Invalid while directive '@while': expected expression.") unless value 401: Tree::WhileNode.new(parse_script(value, :offset => offset)) 402: elsif directive == "if" 403: raise SyntaxError.new("Invalid if directive '@if': expected expression.") unless value 404: Tree::IfNode.new(parse_script(value, :offset => offset)) 405: elsif directive == "debug" 406: raise SyntaxError.new("Invalid debug directive '@debug': expected expression.") unless value 407: raise SyntaxError.new("Illegal nesting: Nothing may be nested beneath debug directives.", @line + 1) unless line.children.empty? 408: offset = line.offset + line.text.index(value).to_i 409: Tree::DebugNode.new(parse_script(value, :offset => offset)) 410: else 411: Tree::DirectiveNode.new(line.text) 412: end 413: end
# File lib/sass/engine.rb, line 435 435: def parse_else(parent, line, text) 436: previous = parent.last 437: raise SyntaxError.new("@else must come after @if.") unless previous.is_a?(Tree::IfNode) 438: 439: if text 440: if text !~ /^if\s+(.+)/ 441: raise SyntaxError.new("Invalid else directive '@else #{text}': expected 'if <expr>'.", @line) 442: end 443: expr = parse_script($1, :offset => line.offset + line.text.index($1)) 444: end 445: 446: node = Tree::IfNode.new(expr) 447: append_children(node, line.children, false) 448: previous.add_else node 449: nil 450: end
# File lib/sass/engine.rb, line 415 415: def parse_for(line, root, text) 416: var, from_expr, to_name, to_expr = text.scan(/^([^\s]+)\s+from\s+(.+)\s+(to|through)\s+(.+)$/).first 417: 418: if var.nil? # scan failed, try to figure out why for error message 419: if text !~ /^[^\s]+/ 420: expected = "variable name" 421: elsif text !~ /^[^\s]+\s+from\s+.+/ 422: expected = "'from <expr>'" 423: else 424: expected = "'to <expr>' or 'through <expr>'" 425: end 426: raise SyntaxError.new("Invalid for directive '@for #{text}': expected #{expected}.", @line) 427: end 428: raise SyntaxError.new("Invalid variable \"#{var}\".", @line) unless var =~ Script::VALIDATE 429: 430: parsed_from = parse_script(from_expr, :offset => line.offset + line.text.index(from_expr)) 431: parsed_to = parse_script(to_expr, :offset => line.offset + line.text.index(to_expr)) 432: Tree::ForNode.new(var[1..-1], parsed_from, parsed_to, to_name == 'to') 433: end
# File lib/sass/engine.rb, line 317 317: def parse_line(parent, line, root) 318: case line.text[0] 319: when PROPERTY_CHAR 320: if line.text[1] == PROPERTY_CHAR || 321: (@options[:property_syntax] == :new && 322: line.text =~ PROPERTY_OLD && $3.empty?) 323: # Support CSS3-style pseudo-elements, 324: # which begin with ::, 325: # as well as pseudo-classes 326: # if we're using the new property syntax 327: Tree::RuleNode.new(line.text) 328: else 329: parse_property(line, PROPERTY_OLD) 330: end 331: when Script::VARIABLE_CHAR 332: parse_variable(line) 333: when COMMENT_CHAR 334: parse_comment(line.text) 335: when DIRECTIVE_CHAR 336: parse_directive(parent, line, root) 337: when ESCAPE_CHAR 338: Tree::RuleNode.new(line.text[1..-1]) 339: when MIXIN_DEFINITION_CHAR 340: parse_mixin_definition(line) 341: when MIXIN_INCLUDE_CHAR 342: if line.text[1].nil? || line.text[1] == ?\s 343: Tree::RuleNode.new(line.text) 344: else 345: parse_mixin_include(line, root) 346: end 347: else 348: if line.text =~ PROPERTY_NEW_MATCHER 349: parse_property(line, PROPERTY_NEW) 350: else 351: Tree::RuleNode.new(line.text) 352: end 353: end 354: end
# File lib/sass/engine.rb, line 452 452: def parse_mixin_definition(line) 453: name, arg_string = line.text.scan(/^=\s*([^(]+)(.*)$/).first 454: raise SyntaxError.new("Invalid mixin \"#{line.text[1..-1]}\".", @line) if name.nil? 455: 456: offset = line.offset + line.text.size - arg_string.size 457: args = Script::Parser.new(arg_string.strip, @line, offset).parse_mixin_definition_arglist 458: default_arg_found = false 459: Tree::MixinDefNode.new(name, args) 460: end
# File lib/sass/engine.rb, line 462 462: def parse_mixin_include(line, root) 463: name, arg_string = line.text.scan(/^\+\s*([^(]+)(.*)$/).first 464: raise SyntaxError.new("Invalid mixin include \"#{line.text}\".", @line) if name.nil? 465: 466: offset = line.offset + line.text.size - arg_string.size 467: args = Script::Parser.new(arg_string.strip, @line, offset).parse_mixin_include_arglist 468: raise SyntaxError.new("Illegal nesting: Nothing may be nested beneath mixin directives.", @line + 1) unless line.children.empty? 469: Tree::MixinNode.new(name, args) 470: end
# File lib/sass/engine.rb, line 356 356: def parse_property(line, property_regx) 357: name, eq, value = line.text.scan(property_regx)[0] 358: 359: if name.nil? || value.nil? 360: raise SyntaxError.new("Invalid property: \"#{line.text}\".", @line) 361: end 362: expr = if (eq.strip[0] == SCRIPT_CHAR) 363: parse_script(value, :offset => line.offset + line.text.index(value)) 364: else 365: value 366: end 367: Tree::PropNode.new(name, expr, property_regx == PROPERTY_OLD ? :old : :new) 368: end
# File lib/sass/engine.rb, line 472 472: def parse_script(script, options = {}) 473: line = options[:line] || @line 474: offset = options[:offset] || 0 475: Script.parse(script, line, offset, @options[:filename]) 476: end
# File lib/sass/engine.rb, line 370 370: def parse_variable(line) 371: name, op, value = line.text.scan(Script::MATCH)[0] 372: raise SyntaxError.new("Illegal nesting: Nothing may be nested beneath variable declarations.", @line + 1) unless line.children.empty? 373: raise SyntaxError.new("Invalid variable: \"#{line.text}\".", @line) unless name && value 374: 375: Tree::VariableNode.new(name, parse_script(value, :offset => line.offset + line.text.index(value)), op == '||=') 376: end
# File lib/sass/engine.rb, line 167 167: def tabulate(string) 168: tab_str = nil 169: first = true 170: lines = [] 171: string.gsub(/\r|\n|\r\n|\r\n/, "\n").scan(/^.*?$/).each_with_index do |line, index| 172: index += (@options[:line] || 1) 173: if line.strip.empty? 174: lines.last.text << "\n" if lines.last && lines.last.comment? 175: next 176: end 177: 178: line_tab_str = line[/^\s*/] 179: unless line_tab_str.empty? 180: tab_str ||= line_tab_str 181: 182: raise SyntaxError.new("Indenting at the beginning of the document is illegal.", index) if first 183: if tab_str.include?(?\s) && tab_str.include?(?\t) 184: raise SyntaxError.new("Indentation can't use both tabs and spaces.", index) 185: end 186: end 187: first &&= !tab_str.nil? 188: if tab_str.nil? 189: lines << Line.new(line.strip, 0, index, 0, @options[:filename], []) 190: next 191: end 192: 193: if lines.last && lines.last.comment? && line =~ /^(?:#{tab_str}){#{lines.last.tabs + 1}}(.*)$/ 194: lines.last.text << "\n" << $1 195: next 196: end 197: 198: line_tabs = line_tab_str.scan(tab_str).size 199: raise SyntaxError.new("Inconsistent indentation: \#{Haml::Shared.human_indentation line_tab_str, true} used for indentation,\nbut the rest of the document was indented using \#{Haml::Shared.human_indentation tab_str}.\n".strip.gsub("\n", ' '), index) if tab_str * line_tabs != line_tab_str 200: lines << Line.new(line.strip, line_tabs, index, tab_str.size, @options[:filename], []) 201: end 202: lines 203: end
# File lib/sass/engine.rb, line 209 209: def tree(arr, i = 0) 210: return [], i if arr[i].nil? 211: 212: base = arr[i].tabs 213: nodes = [] 214: while (line = arr[i]) && line.tabs >= base 215: if line.tabs > base 216: if line.tabs > base + 1 217: raise SyntaxError.new("The line was indented #{line.tabs - base} levels deeper than the previous line.", line.index) 218: end 219: 220: nodes.last.children, i = tree(arr, i) 221: else 222: nodes << line 223: i += 1 224: end 225: end 226: return nodes, i 227: end
# File lib/sass/engine.rb, line 281 281: def validate_and_append_child(parent, child, line, root) 282: unless root 283: case child 284: when Tree::MixinDefNode 285: raise SyntaxError.new("Mixins may only be defined at the root of a document.", line.index) 286: when Tree::ImportNode 287: raise SyntaxError.new("Import directives may only be used at the root of a document.", line.index) 288: end 289: end 290: 291: case child 292: when Array 293: child.each {|c| validate_and_append_child(parent, c, line, root)} 294: when Tree::Node 295: parent << child 296: end 297: end