canonicalize abstract method

FutureOr<Uri?> canonicalize(
  1. Uri url
)

If url is recognized by this importer, returns its canonical format.

Note that canonical URLs must be absolute, including a scheme. Returning file: URLs is encouraged if the imported stylesheet comes from a file on disk.

If Sass has already loaded a stylesheet with the returned canonical URL, it re-uses the existing parse tree. This means that importers must ensure that the same canonical URL always refers to the same stylesheet, even across different importers.

This may return null if url isn't recognized by this importer.

If this importer's URL format supports file extensions, it should canonicalize them the same way as the default filesystem importer:

  • The importer should look for stylesheets by adding the prefix _ to the URL's basename, and by adding the extensions .sass and .scss if the URL doesn't already have one of those extensions. For example, if the URL was foo/bar/baz, the importer would look for:

    • foo/bar/baz.sass
    • foo/bar/baz.scss
    • foo/bar/_baz.sass
    • foo/bar/_baz.scss

    If the URL was foo/bar/baz.scss, the importer would just look for:

    • foo/bar/baz.scss
    • foo/bar/_baz.scss

    If the importer finds a stylesheet at more than one of these URLs, it should throw an exception indicating that the import is ambiguous. Note that if the extension is explicitly specified, a stylesheet with the opposite extension may exist.

  • If none of the possible paths is valid, the importer should perform the same resolution on the URL followed by /index. In the example above, it would look for:

    • foo/bar/baz/_index.sass
    • foo/bar/baz/index.sass
    • foo/bar/baz/_index.scss
    • foo/bar/baz/index.scss

    As above, if the importer finds a stylesheet at more than one of these URLs, it should throw an exception indicating that the import is ambiguous.

If no stylesheets are found, the importer should return null.

Calling canonicalize multiple times with the same URL must return the same result. Calling canonicalize with a URL returned by canonicalize must return that URL. Calling canonicalize with a URL relative to one returned by canonicalize must return a meaningful result.

Implementation

FutureOr<Uri?> canonicalize(Uri url);