Throw multi-span exceptions for argument errors

Author: nex3

lib/src/ast/node.dart

@@ -11,4 +11,24 @@ abstract class AstNode {
   /// This indicates where in the source Sass or SCSS stylesheet the node was
   /// defined.
   FileSpan get span;
+
+  /// Returns an [AstNode] that doesn't have any data and whose span is
+  /// generated by [callback].
+  ///
+  /// Anumber of APIs take [AstNode]s instead of spans because computing spans
+  /// eagerly can be expensive. This allows arbitrary spans to be passed to
+  /// those callbacks while sitll being lazily computed.
+  factory AstNode.fake(FileSpan Function() callback) = _FakeAstNode;
+
+  AstNode();
+}
+
+/// An [AstNode] that just exposes a single span generated by a callback.
+class _FakeAstNode implements AstNode {
+  FileSpan get span => _callback();
+
+  /// The callback to use to generate [span].
+  final FileSpan Function() _callback;
+
+  _FakeAstNode(this._callback);
 }

lib/src/ast/sass/argument_declaration.dart

@@ -8,6 +8,7 @@ import '../../exception.dart';
 import '../../logger.dart';
 import '../../parse/scss.dart';
 import '../../utils.dart';
+import '../../util/character.dart';
 import 'argument.dart';
 import 'node.dart';
 
@@ -22,6 +23,32 @@ class ArgumentDeclaration implements SassNode {
 
   final FileSpan span;
 
+  /// Returns [span] expanded to include an identifier immediately before the
+  /// declaration, if possible.
+  FileSpan get spanWithName {
+    var text = span.file.getText(0);
+
+    // Move backwards through and whitspace between the name and the arguments.
+    var i = span.start.offset - 1;
+    while (i > 0 && isWhitespace(text.codeUnitAt(i))) {
+      i--;
+    }
+
+    // Then move backwards through the name itself.
+    if (!isName(text.codeUnitAt(i))) return span;
+    i--;
+    while (i >= 0 && isName(text.codeUnitAt(i))) {
+      i--;
+    }
+
+    // If the name didn't start with [isNameStart], it's not a valid identifier.
+    if (!isNameStart(text.codeUnitAt(i + 1))) return span;
+
+    // Trim because it's possible that this span is empty (for example, a mixin
+    // may be declared without an argument list).
+    return span.file.span(i + 1, span.end.offset).trim();
+  }
+
   /// The name of the rest argument as written in the document, without
   /// underscores converted to hyphens and including the leading `$`.
   ///
@@ -47,16 +74,15 @@ class ArgumentDeclaration implements SassNode {
       : arguments = const [],
         restArgument = null;
 
-  /// Parses an argument declaration from [contents], which should not include
-  /// parentheses.
+  /// Parses an argument declaration from [contents], which should be of the
+  /// form `@rule name(args) {`.
   ///
   /// If passed, [url] is the name of the file from which [contents] comes.
   ///
   /// Throws a [SassFormatException] if parsing fails.
   factory ArgumentDeclaration.parse(String contents,
           {Object url, Logger logger}) =>
-      ScssParser("($contents)", url: url, logger: logger)
-          .parseArgumentDeclaration();
+      ScssParser(contents, url: url, logger: logger).parseArgumentDeclaration();
 
   /// Throws a [SassScriptException] if [positional] and [names] aren't valid
   /// for this argument declaration.
@@ -73,27 +99,34 @@ class ArgumentDeclaration implements SassNode {
       } else if (names.contains(argument.name)) {
         namedUsed++;
       } else if (argument.defaultValue == null) {
-        throw SassScriptException(
-            "Missing argument ${_originalArgumentName(argument.name)}.");
+        throw MultiSpanSassScriptException(
+            "Missing argument ${_originalArgumentName(argument.name)}.",
+            "invocation",
+            {spanWithName: "declaration"});
       }
     }
 
     if (restArgument != null) return;
 
     if (positional > arguments.length) {
-      throw SassScriptException("Only ${arguments.length} "
-          "${names.isEmpty ? '' : 'positional '}"
-          "${pluralize('argument', arguments.length)} allowed, but "
-          "${positional} ${pluralize('was', positional, plural: 'were')} "
-          "passed.");
+      throw MultiSpanSassScriptException(
+          "Only ${arguments.length} "
+              "${names.isEmpty ? '' : 'positional '}"
+              "${pluralize('argument', arguments.length)} allowed, but "
+              "${positional} ${pluralize('was', positional, plural: 'were')} "
+              "passed.",
+          "invocation",
+          {spanWithName: "declaration"});
     }
 
     if (namedUsed < names.length) {
       var unknownNames = Set.of(names)
         ..removeAll(arguments.map((argument) => argument.name));
-      throw SassScriptException(
+      throw MultiSpanSassScriptException(
           "No ${pluralize('argument', unknownNames.length)} named "
-          "${toSentence(unknownNames.map((name) => "\$$name"), 'or')}.");
+              "${toSentence(unknownNames.map((name) => "\$$name"), 'or')}.",
+          "invocation",
+          {spanWithName: "declaration"});
     }
   }
 

