Sass Reference - - By Hugo Giraudel

Warnings and Errors

Warnings and errors are the way a program has to communicate with a developer or user. For instance, when you inadvertently introduce a syntax error in your code, the program/language (whatever it is) is likely to throw an error explaining your mistake and how you should fix it.

Sass providing easy ways to build public APIs (essentially using functions and mixins), there is nothing surprising in having a way to emit warnings and errors as part of the language. It is especially useful when checking arguments from mixins and functions.

Both warnings and errors are emitted in the current output channel. When compiling Sass by hand or with a CLI-based tool such as Grunt or Gulp, the output stream is the console. For tools including user interfaces like Codekit or Prepros, it is likely that they catch and display them as part of their interface. Online playgrounds like CodePen and SassMeister manage to catch errors, so don’t be alarmed if you cannot test warnings in there.

Warnings

Warnings, through the @warn directive, are messages that are displayed in the current output stream without stopping the execution process. They come in handy when wanting to let the user know about something going on with the code, for instance when a mixin assumes something, which might be wrong or incorrect.

The warning directive could not be any easier: it is the @warn token followed by a string. There is no configuration whatsoever or extra options.

@warn 'Ohai! I am a warning message.';

Errors

Errors, through the @error directive, are messages that are displayed in the current output stream, but unlike warnings, they do stop the compilation. When Sass meets an @error directive, it prints the given message and stops execution right away.

The syntax for the @error directive is the exact same as the one from @warn: the @error token followed by a string.

@error 'Uh-ho, something is going wrong.';

Example

One of the best examples I have encountered for @warn lives in the Sass-MQ library. It is meant to let the developer know that the mq-px2em mixin is assuming that a unitless value should be considered as a pixel value.

@function mq-px2em($px, $base-font-size: $mq-base-font-size) {
  @if unitless($px) {
    @warn 'Assuming #{$px} to be in pixels, attempting to convert it into pixels.';
    @return mq-px2em($px + 0px);
  } @else if unit($px) == em {
    @return $px;
  }

  @return ($px / $base-font-size) * 1em;
}

I think this is a nice addition because the program is effectively able to keep going, but something might possibly go wrong. The user deserves to know, hence the warning.

Regarding errors, the simplest use case would be parameter validation in a mixin. For instance:

@mixin size($width, $height: $width) {
    @if not is-length($width) or not is-length($height) {
        @error '`size` mixin is expecting lengths.';
    }

    width: $width;
    height: $height;
}

Engine compatibility

Sass warnings are fully compatible across all Sass engines and there is no known bug to this day about their implementation. On the other hand, Sass errors are only supported since Sass 3.4. Using the @error directive in an unsupported environment will result in a parsing error.

One way to handle errors in unsupported (pre 3.4) environments is to wrap tests in functions, warn then return null.

@function do-something($value) { @if not $value { @warn "Error message"; @return null; } // Function core when `$value` is okay }

One downside we could raise about this way of doing is that it does not actually stop Sass from processing.

If we want to trigger an error so that Sass completely stops, Eric Suzanne found a neat little solution. The idea is to create an empty function with no return statement.

@function error() {}

When you want to throw an error, you simply call this function. Because Sass expects a @return statement in a function, it will throw the following error:

Function error finished without @return

That does not tell much about the error, but at least Sass is not running anymore. I am not a big fan of this technique since there is no way of outputing a specific message, but it has the benefit of working fine in unsupported environment.