Using Sass’s @error, @warn, and @debug Directives

Feedback methods are essential in any programming language. In JavaScript, you’ve probably used console.log() or maybe alert(). In PHP, you can use var_dump() or print_r(). In Ruby, you may use debug or inspect. All these functions allow you to debug any value and find out what your code is doing at any point in the logic where you need help.

Sass has three directives for providing feedback to developers. They are @error, @warn, and @debug. In this post, we’ll look at how to use these directives, what use cases they’re best suited for, and what kind of feedback they can provide for other developers who use our code.

Basic Syntax and Use

All three of these directives follow the same syntax:

[code language="sass"]
@directive "String of text to output.";
[/code]

If you need to interpolate a variable’s value in that string, you can do so using the standard Sass interpolation (#{$variable}) and the value will be printed in the string. With this method, you can tell a developer both the name of the variable and its current value:

[code language="sass"]
@error "Sorry, but `#{$variable}` is not a valid value for $variable.";
[/code]

Note that the ticks (`) around the interpolation are not required. You may want to include them because they give the developer an obvious start/stop point for the variable’s contents.

If a developer makes a mistake when using your Sass code, these directives will send the specified message to the compiler and the compiler will show that message to the developer. For example, GUI apps (like CodeKit) will show a system notification with the error. Certain Grunt and Gulp notification packages can do that as well.

If a developer is compiling with the command line (Sass, Compass, Grunt, or Gulp), the message will likely end up in their console (Terminal, iTerm2, Putty, etc). If you’re writing Sass online with Sassmeister or Codepen, you’ll only get limited feedback, but you may get an inline notification in your editor or text in the output window.

Now that we know how to write @error, @warn, and @debug messages and where they’ll appear for the developer, let’s look at the difference between these directives and the best uses for each one.

Stop Everything – The @error Directive

Sass’s @error directive stops the Sass compiler completely and sends its string of text to the compiler’s output as a fatal error. Use this directive when you need to send a message that stops the developer immediately and forces them to correct their mistake right away. This is ideal for letting a developer know they’ve done something wrong or entered a value that’s entirely incompatible. Sass will include the line number with any fatal error, including @error output. The @error directive is ideal for validating arguments within a mixin or function.

Note: If your compiler is older than Sass 3.4 or LibSass 3.1, @error is not available. You can use this log() function to emulate @error in older Sass versions.

As an example, if you’ve written a function that relies on a certain input format for its calculations, you can validate the input and use @error to stop the compiler and alert the developer that they’ve made a mistake that can’t be overlooked. If you’ve written a function that relies on a key/value pair from a map, @error can make sure that the key that’s called from the map actually exists.

This Sass color management tool uses @error to ensure that the developer only uses a color name that’s a valid CSS color name or a key from a related map:

Map:

[code language="sass"]
$colors: (
brand-red: #c0392b,
brand-blue: #2980b9,
text-gray: #2c3e50,
text-silver: #bdc3c7
);
[/code]

Function:

[code language="sass"]
// Ignore the `$variation: false` bit here,
// or read the post for more information.

@function color-variation($color, $variation: false) {
@if map-has-key($colors, $color) {
$color: map-get($colors, $color);
} @else {
@if type-of($color) != color {
@error "Invalid color name: `#{$color}`.";
}
}
}
[/code]

Usage:

[code language="sass"]
.element {
color: color-variation(brand-orange);
}
[/code]

Output:

[code language="bash"]
>> Invalid color name: `brand-orange`.
>> Line 9 Column 7 sass/test.scss
[/code]

In this example, if the developer tries calling the color-variation() function with a string that’s neither a valid CSS color nor a key from the $colors map, there’s nothing Sass can do to output a valid color. Using @error gives the developer specific, actionable feedback.

Continue reading %Using Sass’s @error, @warn, and @debug Directives%

by James Steinbach via SitePoint