[meta.load] Add support for meta.load() and related features

Author: nex3

CHANGELOG.md

@@ -1,3 +1,19 @@
+## 1.105.0
+
+* Add support for first-class modules. These can be accessed using the new
+  `meta.load()` and `meta.get-module()` functions, and may be passed as the
+  `$module` argument to numerous eisting `sass:meta` functions.
+
+* Add the `meta.css()` mixin, which includes CSS from a first-class module.
+
+### JS API
+
+* Add a `SassModule` class and a corresponding `Value.assertModule()` method.
+
+### Dart API
+
+* Add a `SassModule` class and a corresponding `Value.assertModule()` method.
+
 ## 1.104.1
 
 * Fix a bug where loud comments before `@use` rules could be emitted multiple

lib/src/async_environment.dart

@@ -438,7 +438,7 @@ final class AsyncEnvironment {
   /// Throws a [SassScriptException] if there is no module named [namespace], or
   /// if multiple global modules expose variables named [name].
   Value? getVariable(String name, {String? namespace}) {
-    if (namespace != null) return _getModule(namespace).variables[name];
+    if (namespace != null) return getModule(namespace).variables[name];
 
     if (_lastVariableName == name) {
       return _variables[_lastVariableIndex!][name] ??
@@ -477,7 +477,7 @@ final class AsyncEnvironment {
   /// required, since some nodes need to do real work to manufacture a source
   /// span.
   AstNode? getVariableNode(String name, {String? namespace}) {
-    if (namespace != null) return _getModule(namespace).variableNodes[name];
+    if (namespace != null) return getModule(namespace).variableNodes[name];
 
     if (_lastVariableName == name) {
       return _variableNodes[_lastVariableIndex!][name] ??
@@ -526,7 +526,7 @@ final class AsyncEnvironment {
   /// if multiple global modules expose functions named [name].
   bool globalVariableExists(String name, {String? namespace}) {
     if (namespace != null) {
-      return _getModule(namespace).variables.containsKey(name);
+      return getModule(namespace).variables.containsKey(name);
     }
     if (_variables.first.containsKey(name)) return true;
     return _getVariableFromGlobalModule(name) != null;
@@ -567,7 +567,7 @@ final class AsyncEnvironment {
     bool global = false,
   }) {
     if (namespace != null) {
-      _getModule(namespace).setVariable(name, value, nodeWithSpan);
+      getModule(namespace).setVariable(name, value, nodeWithSpan);
       return;
     }
 
@@ -663,7 +663,7 @@ final class AsyncEnvironment {
   /// Throws a [SassScriptException] if there is no module named [namespace], or
   /// if multiple global modules expose functions named [name].
   AsyncCallable? getFunction(String name, {String? namespace}) {
-    if (namespace != null) return _getModule(namespace).functions[name];
+    if (namespace != null) return getModule(namespace).functions[name];
 
     if (_functionIndices[name] case var index?) {
       return _functions[index][name] ?? _getFunctionFromGlobalModule(name);
@@ -710,7 +710,7 @@ final class AsyncEnvironment {
   /// Throws a [SassScriptException] if there is no module named [namespace], or
   /// if multiple global modules expose mixins named [name].
   AsyncCallable? getMixin(String name, {String? namespace}) {
-    if (namespace != null) return _getModule(namespace).mixins[name];
+    if (namespace != null) return getModule(namespace).mixins[name];
 
     if (_mixinIndices[name] case var index?) {
       return _mixins[index][name] ?? _getMixinFromGlobalModule(name);
@@ -891,10 +891,10 @@ final class AsyncEnvironment {
 
   /// Returns the module with the given [namespace], or throws a
   /// [SassScriptException] if none exists.
-  Module _getModule(String namespace) {
+  Module getModule(String namespace) {
     if (_modules[namespace] case var module?) return module;
     throw SassScriptException(
-      'There is no module with the namespace "$namespace".',
+      'There is no module with namespace "$namespace".',
     );
   }
 

lib/src/embedded/compilation_dispatcher.dart

@@ -17,6 +17,7 @@ import 'package:sass/src/importer/node_package.dart' as npi;
 import '../logger.dart';
 import '../value/function.dart';
 import '../value/mixin.dart';
+import '../value/module.dart';
 import 'embedded_sass.pb.dart';
 import 'opaque_registry.dart';
 import 'host_callable.dart';
@@ -108,6 +109,7 @@ final class CompilationDispatcher(
   ) {
     var functions = OpaqueRegistry<SassFunction>();
     var mixins = OpaqueRegistry<SassMixin>();
+    var modules = OpaqueRegistry<SassModule>();
 
     sass.OutputStyle style = request.style == OutputStyle.COMPRESSED
         ? .compressed
@@ -161,7 +163,8 @@ final class CompilationDispatcher(
       );
 
       var globalFunctions = request.globalFunctions.map(
-        (signature) => hostCallable(this, functions, mixins, signature),
+        (signature) =>
+            hostCallable(this, functions, mixins, modules, signature),
       );
 
       late sass.CompileResult result;

lib/src/embedded/host_callable.dart

@@ -6,6 +6,7 @@ import '../callable.dart';
 import '../exception.dart';
 import '../value/function.dart';
 import '../value/mixin.dart';
+import '../value/module.dart';
 import 'compilation_dispatcher.dart';
 import 'embedded_sass.pb.dart';
 import 'opaque_registry.dart';
@@ -24,12 +25,13 @@ Callable hostCallable(
   CompilationDispatcher dispatcher,
   OpaqueRegistry<SassFunction> functions,
   OpaqueRegistry<SassMixin> mixins,
+  OpaqueRegistry<SassModule> modules,
   String signature, {
   int? id,
 }) {
   late Callable callable;
   callable = Callable.fromSignature(signature, (arguments) {
-    var protofier = Protofier(dispatcher, functions, mixins);
+    var protofier = Protofier(dispatcher, functions, mixins, modules);
     var request = OutboundMessage_FunctionCallRequest()
       ..arguments.addAll([
         for (var argument in arguments) protofier.protofy(argument),

lib/src/embedded/protofier.dart

@@ -25,6 +25,9 @@ final class Protofier(
 
   /// The IDs of first-class mixins.
   final OpaqueRegistry<SassMixin> _mixins,
+
+  /// The IDs of first-class modules.
+  final OpaqueRegistry<SassModule> _modules,
 ) {
   /// Any argument lists transitively contained in [value].
   ///
@@ -93,6 +96,8 @@ final class Protofier(
         );
       case SassMixin():
         result.compilerMixin = Value_CompilerMixin(id: _mixins.getId(value));
+      case SassModule():
+        result.compilerModule = Value_CompilerModule(id: _modules.getId(value));
       case sassTrue:
         result.singleton = SingletonValue.TRUE;
       case sassFalse:
@@ -304,6 +309,7 @@ final class Protofier(
               _dispatcher,
               _functions,
               _mixins,
+              _modules,
               value.hostFunction.signature,
               id: value.hostFunction.id,
             ),
@@ -316,6 +322,13 @@ final class Protofier(
             "CompilerMixin.id $id doesn't match any known mixins",
           );
 
+        case Value_Value.compilerModule:
+          var id = value.compilerModule.id;
+          if (_modules[id] case var module?) return module;
+          throw paramsError(
+            "CompilerModule.id $id doesn't match any known modules.",
+          );
+
         case Value_Value.calculation:
           return _deprotofyCalculation(value.calculation);
 

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: 6d84948495bad10a2416f6d51fd568322523c5e6
+// Checksum: 7b9b411c85ad6da89891b089912cc52c673fc801
 //
 // ignore_for_file: unused_import
 
@@ -449,7 +449,7 @@ final class Environment {
   /// Throws a [SassScriptException] if there is no module named [namespace], or
   /// if multiple global modules expose variables named [name].
   Value? getVariable(String name, {String? namespace}) {
-    if (namespace != null) return _getModule(namespace).variables[name];
+    if (namespace != null) return getModule(namespace).variables[name];
 
     if (_lastVariableName == name) {
       return _variables[_lastVariableIndex!][name] ??
@@ -488,7 +488,7 @@ final class Environment {
   /// required, since some nodes need to do real work to manufacture a source
   /// span.
   AstNode? getVariableNode(String name, {String? namespace}) {
-    if (namespace != null) return _getModule(namespace).variableNodes[name];
+    if (namespace != null) return getModule(namespace).variableNodes[name];
 
     if (_lastVariableName == name) {
       return _variableNodes[_lastVariableIndex!][name] ??
@@ -537,7 +537,7 @@ final class Environment {
   /// if multiple global modules expose functions named [name].
   bool globalVariableExists(String name, {String? namespace}) {
     if (namespace != null) {
-      return _getModule(namespace).variables.containsKey(name);
+      return getModule(namespace).variables.containsKey(name);
     }
     if (_variables.first.containsKey(name)) return true;
     return _getVariableFromGlobalModule(name) != null;
@@ -578,7 +578,7 @@ final class Environment {
     bool global = false,
   }) {
     if (namespace != null) {
-      _getModule(namespace).setVariable(name, value, nodeWithSpan);
+      getModule(namespace).setVariable(name, value, nodeWithSpan);
       return;
     }
 
@@ -674,7 +674,7 @@ final class Environment {
   /// Throws a [SassScriptException] if there is no module named [namespace], or
   /// if multiple global modules expose functions named [name].
   Callable? getFunction(String name, {String? namespace}) {
-    if (namespace != null) return _getModule(namespace).functions[name];
+    if (namespace != null) return getModule(namespace).functions[name];
 
     if (_functionIndices[name] case var index?) {
       return _functions[index][name] ?? _getFunctionFromGlobalModule(name);
@@ -721,7 +721,7 @@ final class Environment {
   /// Throws a [SassScriptException] if there is no module named [namespace], or
   /// if multiple global modules expose mixins named [name].
   Callable? getMixin(String name, {String? namespace}) {
-    if (namespace != null) return _getModule(namespace).mixins[name];
+    if (namespace != null) return getModule(namespace).mixins[name];
 
     if (_mixinIndices[name] case var index?) {
       return _mixins[index][name] ?? _getMixinFromGlobalModule(name);
@@ -902,10 +902,10 @@ final class Environment {
 
   /// Returns the module with the given [namespace], or throws a
   /// [SassScriptException] if none exists.
-  Module<Callable> _getModule(String namespace) {
+  Module<Callable> getModule(String namespace) {
     if (_modules[namespace] case var module?) return module;
     throw SassScriptException(
-      'There is no module with the namespace "$namespace".',
+      'There is no module with namespace "$namespace".',
     );
   }
 

lib/src/functions/meta.dart

@@ -63,6 +63,7 @@ final _shared = UnmodifiableListView([
       SassNumber() => "number",
       SassFunction() => "function",
       SassMixin() => "mixin",
+      SassModule() => "module",
       SassCalculation() => "calculation",
       SassString() => "string",
       _ => throw "[BUG] Unknown value type ${arguments[0]}",

lib/src/js.dart

@@ -50,6 +50,7 @@ void main() {
   exports.SassColor = colorClass;
   exports.SassFunction = functionClass;
   exports.SassMixin = mixinClass;
+  exports.SassModule = moduleClass;
   exports.SassList = listClass;
   exports.SassMap = mapClass;
   exports.SassNumber = numberClass;

lib/src/js/exports.dart

@@ -40,6 +40,7 @@ class Exports {
   external set SassColor(JSClass function);
   external set SassFunction(JSClass function);
   external set SassMixin(JSClass mixin);
+  external set SassModule(JSClass mixin);
   external set SassList(JSClass function);
   external set SassMap(JSClass function);
   external set SassNumber(JSClass function);

lib/src/js/value.dart

@@ -16,6 +16,7 @@ export 'value/function.dart';
 export 'value/list.dart';
 export 'value/map.dart';
 export 'value/mixin.dart';
+export 'value/module.dart';
 export 'value/number.dart';
 export 'value/string.dart';
 
@@ -44,6 +45,7 @@ final JSClass valueClass = () {
     'assertFunction': (Value self, [String? name]) => self.assertFunction(name),
     'assertMap': (Value self, [String? name]) => self.assertMap(name),
     'assertMixin': (Value self, [String? name]) => self.assertMixin(name),
+    'assertModule': (Value self, [String? name]) => self.assertModule(name),
     'assertNumber': (Value self, [String? name]) => self.assertNumber(name),
     'assertString': (Value self, [String? name]) => self.assertString(name),
     'tryMap': (Value self) => self.tryMap(),