Class: Sass::Engine

Inherits:

Object

• Object
• Sass::Engine

Defined in:

lib/sass/engine.rb

Overview

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

Defined Under Namespace

Classes: Line

Constant Summary

PROPERTY_CHAR =

The character that begins a CSS property.

?:

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.

?/

SASS_LOUD_COMMENT_CHAR =

The character that indicates that a comment allows interpolation and should be preserved even in :compressed mode.

?!

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_OLD =

The regex that matches and extracts data from properties of the form :name prop.

/^:([^\s=:"]+)\s*(?:\s+|$)(.*)/

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

• #options ⇒ {Symbol => Object} readonly

  The options for the Sass engine.

Class Method Summary

• .for_file(filename, options) ⇒ Sass::Engine

  Returns the Engine for the given file.

Instance Method Summary

• #dependencies ⇒ [Sass::Engine]

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

• #initialize(template, options = {}) ⇒ Engine constructor

  Creates a new Engine.

• #render ⇒ String (also: #to_css)

  Render the template to CSS.

• #render_with_sourcemap(sourcemap_uri) ⇒ (String, Sass::Source::Map)

  Render the template to CSS and return the source map.

• #source_encoding ⇒ Encoding^?

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

• #to_tree ⇒ Sass::Tree::Node

  Parses the document into its parse tree.

Constructor Details

#initialize(template, options = {}) ⇒ Engine

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}

# File 'lib/sass/engine.rb', line 261

def initialize(template, options = {})
  @options = self.class.normalize_options(options)
  @template = template
end

Instance Attribute Details

#options ⇒ {Symbol => Object} (readonly)

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

Returns:

• ({Symbol => Object})

# File 'lib/sass/engine.rb', line 242

def options
  @options
end

Class Method Details

.for_file(filename, options) ⇒ Sass::Engine

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:

• filename (String) —

  The path to the Sass or SCSS file

• options ({Symbol => Object}) —

  The options hash; See the Sass options documentation.

Returns:

• (Sass::Engine) —

  The Engine for the given Sass or SCSS file.

Raises:

• (Sass::SyntaxError) —

  if there's an error in the document.

# File 'lib/sass/engine.rb', line 224

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

  if had_syntax
    # Use what was explicitly specificed
  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

#dependencies ⇒ [Sass::Engine]

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

Returns:

• ([Sass::Engine]) —

  The dependency documents.

# File 'lib/sass/engine.rb', line 326

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

#render ⇒ String 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

# File 'lib/sass/engine.rb', line 273

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

#render_with_sourcemap(sourcemap_uri) ⇒ (String, Sass::Source::Map)

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:

• ((String, Sass::Source::Map)) —

  The rendered CSS and the associated source map

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

# File 'lib/sass/engine.rb', line 290

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

#source_encoding ⇒ 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

# File 'lib/sass/engine.rb', line 316

def source_encoding
  check_encoding!
  @original_encoding
end

#to_tree ⇒ Sass::Tree::Node

Parses the document into its parse tree. Memoized.

Returns:

• (Sass::Tree::Node) —

  The root of the parse tree.

Raises:

• (Sass::SyntaxError) —

  if there's an error in the document

# File 'lib/sass/engine.rb', line 301

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