Class: Sass::Importers::Base Abstract

Inherits:
Object
  • Object
show all
Defined in:
lib/sass/importers/base.rb

Overview

This class is abstract.

The abstract base class for Sass importers. All importers should inherit from this.

At the most basic level, an importer is given a string and must return a Engine containing some Sass code. This string can be interpreted however the importer wants; however, subclasses are encouraged to use the URI format for pathnames.

Importers that have some notion of "relative imports" should take a single load path in their constructor, and interpret paths as relative to that. They should also implement the #find_relative method.

Importers should be serializable via Marshal.dump.

Direct Known Subclasses

Filesystem

Instance Method Summary collapse

Instance Method Details

#directories_to_watchArray<String>

If the importer is based on files on the local filesystem this method should return folders which should be watched for changes.



165
166
167
# File 'lib/sass/importers/base.rb', line 165

def directories_to_watch
  []
end

#find(uri, options) ⇒ Sass::Engine?

Find a Sass file, if it exists.

This is the primary entry point of the Importer. It corresponds directly to an @import statement in Sass. It should do three basic things:

  • Determine if the URI is in this importer's format. If not, return nil.
  • Determine if the file indicated by the URI actually exists and is readable. If not, return nil.
  • Read the file and place the contents in a Engine. Return that engine.

If this importer's format allows for file extensions, it should treat them the same way as the default Filesystem importer. If the URI explicitly has a .sass or .scss filename, the importer should look for that exact file and import it as the syntax indicated. If it doesn't exist, the importer should return nil.

If the URI doesn't have either of these extensions, the importer should look for files with the extensions. If no such files exist, it should return nil.

The Engine to be returned should be passed options, with a few modifications. :syntax should be set appropriately, :filename should be set to uri, and :importer should be set to this importer.



82
83
84
# File 'lib/sass/importers/base.rb', line 82

def find(uri, options)
  Sass::Util.abstract(self)
end

#find_relative(uri, base, options) ⇒ Sass::Engine?

Find a Sass file relative to another file. Importers without a notion of "relative paths" should just return nil here.

If the importer does have a notion of "relative paths", it should ignore its load path during this method.

See #find for important information on how this method should behave.

The :filename option passed to the returned Engine should be of a format that could be passed to #find.



42
43
44
# File 'lib/sass/importers/base.rb', line 42

def find_relative(uri, base, options)
  Sass::Util.abstract(self)
end

#key(uri, options) ⇒ (String, String)

Get the cache key pair for the given Sass URI. The URI need not be checked for validity.

The only strict requirement is that the returned pair of strings uniquely identify the file at the given URI. However, the first component generally corresponds roughly to the directory, and the second to the basename, of the URI.

Note that keys must be unique across importers. Thus it's probably a good idea to include the importer name at the beginning of the first component.



117
118
119
# File 'lib/sass/importers/base.rb', line 117

def key(uri, options)
  Sass::Util.abstract(self)
end

#mtime(uri, options) ⇒ Time?

Returns the time the given Sass file was last modified.

If the given file has been deleted or the time can't be accessed for some other reason, this should return nil.



96
97
98
# File 'lib/sass/importers/base.rb', line 96

def mtime(uri, options)
  Sass::Util.abstract(self)
end

#public_url(uri, sourcemap_directory) ⇒ String?

Get the publicly-visible URL for an imported file. This URL is used by source maps to link to the source stylesheet. This may return nil to indicate that no public URL is available; however, this will cause sourcemap generation to fail if any CSS is generated from files imported from this importer.

If an absolute "file:" URI can be produced for an imported file, that should be preferred to returning nil. However, a URL relative to sourcemap_directory should be preferred over an absolute "file:" URI.



140
141
142
143
144
145
146
147
# File 'lib/sass/importers/base.rb', line 140

def public_url(uri, sourcemap_directory)
  return if @public_url_warning_issued
  @public_url_warning_issued = true
  Sass::Util.sass_warn <<WARNING
WARNING: #{self.class.name} should define the #public_url method.
WARNING
  nil
end

#to_sString

A string representation of the importer. Should be overridden by subclasses.

This is used to help debugging, and should usually just show the load path encapsulated by this importer.



156
157
158
# File 'lib/sass/importers/base.rb', line 156

def to_s
  Sass::Util.abstract(self)
end

#watched_file?(filename) ⇒ Boolean

If this importer is based on files on the local filesystem This method should return true if the file, when changed, should trigger a recompile.

It is acceptable for non-sass files to be watched and trigger a recompile.



177
178
179
# File 'lib/sass/importers/base.rb', line 177

def watched_file?(filename)
  false
end