Class: Sass::Engine

Inherits:
Object
  • Object
show all
Defined in:
/Users/ceppstei/Projects/sass-lang/.sass/lib/sass/engine.rb

Overview

This class handles the parsing and compilation of the Sass template. Example usage:

template = File.read('stylesheets/sassy.sass')
sass_engine = Sass::Engine.new(template)
output = sass_engine.render
puts output

Defined Under Namespace

Classes: Line

Constant Summary

DEFAULT_OPTIONS =

The default options for Sass::Engine.

{
  :style => :nested,
  :load_paths => [],
  :cache => true,
  :cache_location => './.sass-cache',
  :syntax => :sass,
  :filesystem_importer => Sass::Importers::Filesystem
}.freeze

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (Engine) initialize(template, options = {})

Creates a new Engine. Note that Engine should only be used directly when compiling in-memory Sass code. If you’re compiling a single Sass file from the filesystem, use for_file. If you’re compiling multiple files from the filesystem, use Plugin.

Parameters:

  • template (String) —

    The Sass template. This template can be encoded using any encoding that can be converted to Unicode. If the template contains an @charset declaration, that overrides the Ruby encoding (see the encoding documentation)

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

    An options hash. See the Sass options documentation.

See Also:

  • Sass::Engine.{Sass{Sass::Engine{Sass::Engine.for_file}
  • Sass::Engine.{Sass{Sass::Plugin}


265
266
267
268
269
270
271
 
# File '/Users/ceppstei/Projects/sass-lang/.sass/lib/sass/engine.rb', line 265

def initialize(template, options = {})
  @options = self.class.normalize_options(options)
  @template = template
  @checked_encoding = false
  @filename = nil
  @line = nil
end

Instance Attribute Details

- ({Symbol => Object}) options (readonly)

The options for the Sass engine. See the Sass options documentation.

Returns:

  • ({Symbol => Object}) 


246
247
248
 
# File '/Users/ceppstei/Projects/sass-lang/.sass/lib/sass/engine.rb', line 246

def options
  @options
end

Class Method Details

+ (Sass::Engine) for_file(filename, options)

Returns the Sass::Engine for the given file. This is preferable to Sass::Engine.new when reading from a file because it properly sets up the Engine’s metadata, enables parse-tree caching, and infers the syntax from the filename.

Parameters:

Returns:

  • (Sass::Engine) —

    The Engine for the given Sass or SCSS file.

Raises:



228
229
230
231
232
233
234
235
236
237
238
239
240
 
# File '/Users/ceppstei/Projects/sass-lang/.sass/lib/sass/engine.rb', line 228

def self.for_file(filename, options)
  had_syntax = options[:syntax]

  if had_syntax
    # Use what was explicitly specified
  elsif filename =~ /\.scss$/
    options.merge!(:syntax => :scss)
  elsif filename =~ /\.sass$/
    options.merge!(:syntax => :sass)
  end

  Sass::Engine.new(File.read(filename), options.merge(:filename => filename))
end

Instance Method Details

- ([Sass::Engine]) dependencies

Gets a set of all the documents that are (transitive) dependencies of this document, not including the document itself.

Returns:



333
334
335
336
 
# File '/Users/ceppstei/Projects/sass-lang/.sass/lib/sass/engine.rb', line 333

def dependencies
  _dependencies(Set.new, engines = Set.new)
  Sass::Util.array_minus(engines, [self])
end

- (String) render Also known as: to_css

Render the template to CSS.

Returns:

  • (String) —

    The CSS

Raises:

  • (Sass::SyntaxError) —

    if there’s an error in the document

  • (Encoding::UndefinedConversionError) —

    if the source encoding cannot be converted to UTF-8

  • (ArgumentError) —

    if the document uses an unknown encoding with @charset



280
281
282
283
 
# File '/Users/ceppstei/Projects/sass-lang/.sass/lib/sass/engine.rb', line 280

def render
  return _to_tree.render unless @options[:quiet]
  Sass::Util.silence_sass_warnings {_to_tree.render}
end

- ((String, Sass::Source::Map)) render_with_sourcemap(sourcemap_uri)

Render the template to CSS and return the source map.

Parameters:

  • sourcemap_uri (String) —

    The sourcemap URI to use in the @sourceMappingURL comment. If this is relative, it should be relative to the location of the CSS file.

Returns:

Raises:

  • (Sass::SyntaxError) —

    if there’s an error in the document, or if the public URL for this document couldn’t be determined.

  • (Encoding::UndefinedConversionError) —

    if the source encoding cannot be converted to UTF-8

  • (ArgumentError) —

    if the document uses an unknown encoding with @charset



297
298
299
300
 
# File '/Users/ceppstei/Projects/sass-lang/.sass/lib/sass/engine.rb', line 297

def render_with_sourcemap(sourcemap_uri)
  return _render_with_sourcemap(sourcemap_uri) unless @options[:quiet]
  Sass::Util.silence_sass_warnings {_render_with_sourcemap(sourcemap_uri)}
end

- (Encoding?) source_encoding

Returns the original encoding of the document, or nil under Ruby 1.8.

Returns:

  • (Encoding, nil)

Raises:

  • (Encoding::UndefinedConversionError) —

    if the source encoding cannot be converted to UTF-8

  • (ArgumentError) —

    if the document uses an unknown encoding with @charset



323
324
325
326
 
# File '/Users/ceppstei/Projects/sass-lang/.sass/lib/sass/engine.rb', line 323

def source_encoding
  check_encoding!
  @source_encoding
end

- (Sass::Tree::Node) to_tree

Parses the document into its parse tree. Memoized.

Returns:

Raises:



308
309
310
311
312
313
314
 
# File '/Users/ceppstei/Projects/sass-lang/.sass/lib/sass/engine.rb', line 308

def to_tree
  @tree ||= if @options[:quiet]
              Sass::Util.silence_sass_warnings {_to_tree}
            else
              _to_tree
            end
end