Class: Sass::Plugin::Compiler

Inherits:
Object
  • Object
show all
Extended by:
Callbacks
Includes:
Configuration, Util
Defined in:
lib/sass/plugin/compiler.rb

Overview

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

Constant Summary

Constants included from Util

Util::CHARSET_REGEXPS, Util::ENCODINGS_TO_CHECK, Util::RUBY_ENGINE, Util::RUBY_VERSION

Instance Method Summary collapse

Methods included from Callbacks

define_callback, extended

Methods included from Configuration

#add_template_location, #default_options, #options, #options=, #remove_template_location, #reset!, #template_location_array

Methods included from Util

#abstract, #ap_geq?, #ap_geq_3?, #av_template_class, #caller_info, #check_encoding, #check_range, #check_sass_encoding, #destructure, #enum_cons, #enum_slice, #enum_with_index, #extract!, #extract_values, #flatten, #glob, #group_by_to_a, #has?, #hash_to_a, #inject_values, #inspect_obj, #intersperse, #ironruby?, #lcs, #macruby?, #map_hash, #map_keys, #map_vals, #merge_adjacent_strings, #ord, #paths, #powerset, #rails_env, #rails_root, #restrict, #ruby1_8?, #ruby1_8_6?, #sass_warn, #scope, #set_eql?, #set_hash, #silence_sass_warnings, #silence_warnings, #strip_string_array, #subsequence?, #substitute, #to_hash, #version_geq, #version_gt, #windows?, #with_extracted_values

Constructor Details

#initialize(options = {}) ⇒ Compiler

Creates a new compiler.

Parameters:



37
38
39
 
# File 'lib/sass/plugin/compiler.rb', line 37

def initialize(options = {})
  self.options.merge!(options)
end

Instance Method Details

#engine_options(additional_options = {}) ⇒ {Symbol => Object}

Non-destructively modifies Sass::Plugin::Configuration#options so that default values are properly set, and returns the result.

Parameters:

Returns:

  • ({Symbol => Object}) —

    The modified options hash



318
319
320
321
322
 
# File 'lib/sass/plugin/compiler.rb', line 318

def engine_options(additional_options = {})
  opts = options.merge(additional_options)
  opts[:load_paths] = load_paths(opts)
  opts
end

#on_updating_stylesheet_with_deprecation_warning(&block) Also known as: on_updating_stylesheet 



86
87
88
89
 
# File 'lib/sass/plugin/compiler.rb', line 86

def on_updating_stylesheet_with_deprecation_warning(&block)
  Sass::Util.sass_warn("Sass::Compiler#on_updating_stylesheet callback is deprecated and will be removed in a future release. Use Sass::Compiler#on_updated_stylesheet instead, which is run after stylesheet compilation.")
  on_updating_stylesheet_without_deprecation_warning(&block)
end

#stylesheet_needs_update?(css_file, template_file) ⇒ Boolean

Compass expects this to exist

Returns:

  • (Boolean) 


325
326
327
 
# File 'lib/sass/plugin/compiler.rb', line 325

def stylesheet_needs_update?(css_file, template_file)
  StalenessChecker.stylesheet_needs_update?(css_file, template_file)
end

#update_stylesheets(individual_files = [])

Updates out-of-date stylesheets.

Checks each Sass/SCSS file in :template_location to see if it's been modified more recently than the corresponding CSS file in :css_location. If it has, it updates the CSS file.

Parameters:

  • individual_files (Array<(String, String)>) (defaults to: []) —

    A list of files to check for updates in addition to those specified by the :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.



185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
 
# File 'lib/sass/plugin/compiler.rb', line 185

def update_stylesheets(individual_files = [])
  individual_files = individual_files.dup
  Sass::Plugin.checked_for_updates = true
  staleness_checker = StalenessChecker.new(engine_options)

  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 = file.sub(template_location.to_s.sub(/\/*$/, '/'), "")
      css = css_filename(name, css_location)
      individual_files << [file, css]
    end
  end

  run_updating_stylesheets individual_files

  individual_files.each do |file, css|
    if options[:always_update] || staleness_checker.stylesheet_needs_update?(css, file)
      update_stylesheet(file, css)
    else
      run_not_updating_stylesheet(file, css)
    end
  end
end

#watch(individual_files = [])

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 :template_location, the corresponding CSS file in :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 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.

Parameters:

  • individual_files (Array<(String, String)>) (defaults to: []) —

    A list of files to watch for updates in addition to those specified by the :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.



234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
 
# File 'lib/sass/plugin/compiler.rb', line 234

def watch(individual_files = [])
  update_stylesheets(individual_files)

  begin
    require 'listen'
  rescue LoadError => e
    dir = Sass::Util.scope("vendor/listen/lib")
    if $LOAD_PATH.include?(dir)
      e.message << "\n" <<
        if File.exists?(scope(".git"))
          'Run "git submodule update --init" to get the recommended version.'
        else
          'Run "gem install listen" to get it.'
        end
      raise e
    else
      $LOAD_PATH.unshift dir
      retry
    end
  end

  template_paths = template_locations # cache the locations
  individual_files_hash = individual_files.inject({}) do |h, files|
    parent = File.dirname(files.first)
    (h[parent] ||= []) << files unless template_paths.include?(parent)
    h
  end
  directories = template_paths + individual_files_hash.keys +
    [{:relative_paths => true}]

  # TODO: Keep better track of what depends on what
  # so we don't have to run a global update every time anything changes.
  listener = Listen::MultiListener.new(*directories) do |modified, added, removed|
    modified.each do |f|
      parent = File.dirname(f)
      if files = individual_files_hash[parent]
        next unless files.first == f
      else
        next unless f =~ /\.s[ac]ss$/
      end
      run_template_modified(f)
    end

    added.each do |f|
      parent = File.dirname(f)
      if files = individual_files_hash[parent]
        next unless files.first == f
      else
        next unless f =~ /\.s[ac]ss$/
      end
      run_template_created(f)
    end

    removed.each do |f|
      parent = File.dirname(f)
      if files = individual_files_hash[parent]
        next unless files.first == f
        try_delete_css files[1]
      else
        next unless f =~ /\.s[ac]ss$/
        try_delete_css f.gsub(/\.s[ac]ss$/, '.css')
      end
      run_template_deleted(f)
    end

    update_stylesheets(individual_files)
  end

  # The native windows listener is much slower than the polling
  # option, according to https://github.com/nex3/sass/commit/a3031856b22bc834a5417dedecb038b7be9b9e3e#commitcomment-1295118
  listener.force_polling(true) if @options[:poll] || Sass::Util.windows?

  begin
    listener.start
  rescue Exception => e
    raise e unless e.is_a?(Interrupt)
  end
end