Class: Sass::Engine

Inherits:
Object
  • Object
show all
Includes:
Haml::Util
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 collapse

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 =

The regex that matches properties of the form name: prop.

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

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

/^([^\s=:"]+)\s*(=|:)(?:\s+|$)(.*)/
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

Constants included from Haml::Util

Haml::Util::CHARSET_REGEXPS, Haml::Util::ENCODINGS_TO_CHECK, Haml::Util::RUBY_VERSION

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Haml::Util

#abstract, #ap_geq?, #ap_geq_3?, #assert_html_safe!, #av_template_class, #caller_info, #check_encoding, #check_haml_encoding, #check_sass_encoding, #def_static_method, #dump, #enum_cons, #enum_slice, #enum_with_index, #flatten, #haml_warn, #has?, #html_safe, #intersperse, #lcs, #load, #map_hash, #map_keys, #map_vals, #merge_adjacent_strings, #ord, #paths, #powerset, #rails_env, #rails_root, #rails_safe_buffer_class, #rails_xss_safe?, #restrict, #ruby1_8?, #ruby1_8_6?, #scope, #set_eql?, #set_hash, #silence_haml_warnings, #silence_warnings, #static_method_name, #strip_string_array, #substitute, #to_hash, #version_geq, #version_gt, #windows?

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 {Sass::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}


220
221
222
223
 
# File 'lib/sass/engine.rb', line 220

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}) 


201
202
203
 
# File 'lib/sass/engine.rb', line 201

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:

Returns:

  • (Sass::Engine) —

    The Engine for the given Sass or SCSS file.

Raises:



183
184
185
186
187
188
189
190
191
192
193
194
195
 
# File 'lib/sass/engine.rb', line 183

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

#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



232
233
234
235
 
# File 'lib/sass/engine.rb', line 232

def render
  return _render unless @options[:quiet]
  Haml::Util.silence_haml_warnings {_render}
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



254
255
256
257
 
# File 'lib/sass/engine.rb', line 254

def source_encoding
  check_encoding!
  @original_encoding
end

#to_tree ⇒ Sass::Tree::Node

Parses the document into its parse tree.

Returns:

Raises:



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

def to_tree
  return _to_tree unless @options[:quiet]
  Haml::Util.silence_haml_warnings {_to_tree}
end