lib/src/ast/sass/expression/if.dart

@@ -17,8 +17,8 @@ import '../callable_invocation.dart';
 /// evaluated.
 class IfExpression implements Expression, CallableInvocation {
   /// The declaration of `if()`, as though it were a normal function.
-  static final declaration =
-      ArgumentDeclaration.parse(r"$condition, $if-true, $if-false");
+  static final declaration = ArgumentDeclaration.parse(
+      r"@function if($condition, $if-true, $if-false) {");
 
   /// The arguments passed to `if()`.
   final ArgumentInvocation arguments;

lib/src/ast/sass/statement/include_rule.dart

@@ -4,6 +4,7 @@
 
 import 'package:source_span/source_span.dart';
 
+import '../../../utils.dart';
 import '../../../visitor/interface/statement.dart';
 import '../argument_invocation.dart';
 import '../callable_invocation.dart';
@@ -29,6 +30,11 @@ class IncludeRule implements Statement, CallableInvocation {
 
   final FileSpan span;
 
+  /// Returns this include's span, without its content block (if it has one).
+  FileSpan get spanWithoutContent => content == null
+      ? span
+      : span.file.span(span.start.offset, arguments.span.end.offset).trim();
+
   IncludeRule(this.name, this.arguments, this.span,
       {this.namespace, this.content});
 

lib/src/callable.dart

@@ -15,8 +15,8 @@ export 'callable/built_in.dart';
 export 'callable/plain_css.dart';
 export 'callable/user_defined.dart';
 
-/// An interface functions and mixins that can be invoked from Sass by passing
-/// in arguments.
+/// An interface for functions and mixins that can be invoked from Sass by
+/// passing in arguments.
 ///
 /// This extends [AsyncCallable] because all synchronous callables are also
 /// usable in asynchronous contexts. [Callable]s are usable with both the
@@ -65,7 +65,12 @@ export 'callable/user_defined.dart';
 ///   access a string's length in code points.
 @sealed
 abstract class Callable extends AsyncCallable {
-  /// Creates a callable with the given [name] and [arguments] that runs
+  @Deprecated('Use `new Callable.function` instead.')
+  factory Callable(String name, String arguments,
+          ext.Value callback(List<ext.Value> arguments)) =>
+      Callable.function(name, arguments, callback);
+
+  /// Creates a function with the given [name] and [arguments] that runs
   /// [callback] when called.
   ///
   /// The argument declaration is parsed from [arguments], which uses the same
@@ -80,7 +85,8 @@ abstract class Callable extends AsyncCallable {
   /// For example:
   ///
   /// ```dart
-  /// new Callable("str-split", r'$string, $divider: " "', (arguments) {
+  /// new Callable.function("str-split", r'$string, $divider: " "',
+  ///     (arguments) {
   ///   var string = arguments[0].assertString("string");
   ///   var divider = arguments[1].assertString("divider");
   ///   return new SassList(
@@ -90,12 +96,12 @@ abstract class Callable extends AsyncCallable {
   /// });
   /// ```
   ///
-  /// Callables may also take variable length argument lists. These are declared
+  /// Functions may also take variable length argument lists. These are declared
   /// the same way as in Sass, and are passed as the final argument to the
   /// callback. For example:
   ///
   /// ```dart
-  /// new Callable("str-join", r'$strings...', (arguments) {
+  /// new Callable.function("str-join", r'$strings...', (arguments) {
   ///   var args = arguments.first as SassArgumentList;
   ///   var strings = args.map((arg) => arg.assertString()).toList();
   ///   return new SassString(strings.map((string) => string.text).join(),
@@ -106,8 +112,8 @@ abstract class Callable extends AsyncCallable {
   /// Note that the argument list is always an instance of [SassArgumentList],
   /// which provides access to keyword arguments using
   /// [SassArgumentList.keywords].
-  factory Callable(String name, String arguments,
+  factory Callable.function(String name, String arguments,
           ext.Value callback(List<ext.Value> arguments)) =>
-      BuiltInCallable(
+      BuiltInCallable.function(
           name, arguments, (arguments) => callback(arguments) as Value);
 }

lib/src/callable/async.dart

@@ -10,8 +10,8 @@ import '../value.dart';
 import '../value/external/value.dart' as ext;
 import 'async_built_in.dart';
 
-/// An interface functions and mixins that can be invoked from Sass by passing
-/// in arguments.
+/// An interface for functions and mixins that can be invoked from Sass by
+/// passing in arguments.
 ///
 /// This class represents callables that *need* to do asynchronous work. It's
 /// only compatible with the asynchonous `compile()` methods. If a callback can
@@ -23,16 +23,21 @@ abstract class AsyncCallable {
   /// The callable's name.
   String get name;
 
+  @Deprecated('Use `new AsyncCallable.function` instead.')
+  factory AsyncCallable(String name, String arguments,
+          FutureOr<ext.Value> callback(List<ext.Value> arguments)) =>
+      AsyncCallable.function(name, arguments, callback);
+
   /// Creates a callable with the given [name] and [arguments] that runs
   /// [callback] when called.
   ///
   /// The argument declaration is parsed from [arguments], which should not
   /// include parentheses. Throws a [SassFormatException] if parsing fails.
   ///
   /// See [new Callable] for more details.
-  factory AsyncCallable(String name, String arguments,
+  factory AsyncCallable.function(String name, String arguments,
           FutureOr<ext.Value> callback(List<ext.Value> arguments)) =>
-      AsyncBuiltInCallable(name, arguments, (arguments) {
+      AsyncBuiltInCallable.function(name, arguments, (arguments) {
         var result = callback(arguments);
         if (result is ext.Value) return result as Value;
         return (result as Future<ext.Value>).then((value) => value as Value);

lib/src/callable/async_built_in.dart

@@ -22,36 +22,49 @@ typedef _Callback = FutureOr<Value> Function(List<Value> arguments);
 class AsyncBuiltInCallable implements AsyncCallable {
   final String name;
 
-  /// The overloads declared for this callable.
-  final _overloads = <Tuple2<ArgumentDeclaration, _Callback>>[];
+  /// This callable's arguments.
+  final ArgumentDeclaration _arguments;
 
-  /// Creates a callable with a single [arguments] declaration and a single
+  /// The callback to run when executing this callable.
+  final _Callback _callback;
+
+  /// Creates a function with a single [arguments] declaration and a single
   /// [callback].
   ///
   /// The argument declaration is parsed from [arguments], which should not
   /// include parentheses. Throws a [SassFormatException] if parsing fails.
-  AsyncBuiltInCallable(String name, String arguments,
-      FutureOr<Value> callback(List<Value> arguments))
-      : this.parsed(name, ArgumentDeclaration.parse(arguments), callback);
+  ///
+  /// If passed, [url] is the URL of the module in which the function is
+  /// defined.
+  AsyncBuiltInCallable.function(String name, String arguments,
+      FutureOr<Value> callback(List<Value> arguments), {Object url})
+      : this.parsed(
+            name,
+            ArgumentDeclaration.parse('@function $name($arguments) {',
+                url: url),
+            callback);
 
-  /// Creates a callable with a single [arguments] declaration and a single
+  /// Creates a mixin with a single [arguments] declaration and a single
   /// [callback].
-  AsyncBuiltInCallable.parsed(this.name, ArgumentDeclaration arguments,
-      FutureOr<Value> callback(List<Value> arguments)) {
-    _overloads.add(Tuple2(arguments, callback));
-  }
-
-  /// Creates a callable with multiple implementations.
   ///
-  /// Each key/value pair in [overloads] defines the argument declaration for
-  /// the overload (which should not include parentheses), and the callback to
-  /// execute if that argument declaration matches. Throws a
-  /// [SassFormatException] if parsing fails.
-  AsyncBuiltInCallable.overloaded(this.name, Map<String, _Callback> overloads) {
-    overloads.forEach((arguments, callback) {
-      _overloads.add(Tuple2(ArgumentDeclaration.parse(arguments), callback));
-    });
-  }
+  /// The argument declaration is parsed from [arguments], which should not
+  /// include parentheses. Throws a [SassFormatException] if parsing fails.
+  ///
+  /// If passed, [url] is the URL of the module in which the mixin is
+  /// defined.
+  AsyncBuiltInCallable.mixin(String name, String arguments,
+      FutureOr<void> callback(List<Value> arguments),
+      {Object url})
+      : this.parsed(name,
+            ArgumentDeclaration.parse('@mixin $name($arguments) {', url: url),
+            (arguments) async {
+          await callback(arguments);
+          return null;
+        });
+
+  /// Creates a callable with a single [arguments] declaration and a single
+  /// [callback].
+  AsyncBuiltInCallable.parsed(this.name, this._arguments, this._callback);
 
   /// Returns the argument declaration and Dart callback for the given
   /// positional and named arguments.
@@ -60,28 +73,6 @@ class AsyncBuiltInCallable implements AsyncCallable {
   /// doesn't guarantee that [positional] and [names] are valid for the returned
   /// [ArgumentDeclaration].
   Tuple2<ArgumentDeclaration, _Callback> callbackFor(
-      int positional, Set<String> names) {
-    Tuple2<ArgumentDeclaration, _Callback> fuzzyMatch;
-    int minMismatchDistance;
-
-    for (var overload in _overloads) {
-      // Ideally, find an exact match.
-      if (overload.item1.matches(positional, names)) return overload;
-
-      var mismatchDistance = overload.item1.arguments.length - positional;
-
-      if (minMismatchDistance != null) {
-        if (mismatchDistance.abs() > minMismatchDistance.abs()) continue;
-        // If two overloads have the same mismatch distance, favor the overload
-        // that has more arguments.
-        if (mismatchDistance.abs() == minMismatchDistance.abs() &&
-            mismatchDistance < 0) continue;
-      }
-
-      minMismatchDistance = mismatchDistance;
-      fuzzyMatch = overload;
-    }
-
-    return fuzzyMatch;
-  }
+          int positional, Set<String> names) =>
+      Tuple2(_arguments, _callback);
 }