Support configuring modules through imports (#885)

Fixes #882

See sass/sass-spec#1497

Author: jathak

CHANGELOG.md

@@ -1,5 +1,9 @@
 ## 1.24.0
 
+* Support configuring modules through `@import` rules.
+
+## 1.23.8
+
 * **Potentially breaking bug fix:** Members loaded through a nested `@import`
   are no longer ever accessible outside that nested context.
 
@@ -14,7 +18,7 @@
 
 ## 1.23.7
 
-* No user-visible changes.
+* No user-visible changes
 
 ## 1.23.6
 

lib/src/async_environment.dart

@@ -13,6 +13,8 @@ import 'ast/css.dart';
 import 'ast/node.dart';
 import 'ast/sass.dart';
 import 'callable.dart';
+import 'configuration.dart';
+import 'configured_value.dart';
 import 'exception.dart';
 import 'extend/extender.dart';
 import 'module.dart';
@@ -730,6 +732,23 @@ class AsyncEnvironment {
     }
   }
 
+  /// Creates an implicit configuration from the variables declared in this
+  /// environment.
+  Configuration toImplicitConfiguration() {
+    var configuration = <String, ConfiguredValue>{};
+    for (var i = 0; i < _variables.length; i++) {
+      var values = _variables[i];
+      var nodes =
+          _variableNodes == null ? <String, AstNode>{} : _variableNodes[i];
+      for (var name in values.keys) {
+        // Implicit configurations are never invalid, making [configurationSpan]
+        // unnecessary, so we pass null here to avoid having to compute it.
+        configuration[name] = ConfiguredValue(values[name], null, nodes[name]);
+      }
+    }
+    return Configuration(configuration, isImplicit: true);
+  }
+
   /// Returns a module that represents the top-level members defined in [this],
   /// that contains [css] as its CSS tree, which can be extended using
   /// [extender].

lib/src/configuration.dart

@@ -0,0 +1,77 @@
+// Copyright 2019 Google LLC. Use of this source code is governed by an
+// MIT-style license that can be found in the LICENSE file or at
+// https://opensource.org/licenses/MIT.
+
+import 'dart:collection';
+
+import 'ast/sass.dart';
+import 'configured_value.dart';
+import 'util/limited_map_view.dart';
+import 'util/unprefixed_map_view.dart';
+
+/// A set of variables meant to configure a module by overriding its
+/// `!default` declarations.
+class Configuration {
+  /// A map from variable names (without `$`) to values.
+  ///
+  /// This map may not be modified directly. To remove a value from this
+  /// configuration, use the [remove] method.
+  Map<String, ConfiguredValue> get values => UnmodifiableMapView(_values);
+  final Map<String, ConfiguredValue> _values;
+
+  /// Whether or not this configuration is implicit.
+  ///
+  /// Implicit configurations are created when a file containing a `@forward`
+  /// rule is imported, while explicit configurations are created by the
+  /// `with` clause of a `@use` rule.
+  ///
+  /// Both types of configuration pass through `@forward` rules, but explicit
+  /// configurations will cause an error if attempting to use them on a module
+  /// that has already been loaded, while implicit configurations will be
+  /// silently ignored in this case.
+  final bool isImplicit;
+
+  Configuration(Map<String, ConfiguredValue> values, {this.isImplicit = false})
+      : _values = values;
+
+  /// The empty configuration, which indicates that the module has not been
+  /// configured.
+  ///
+  /// Empty configurations are always considered implicit, since they are
+  /// ignored if the module has already been loaded.
+  const Configuration.empty()
+      : _values = const {},
+        isImplicit = true;
+
+  bool get isEmpty => values.isEmpty;
+
+  /// Removes a variable with [name] from this configuration, returning it.
+  ///
+  /// If no such variable exists in this configuration, returns null.
+  ConfiguredValue remove(String name) => isEmpty ? null : _values.remove(name);
+
+  /// Creates a new configuration from this one based on a `@forward` rule.
+  Configuration throughForward(ForwardRule forward) {
+    if (isEmpty) return const Configuration.empty();
+    var newValues = _values;
+
+    // Only allow variables that are visible through the `@forward` to be
+    // configured. These views support [Map.remove] so we can mark when a
+    // configuration variable is used by removing it even when the underlying
+    // map is wrapped.
+    if (forward.prefix != null) {
+      newValues = UnprefixedMapView(newValues, forward.prefix);
+    }
+    if (forward.shownVariables != null) {
+      newValues = LimitedMapView.whitelist(newValues, forward.shownVariables);
+    } else if (forward.hiddenVariables?.isNotEmpty ?? false) {
+      newValues = LimitedMapView.blacklist(newValues, forward.hiddenVariables);
+    }
+    return Configuration(newValues, isImplicit: isImplicit);
+  }
+
+  /// Creates a copy of this configuration.
+  Configuration clone() => isEmpty
+      ? const Configuration.empty()
+      : Configuration({...values}, isImplicit: isImplicit);
+}

lib/src/configured_value.dart

@@ -0,0 +1,25 @@
+// Copyright 2019 Google LLC. Use of this source code is governed by an
+// MIT-style license that can be found in the LICENSE file or at
+// https://opensource.org/licenses/MIT.
+
+import 'package:source_span/source_span.dart';
+
+import 'ast/node.dart';
+import 'value.dart';
+
+/// A variable value that's been configured for a [Configuration].
+class ConfiguredValue {
+  /// The value of the variable.
+  final Value value;
+
+  /// The span where the variable's configuration was written.
+  final FileSpan configurationSpan;
+
+  /// The [AstNode] where the variable's value originated.
+  ///
+  /// This is used to generate source maps and can be `null` if source map
+  /// generation is disabled.
+  final AstNode assignmentNode;
+
+  ConfiguredValue(this.value, this.configurationSpan, [this.assignmentNode]);
+}

lib/src/environment.dart

@@ -5,7 +5,7 @@
 // DO NOT EDIT. This file was generated from async_environment.dart.
 // See tool/grind/synchronize.dart for details.
 //
-// Checksum: 0459cbe5c439f3d45f24b739ed1f36b517d338b8
+// Checksum: 7da67a8956ec74db270764e941b674dcc315a488
 //
 // ignore_for_file: unused_import
 
@@ -19,6 +19,8 @@ import 'ast/css.dart';
 import 'ast/node.dart';
 import 'ast/sass.dart';
 import 'callable.dart';
+import 'configuration.dart';
+import 'configured_value.dart';
 import 'exception.dart';
 import 'extend/extender.dart';
 import 'module.dart';
@@ -734,6 +736,23 @@ class Environment {
     }
   }
 
+  /// Creates an implicit configuration from the variables declared in this
+  /// environment.
+  Configuration toImplicitConfiguration() {
+    var configuration = <String, ConfiguredValue>{};
+    for (var i = 0; i < _variables.length; i++) {
+      var values = _variables[i];
+      var nodes =
+          _variableNodes == null ? <String, AstNode>{} : _variableNodes[i];
+      for (var name in values.keys) {
+        // Implicit configurations are never invalid, making [configurationSpan]
+        // unnecessary, so we pass null here to avoid having to compute it.
+        configuration[name] = ConfiguredValue(values[name], null, nodes[name]);
+      }
+    }
+    return Configuration(configuration, isImplicit: true);
+  }
+
   /// Returns a module that represents the top-level members defined in [this],
   /// that contains [css] as its CSS tree, which can be extended using
   /// [extender].