class Sass::Engine

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

Constants

COMMENT_CHAR

The character that designates the beginning of a comment, either Sass or CSS.

CONTENT_RE
CSS_COMMENT_CHAR

The character that follows the general COMMENT_CHAR and designates a CSS comment, which is embedded in the CSS document.

DEFAULT_OPTIONS

The default options for Sass::Engine. @api public

DIRECTIVES
DIRECTIVE_CHAR

The character used to denote a compiler directive.

ESCAPE_CHAR

Designates a non-parsed rule.

FUNCTION_RE
MIXIN_DEFINITION_CHAR

Designates block as mixin definition rather than CSS rules to output

MIXIN_DEF_RE
MIXIN_INCLUDE_CHAR

Includes named mixin declared using MIXIN_DEFINITION_CHAR

MIXIN_INCLUDE_RE
PROPERTY_CHAR

The character that begins a CSS property.

PROPERTY_OLD

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

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.

Attributes

options[R]

The options for the Sass engine. See {file:SASS_REFERENCE.md#sass_options the Sass options documentation}.

@return [{Symbol => Object}]

Public Class Methods

for_file(filename, options) click to toggle source

Returns the {Sass::Engine} for the given file. This is preferable to ::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.

@param filename [String] The path to the Sass or SCSS file @param options [{Symbol => Object}] The options hash;

See {file:SASS_REFERENCE.md#sass_options the Sass options documentation}.

@return [Sass::Engine] The Engine for the given Sass or SCSS file. @raise [Sass::SyntaxError] if there's an error in the document.

# File 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
new(template, options = {}) click to toggle source

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 {Sass::Engine.for_file}. If you're compiling multiple files from the filesystem, use {Sass::Plugin}.

@param 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 {file:SASS_REFERENCE.md#encodings the encoding documentation})

@param options [{Symbol => Object}] An options hash.

See {file:SASS_REFERENCE.md#sass_options the Sass options documentation}.

@see {Sass::Engine.for_file} @see {Sass::Plugin}

# File 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
normalize_options(options) click to toggle source

Converts a Sass options hash into a standard form, filling in default values and resolving aliases.

@param options [{Symbol => Object}] The options hash;

see {file:SASS_REFERENCE.md#sass_options the Sass options documentation}

@return [{Symbol => Object}] The normalized options hash. @private

# File lib/sass/engine.rb, line 174
def self.normalize_options(options)
  options = DEFAULT_OPTIONS.merge(options.reject {|_k, v| v.nil?})

  # If the `:filename` option is passed in without an importer,
  # assume it's using the default filesystem importer.
  options[:importer] ||= options[:filesystem_importer].new(".") if options[:filename]

  # Tracks the original filename of the top-level Sass file
  options[:original_filename] ||= options[:filename]

  options[:cache_store] ||= Sass::CacheStores::Chain.new(
    Sass::CacheStores::Memory.new, Sass::CacheStores::Filesystem.new(options[:cache_location]))
  # Support both, because the docs said one and the other actually worked
  # for quite a long time.
  options[:line_comments] ||= options[:line_numbers]

  options[:load_paths] = (options[:load_paths] + Sass.load_paths).map do |p|
    next p unless p.is_a?(String) || (defined?(Pathname) && p.is_a?(Pathname))
    options[:filesystem_importer].new(p.to_s)
  end

  # Remove any deprecated importers if the location is imported explicitly
  options[:load_paths].reject! do |importer|
    importer.is_a?(Sass::Importers::DeprecatedPath) &&
      options[:load_paths].find do |other_importer|
        other_importer.is_a?(Sass::Importers::Filesystem) &&
          other_importer != importer &&
          other_importer.root == importer.root
      end
  end

  # Backwards compatibility
  options[:property_syntax] ||= options[:attribute_syntax]
  case options[:property_syntax]
  when :alternate; options[:property_syntax] = :new
  when :normal; options[:property_syntax] = :old
  end
  options[:sourcemap] = :auto if options[:sourcemap] == true
  options[:sourcemap] = :none if options[:sourcemap] == false

  options
end

Public Instance Methods

_dependencies(seen, engines) click to toggle source

Helper for {#dependencies}.

@private

# File lib/sass/engine.rb, line 341
def _dependencies(seen, engines)
  key = [@options[:filename], @options[:importer]]
  return if seen.include?(key)
  seen << key
  engines << self
  to_tree.grep(Tree::ImportNode) do |n|
    next if n.css_import?
    n.imported_file._dependencies(seen, engines)
  end
end
dependencies() click to toggle source

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

@return [[Sass::Engine]] The dependency documents.

# File lib/sass/engine.rb, line 333
def dependencies
  _dependencies(Set.new, engines = Set.new)
  Sass::Util.array_minus(engines, [self])
end
render() click to toggle source

Render the template to CSS.

@return [String] The CSS @raise [Sass::SyntaxError] if there's an error in the document @raise [Encoding::UndefinedConversionError] if the source encoding

cannot be converted to UTF-8

@raise [ArgumentError] if the document uses an unknown encoding with `@charset`

# File lib/sass/engine.rb, line 280
def render
  return _to_tree.render unless @options[:quiet]
  Sass::Util.silence_sass_warnings {_to_tree.render}
end
Also aliased as: to_css
render_with_sourcemap(sourcemap_uri) click to toggle source

Render the template to CSS and return the source map.

@param 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.

@return [(String, Sass::Source::Map)] The rendered CSS and the associated

source map

@raise [Sass::SyntaxError] if there's an error in the document, or if the

public URL for this document couldn't be determined.

@raise [Encoding::UndefinedConversionError] if the source encoding

cannot be converted to UTF-8

@raise [ArgumentError] if the document uses an unknown encoding with `@charset`

# File 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
source_encoding() click to toggle source

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

@return [Encoding, nil] @raise [Encoding::UndefinedConversionError] if the source encoding

cannot be converted to UTF-8

@raise [ArgumentError] if the document uses an unknown encoding with `@charset`

# File lib/sass/engine.rb, line 323
def source_encoding
  check_encoding!
  @source_encoding
end
to_css()
Alias for: render
to_tree() click to toggle source

Parses the document into its parse tree. Memoized.

@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 308
def to_tree
  @tree ||= if @options[:quiet]
              Sass::Util.silence_sass_warnings {_to_tree}
            else
              _to_tree
            end
end