Exception: Sass::SyntaxError

Inherits:
StandardError
  • Object
show all
Defined in:
lib/sass/error.rb

Overview

An exception class that keeps track of the line of the Sass template it was raised on and the Sass file that was being parsed (if applicable).

All Sass errors are raised as SyntaxErrors.

When dealing with SyntaxErrors, it's important to provide filename and line number information. This will be used in various error reports to users, including backtraces; see #sass_backtrace for details.

Some of this information is usually provided as part of the constructor. New backtrace entries can be added with #add_backtrace, which is called when an exception is raised between files (e.g. with @import).

Often, a chunk of code will all have similar backtrace information - the same filename or even line. It may also be useful to have a default line number set. In those situations, the default values can be used by omitting the information on the original exception, and then calling #modify_backtrace in a wrapper rescue. When doing this, be sure that all exceptions ultimately end up with the information filled in.

Direct Known Subclasses

UnitConversionError

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(msg, attrs = {}) ⇒ SyntaxError

Returns a new instance of SyntaxError.

Parameters:

  • msg (String) —

    The error message

  • attrs ({Symbol => Object}) (defaults to: {}) —

    The information in the backtrace entry. See #sass_backtrace



55
56
57
58
59
 
# File 'lib/sass/error.rb', line 55

def initialize(msg, attrs = {})
  @message = msg
  @sass_backtrace = []
  add_backtrace(attrs)
end

Instance Attribute Details

#sass_backtrace ⇒ Aray<{Symbol => Object>}

The backtrace of the error within Sass files. This is an array of hashes containing information for a single entry. The hashes have the following keys:

:filename : The name of the file in which the exception was raised, or nil if no filename is available.

:mixin : The name of the mixin in which the exception was raised, or nil if it wasn't raised in a mixin.

:line : The line of the file on which the error occurred. Never nil.

This information is also included in standard backtrace format in the output of #backtrace.

Returns:

  • (Aray<{Symbol => Object>}) 


45
46
47
 
# File 'lib/sass/error.rb', line 45

def sass_backtrace
  @sass_backtrace
end

#sass_template ⇒ String

The text of the template where this error was raised.

Returns:

  • (String) 


50
51
52
 
# File 'lib/sass/error.rb', line 50

def sass_template
  @sass_template
end

Class Method Details

.exception_to_css(e, options) ⇒ String

Returns an error report for an exception in CSS format.

Parameters:

  • e (Exception)
  • options ({Symbol => Object}) —

    The options passed to Engine#initialize

Returns:

  • (String) —

    The error report

Raises:



161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/sass/error.rb', line 161

def exception_to_css(e, options)
  raise e unless options[:full_exception]

  header = header_string(e, options)

  <<END
/*
#{header}

Backtrace:\n#{e.backtrace.join("\n")}
*/
body:before {
  white-space: pre;
  font-family: monospace;
  content: "#{header.gsub('"', '\"').gsub("\n", '\\A ')}"; }
END
end

Instance Method Details

#add_backtrace(attrs)

Adds an entry to the exception's Sass backtrace.

Parameters:

  • attrs ({Symbol => Object}) —

    The information in the backtrace entry. See #sass_backtrace



88
89
90
 
# File 'lib/sass/error.rb', line 88

def add_backtrace(attrs)
  sass_backtrace << attrs.reject {|k, v| v.nil?}
end

#backtrace ⇒ Array<String>

Returns the standard exception backtrace, including the Sass backtrace.

Returns:

  • (Array<String>) 


126
127
128
129
130
131
132
133
 
# File 'lib/sass/error.rb', line 126

def backtrace
  return nil if super.nil?
  return super if sass_backtrace.all? {|h| h.empty?}
  sass_backtrace.map do |h|
    "#{h[:filename] || "(sass)"}:#{h[:line]}" +
      (h[:mixin] ? ":in `#{h[:mixin]}'" : "")
  end + super
end

#modify_backtrace(attrs)

Modify the top Sass backtrace entries (that is, the most deeply nested ones) to have the given attributes.

Specifically, this goes through the backtrace entries from most deeply nested to least, setting the given attributes for each entry. If an entry already has one of the given attributes set, the pre-existing attribute takes precedence and is not used for less deeply-nested entries (even if they don't have that attribute set).

Parameters:

  • attrs ({Symbol => Object}) —

    The information to add to the backtrace entry. See #sass_backtrace



106
107
108
109
110
111
112
113
114
115
 
# File 'lib/sass/error.rb', line 106

def modify_backtrace(attrs)
  attrs = attrs.reject {|k, v| v.nil?}
  # Move backwards through the backtrace
  (0...sass_backtrace.size).to_a.reverse.each do |i|
    entry = sass_backtrace[i]
    sass_backtrace[i] = attrs.merge(entry)
    attrs.reject! {|k, v| entry.include?(k)}
    break if attrs.empty?
  end
end

#sass_backtrace_str(default_filename = "an unknown file") ⇒ String

Returns a string representation of the Sass backtrace.

Parameters:

  • default_filename (String) (defaults to: "an unknown file") —

    The filename to use for unknown files

Returns:

  • (String)

See Also:



140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/sass/error.rb', line 140

def sass_backtrace_str(default_filename = "an unknown file")
  lines = self.message.split("\n")
  msg = lines[0] + lines[1..-1].
    map {|l| "\n" + (" " * "Syntax error: ".size) + l}.join
  "Syntax error: #{msg}" +
    Sass::Util.enum_with_index(sass_backtrace).map do |entry, i|
    "\n        #{i == 0 ? "on" : "from"} line #{entry[:line]}" +
      " of #{entry[:filename] || default_filename}" +
      (entry[:mixin] ? ", in `#{entry[:mixin]}'" : "")
  end.join
end

#sass_filename ⇒ String?

The name of the file in which the exception was raised. This could be nil if no filename is available.

Returns:

  • (String, nil) 


65
66
67
 
# File 'lib/sass/error.rb', line 65

def sass_filename
  sass_backtrace.first[:filename]
end

#sass_line ⇒ Fixnum

The line of the Sass template on which the error occurred.

Returns:

  • (Fixnum) 


80
81
82
 
# File 'lib/sass/error.rb', line 80

def sass_line
  sass_backtrace.first[:line]
end

#sass_mixin ⇒ Fixnum

The name of the mixin in which the error occurred. This could be nil if the error occurred outside a mixin.

Returns:

  • (Fixnum) 


73
74
75
 
# File 'lib/sass/error.rb', line 73

def sass_mixin
  sass_backtrace.first[:mixin]
end

#to_s ⇒ String

Returns The error message.

Returns:

  • (String) —

    The error message



118
119
120
 
# File 'lib/sass/error.rb', line 118

def to_s
  @message
end