class Sass::Plugin::Compiler

The Compiler class handles compilation of multiple files and/or directories, including checking which CSS files are out-of-date and need to be updated and calling Sass to perform the compilation on those files.

{Sass::Plugin} uses this class to update stylesheets for a single application. Unlike {Sass::Plugin}, though, the Compiler class has no global state, and so multiple instances may be created and used independently.

If you need to compile a Sass string into CSS, please see the {Sass::Engine} class.

Unlike {Sass::Plugin}, this class doesn’t keep track of whether or how many times a stylesheet should be updated. Therefore, the following ‘Sass::Plugin` options are ignored by the Compiler:

‘:never_update`
‘:always_check`

Public Class Methods

new (opts = {})

Source

# File lib/sass/plugin/compiler.rb, line 35
def initialize(opts = {})
  @watched_files = Set.new
  options.merge!(opts)
end

Creates a new compiler.

@param opts [{Symbol => Object}]

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

Public Instance Methods

clean (individual_files = [])

Source

# File lib/sass/plugin/compiler.rb, line 362
def clean(individual_files = [])
  file_list(individual_files).each do |(_, css_file, sourcemap_file)|
    if File.exist?(css_file)
      run_deleting_css css_file
      File.delete(css_file)
    end
    if sourcemap_file && File.exist?(sourcemap_file)
      run_deleting_sourcemap sourcemap_file
      File.delete(sourcemap_file)
    end
  end
  nil
end

Remove all output files that would be created by calling update_stylesheets, if they exist.

This method runs the deleting_css and deleting_sourcemap callbacks for the files that are deleted.

@param individual_files [Array<(String, String[, String])>]

A list of files to check for updates
**in addition to those specified by the
{file:SASS_REFERENCE.md#template_location-option `:template_location` option}.**
The first string in each pair is the location of the Sass/SCSS file,
the second is the location of the CSS file that it should be compiled to.
The third string, if provided, is the location of the Sourcemap file.

engine_options (additional_options = {})

Source

# File lib/sass/plugin/compiler.rb, line 337
def engine_options(additional_options = {})
  opts = options.merge(additional_options)
  opts[:load_paths] = load_paths(opts)
  options[:sourcemap] = :auto if options[:sourcemap] == true
  options[:sourcemap] = :none if options[:sourcemap] == false
  opts
end

Non-destructively modifies {#options} so that default values are properly set, and returns the result.

@param additional_options [{Symbol => Object}] An options hash with which to merge {#options} @return [{Symbol => Object}] The modified options hash

file_list (individual_files = [])

Source

# File lib/sass/plugin/compiler.rb, line 240
def file_list(individual_files = [])
  files = individual_files.map do |tuple|
    if engine_options[:sourcemap] == :none
      tuple[0..1]
    elsif tuple.size < 3
      [tuple[0], tuple[1], Sass::Util.sourcemap_name(tuple[1])]
    else
      tuple.dup
    end
  end

  template_location_array.each do |template_location, css_location|
    Sass::Util.glob(File.join(template_location, "**", "[^_]*.s[ca]ss")).sort.each do |file|
      # Get the relative path to the file
      name = Sass::Util.relative_path_from(file, template_location).to_s
      css = css_filename(name, css_location)
      sourcemap = Sass::Util.sourcemap_name(css) unless engine_options[:sourcemap] == :none
      files << [file, css, sourcemap]
    end
  end
  files
end

Construct a list of files that might need to be compiled from the provided individual_files and the template_locations.

Note: this method does not cache the results as they can change across invocations when sass files are added or removed.

@param individual_files [Array<(String, String[, String])>]

A list of files to check for updates
**in addition to those specified by the
{file:SASS_REFERENCE.md#template_location-option `:template_location` option}.**
The first string in each pair is the location of the Sass/SCSS file,
the second is the location of the CSS file that it should be compiled to.
The third string, if provided, is the location of the Sourcemap file.

@return [Array<(String, String, String)>]

A list of [sass_file, css_file, sourcemap_file] tuples similar
to what was passed in, but expanded to include the current state
of the directories being updated.

stylesheet_needs_update? (css_file, template_file)

Source

# File lib/sass/plugin/compiler.rb, line 346
def stylesheet_needs_update?(css_file, template_file)
  StalenessChecker.stylesheet_needs_update?(css_file, template_file)
end

Compass expects this to exist

update_stylesheets (individual_files = [])

Source

# File lib/sass/plugin/compiler.rb, line 201
def update_stylesheets(individual_files = [])
  Sass::Plugin.checked_for_updates = true
  staleness_checker = StalenessChecker.new(engine_options)

  files = file_list(individual_files)
  run_updating_stylesheets(files)

  updated_stylesheets = []
  files.each do |file, css, sourcemap|
    # TODO: Does staleness_checker need to check the sourcemap file as well?
    if options[:always_update] || staleness_checker.stylesheet_needs_update?(css, file)
      # XXX For consistency, this should return the sourcemap too, but it would
      # XXX be an API change.
      updated_stylesheets << [file, css]
      update_stylesheet(file, css, sourcemap)
    else
      run_not_updating_stylesheet(file, css, sourcemap)
    end
  end
  run_updated_stylesheets(updated_stylesheets)
end

Updates out-of-date stylesheets.

Checks each Sass/SCSS file in {file:SASS_REFERENCE.md#template_location-option ‘:template_location`} to see if it’s been modified more recently than the corresponding CSS file in {file:SASS_REFERENCE.md#css_location-option ‘:css_location`}. If it has, it updates the CSS file.

@param individual_files [Array<(String, String[, String])>]

A list of files to check for updates
**in addition to those specified by the
{file:SASS_REFERENCE.md#template_location-option `:template_location` option}.**
The first string in each pair is the location of the Sass/SCSS file,
the second is the location of the CSS file that it should be compiled to.
The third string, if provided, is the location of the Sourcemap file.

watch (individual_files = [], options = {}) { |modified, added, removed| ... }

Source

# File lib/sass/plugin/compiler.rb, line 291
def watch(individual_files = [], options = {})
  @inferred_directories = []
  options, individual_files = individual_files, [] if individual_files.is_a?(Hash)
  update_stylesheets(individual_files) unless options[:skip_initial_update]

  directories = watched_paths
  individual_files.each do |(source, _, _)|
    source = File.expand_path(source)
    @watched_files << Sass::Util.realpath(source).to_s
    @inferred_directories << File.dirname(source)
  end

  directories += @inferred_directories
  directories = remove_redundant_directories(directories)

  # TODO: Keep better track of what depends on what
  # so we don't have to run a global update every time anything changes.
  # XXX The :additional_watch_paths option exists for Compass to use until
  # a deprecated feature is removed. It may be removed without warning.
  directories += Array(options[:additional_watch_paths])

  options = {
    :relative_paths => false,
    # The native windows listener is much slower than the polling option, according to
    # https://github.com/nex3/sass/commit/a3031856b22bc834a5417dedecb038b7be9b9e3e
    :force_polling => @options[:poll] || Sass::Util.windows?
  }

  listener = create_listener(*directories, options) do |modified, added, removed|
    on_file_changed(individual_files, modified, added, removed)
    yield(modified, added, removed) if block_given?
  end

  begin
    listener.start
    sleep
  rescue Interrupt
    # Squelch Interrupt for clean exit from Listen::Listener
  end
end

Watches the template directory (or directories) and updates the CSS files whenever the related Sass/SCSS files change. ‘watch` never returns.

Whenever a change is detected to a Sass/SCSS file in {file:SASS_REFERENCE.md#template_location-option ‘:template_location`}, the corresponding CSS file in {file:SASS_REFERENCE.md#css_location-option `:css_location`} will be recompiled. The CSS files of any Sass/SCSS files that import the changed file will also be recompiled.

Before the watching starts in earnest, ‘watch` calls {#update_stylesheets}.

Note that ‘watch` uses the [Listen](github.com/guard/listen) library to monitor the filesystem for changes. Listen isn’t loaded until ‘watch` is run. The version of Listen distributed with Sass is loaded by default, but if another version has already been loaded that will be used instead.

@param individual_files [Array<(String, String[, String])>]

A list of files to check for updates
**in addition to those specified by the
{file:SASS_REFERENCE.md#template_location-option `:template_location` option}.**
The first string in each pair is the location of the Sass/SCSS file,
the second is the location of the CSS file that it should be compiled to.
The third string, if provided, is the location of the Sourcemap file.

@param options [Hash] The options that control how watching works. @option options [Boolean] :skip_initial_update

Don't do an initial update when starting the watcher when true