Skip to content

Commit 717867b

Browse files
jathakjathak
authoredSep 5, 2024··
Add a future global-builtin deprecation (#2336)
·
sass-parser/0.4.161.79.0
1 parent 5dff2e8 commit 717867b

17 files changed

+163
-61
lines changed
 

‎CHANGELOG.md

+8
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,11 @@
1+
## 1.79.0
2+
3+
* Add a `global-builtin` future deprecation, which can be opted-into with the
4+
`--future-deprecation` flag or the `futureDeprecations` option in the JS or
5+
Dart API. This emits warnings when any global built-in functions that are
6+
now available in `sass:` modules are called. It will become active by default
7+
in an upcoming release alongside the `@import` deprecation.
8+
19
## 1.78.0
210

311
* The `meta.feature-exists` function is now deprecated. This deprecation is

‎lib/src/callable.dart

+2-1
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,8 @@ import 'utils.dart';
1111
import 'value.dart';
1212

1313
export 'callable/async.dart';
14-
export 'callable/async_built_in.dart' show AsyncBuiltInCallable;
14+
export 'callable/async_built_in.dart'
15+
show AsyncBuiltInCallable, warnForGlobalBuiltIn;
1516
export 'callable/built_in.dart' show BuiltInCallable;
1617
export 'callable/plain_css.dart';
1718
export 'callable/user_defined.dart';

‎lib/src/callable/async_built_in.dart

+20
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@
55
import 'dart:async';
66

77
import '../ast/sass.dart';
8+
import '../deprecation.dart';
9+
import '../evaluation_context.dart';
810
import '../value.dart';
911
import 'async.dart';
1012

@@ -83,4 +85,22 @@ class AsyncBuiltInCallable implements AsyncCallable {
8385
(ArgumentDeclaration, Callback) callbackFor(
8486
int positional, Set<String> names) =>
8587
(_arguments, _callback);
88+
89+
/// Returns a copy of this callable that emits a deprecation warning.
90+
AsyncBuiltInCallable withDeprecationWarning(String module,
91+
[String? newName]) =>
92+
AsyncBuiltInCallable.parsed(name, _arguments, (args) {
93+
warnForGlobalBuiltIn(module, newName ?? name);
94+
return _callback(args);
95+
}, acceptsContent: acceptsContent);
96+
}
97+
98+
/// Emits a deprecation warning for a global built-in function that is now
99+
/// available as function [name] in built-in module [module].
100+
void warnForGlobalBuiltIn(String module, String name) {
101+
warnForDeprecation(
102+
'Global built-in functions will be deprecated in the future.\n'
103+
'Remove the --future-deprecation=global-builtin flag to silence this '
104+
'warning for now.',
105+
Deprecation.globalBuiltin);
86106
}

‎lib/src/callable/built_in.dart

+16
Original file line numberDiff line numberDiff line change
@@ -123,4 +123,20 @@ final class BuiltInCallable implements Callable, AsyncBuiltInCallable {
123123
/// Returns a copy of this callable with the given [name].
124124
BuiltInCallable withName(String name) =>
125125
BuiltInCallable._(name, _overloads, acceptsContent);
126+
127+
/// Returns a copy of this callable that emits a deprecation warning.
128+
BuiltInCallable withDeprecationWarning(String module, [String? newName]) =>
129+
BuiltInCallable._(
130+
name,
131+
[
132+
for (var (declaration, function) in _overloads)
133+
(
134+
declaration,
135+
(args) {
136+
warnForGlobalBuiltIn(module, newName ?? name);
137+
return function(args);
138+
}
139+
)
140+
],
141+
acceptsContent);
126142
}

‎lib/src/deprecation.dart

+6-1
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ enum Deprecation {
1515
// DO NOT EDIT. This section was generated from the language repo.
1616
// See tool/grind/generate_deprecations.dart for details.
1717
//
18-
// Checksum: dd5c6aa0f1431fa9fc88bb71a96f832adbc165f5
18+
// Checksum: bf841a728263bf7efc2a85a091330a1f8074e067
1919

2020
/// Deprecation for passing a string directly to meta.call().
2121
callString('call-string',
@@ -102,6 +102,11 @@ enum Deprecation {
102102
/// Deprecation for @import rules.
103103
import.future('import', description: '@import rules.'),
104104

105+
/// Deprecation for global built-in functions that are available in sass: modules.
106+
globalBuiltin.future('global-builtin',
107+
description:
108+
'Global built-in functions that are available in sass: modules.'),
109+
105110
// END AUTOGENERATED CODE
106111

107112
/// Used for deprecations coming from user-authored code.

‎lib/src/functions/color.dart

+26-15
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,8 @@ final _microsoftFilterStart = RegExp(r'^[a-zA-Z]+\s*=');
2323
/// The global definitions of Sass color functions.
2424
final global = UnmodifiableListView([
2525
// ### RGB
26-
_red, _green, _blue, _mix,
26+
_red.withDeprecationWarning('color'), _green.withDeprecationWarning('color'),
27+
_blue.withDeprecationWarning('color'), _mix.withDeprecationWarning('color'),
2728

2829
BuiltInCallable.overloadedFunction("rgb", {
2930
r"$red, $green, $blue, $alpha": (arguments) => _rgb("rgb", arguments),
@@ -66,10 +67,13 @@ final global = UnmodifiableListView([
6667
red: 255 - color.red, green: 255 - color.green, blue: 255 - color.blue);
6768

6869
return _mixColors(inverse, color, weight);
69-
}),
70+
}).withDeprecationWarning('color'),
7071

7172
// ### HSL
72-
_hue, _saturation, _lightness, _complement,
73+
_hue.withDeprecationWarning('color'),
74+
_saturation.withDeprecationWarning('color'),
75+
_lightness.withDeprecationWarning('color'),
76+
_complement.withDeprecationWarning('color'),
7377

7478
BuiltInCallable.overloadedFunction("hsl", {
7579
r"$hue, $saturation, $lightness, $alpha": (arguments) =>
@@ -116,7 +120,7 @@ final global = UnmodifiableListView([
116120
// Use the native CSS `grayscale` filter function.
117121
return _functionString('grayscale', arguments);
118122
}
119-
123+
warnForGlobalBuiltIn('color', 'grayscale');
120124
var color = arguments[0].assertColor("color");
121125
return color.changeHsl(saturation: 0);
122126
}),
@@ -125,23 +129,23 @@ final global = UnmodifiableListView([
125129
var color = arguments[0].assertColor("color");
126130
var degrees = _angleValue(arguments[1], "degrees");
127131
return color.changeHsl(hue: color.hue + degrees);
128-
}),
132+
}).withDeprecationWarning('color', 'adjust'),
129133

130134
_function("lighten", r"$color, $amount", (arguments) {
131135
var color = arguments[0].assertColor("color");
132136
var amount = arguments[1].assertNumber("amount");
133137
return color.changeHsl(
134138
lightness: (color.lightness + amount.valueInRange(0, 100, "amount"))
135139
.clamp(0, 100));
136-
}),
140+
}).withDeprecationWarning('color', 'adjust'),
137141

138142
_function("darken", r"$color, $amount", (arguments) {
139143
var color = arguments[0].assertColor("color");
140144
var amount = arguments[1].assertNumber("amount");
141145
return color.changeHsl(
142146
lightness: (color.lightness - amount.valueInRange(0, 100, "amount"))
143147
.clamp(0, 100));
144-
}),
148+
}).withDeprecationWarning('color', 'adjust'),
145149

146150
BuiltInCallable.overloadedFunction("saturate", {
147151
r"$amount": (arguments) {
@@ -153,6 +157,7 @@ final global = UnmodifiableListView([
153157
return SassString("saturate(${number.toCssString()})", quotes: false);
154158
},
155159
r"$color, $amount": (arguments) {
160+
warnForGlobalBuiltIn('color', 'adjust');
156161
var color = arguments[0].assertColor("color");
157162
var amount = arguments[1].assertNumber("amount");
158163
return color.changeHsl(
@@ -167,13 +172,17 @@ final global = UnmodifiableListView([
167172
return color.changeHsl(
168173
saturation: (color.saturation - amount.valueInRange(0, 100, "amount"))
169174
.clamp(0, 100));
170-
}),
175+
}).withDeprecationWarning('color', 'adjust'),
171176

172177
// ### Opacity
173-
_function("opacify", r"$color, $amount", _opacify),
174-
_function("fade-in", r"$color, $amount", _opacify),
175-
_function("transparentize", r"$color, $amount", _transparentize),
176-
_function("fade-out", r"$color, $amount", _transparentize),
178+
_function("opacify", r"$color, $amount", _opacify)
179+
.withDeprecationWarning('color', 'adjust'),
180+
_function("fade-in", r"$color, $amount", _opacify)
181+
.withDeprecationWarning('color', 'adjust'),
182+
_function("transparentize", r"$color, $amount", _transparentize)
183+
.withDeprecationWarning('color', 'adjust'),
184+
_function("fade-out", r"$color, $amount", _transparentize)
185+
.withDeprecationWarning('color', 'adjust'),
177186

178187
BuiltInCallable.overloadedFunction("alpha", {
179188
r"$color": (arguments) {
@@ -185,6 +194,7 @@ final global = UnmodifiableListView([
185194
return _functionString("alpha", arguments);
186195
}
187196

197+
warnForGlobalBuiltIn('color', 'alpha');
188198
var color = argument.assertColor("color");
189199
return SassNumber(color.alpha);
190200
},
@@ -215,15 +225,16 @@ final global = UnmodifiableListView([
215225
return _functionString("opacity", arguments);
216226
}
217227

228+
warnForGlobalBuiltIn('color', 'opacity');
218229
var color = arguments[0].assertColor("color");
219230
return SassNumber(color.alpha);
220231
}),
221232

222233
// ### Miscellaneous
223234
_ieHexStr,
224-
_adjust.withName("adjust-color"),
225-
_scale.withName("scale-color"),
226-
_change.withName("change-color")
235+
_adjust.withDeprecationWarning('color').withName("adjust-color"),
236+
_scale.withDeprecationWarning('color').withName("scale-color"),
237+
_change.withDeprecationWarning('color').withName("change-color")
227238
]);
228239

229240
/// The Sass color module.

‎lib/src/functions/list.dart

+9-2
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,15 @@ import '../value.dart';
1313

1414
/// The global definitions of Sass list functions.
1515
final global = UnmodifiableListView([
16-
_length, _nth, _setNth, _join, _append, _zip, _index, _isBracketed, //
17-
_separator.withName("list-separator")
16+
_length.withDeprecationWarning('list'),
17+
_nth.withDeprecationWarning('list'),
18+
_setNth.withDeprecationWarning('list'),
19+
_join.withDeprecationWarning('list'),
20+
_append.withDeprecationWarning('list'),
21+
_zip.withDeprecationWarning('list'),
22+
_index.withDeprecationWarning('list'),
23+
_isBracketed.withDeprecationWarning('list'),
24+
_separator.withDeprecationWarning('list').withName("list-separator")
1825
]);
1926

2027
/// The Sass list module.

‎lib/src/functions/map.dart

+6-6
Original file line numberDiff line numberDiff line change
@@ -15,12 +15,12 @@ import '../value.dart';
1515

1616
/// The global definitions of Sass map functions.
1717
final global = UnmodifiableListView([
18-
_get.withName("map-get"),
19-
_merge.withName("map-merge"),
20-
_remove.withName("map-remove"),
21-
_keys.withName("map-keys"),
22-
_values.withName("map-values"),
23-
_hasKey.withName("map-has-key")
18+
_get.withDeprecationWarning('map').withName("map-get"),
19+
_merge.withDeprecationWarning('map').withName("map-merge"),
20+
_remove.withDeprecationWarning('map').withName("map-remove"),
21+
_keys.withDeprecationWarning('map').withName("map-keys"),
22+
_values.withDeprecationWarning('map').withName("map-values"),
23+
_hasKey.withDeprecationWarning('map').withName("map-has-key")
2424
]);
2525

2626
/// The Sass map module.

‎lib/src/functions/math.dart

+12-4
Original file line numberDiff line numberDiff line change
@@ -30,15 +30,23 @@ final global = UnmodifiableListView([
3030
"To emit a CSS abs() now: abs(#{$number})\n"
3131
"More info: https://sass-lang.com/d/abs-percent",
3232
Deprecation.absPercent);
33+
} else {
34+
warnForGlobalBuiltIn('math', 'abs');
3335
}
3436
return SassNumber.withUnits(number.value.abs(),
3537
numeratorUnits: number.numeratorUnits,
3638
denominatorUnits: number.denominatorUnits);
3739
}),
38-
39-
_ceil, _floor, _max, _min, _percentage, _randomFunction, _round, _unit, //
40-
_compatible.withName("comparable"),
41-
_isUnitless.withName("unitless"),
40+
_ceil.withDeprecationWarning('math'),
41+
_floor.withDeprecationWarning('math'),
42+
_max.withDeprecationWarning('math'),
43+
_min.withDeprecationWarning('math'),
44+
_percentage.withDeprecationWarning('math'),
45+
_randomFunction.withDeprecationWarning('math'),
46+
_round.withDeprecationWarning('math'),
47+
_unit.withDeprecationWarning('math'),
48+
_compatible.withDeprecationWarning('math').withName("comparable"),
49+
_isUnitless.withDeprecationWarning('math').withName("unitless"),
4250
]);
4351

4452
/// The Sass math module.

‎lib/src/functions/meta.dart

+14-8
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,12 @@ final _features = {
2222
"custom-property"
2323
};
2424

25-
/// The global definitions of Sass introspection functions.
26-
final global = UnmodifiableListView([
25+
/// Sass introspection functions that exist as both global functions and in the
26+
/// `sass:meta` module that do not require access to context that's only
27+
/// available at runtime.
28+
///
29+
/// Additional functions are defined in the evaluator.
30+
final _shared = UnmodifiableListView([
2731
// This is only a partial list of meta functions. The rest are defined in the
2832
// evaluator, because they need access to context that's only available at
2933
// runtime.
@@ -35,10 +39,8 @@ final global = UnmodifiableListView([
3539
var feature = arguments[0].assertString("feature");
3640
return SassBoolean(_features.contains(feature.text));
3741
}),
38-
3942
_function("inspect", r"$value",
4043
(arguments) => SassString(arguments.first.toString(), quotes: false)),
41-
4244
_function(
4345
"type-of",
4446
r"$value",
@@ -58,7 +60,6 @@ final global = UnmodifiableListView([
5860
_ => throw "[BUG] Unknown value type ${arguments[0]}"
5961
},
6062
quotes: false)),
61-
6263
_function("keywords", r"$args", (arguments) {
6364
if (arguments[0] case SassArgumentList(:var keywords)) {
6465
return SassMap({
@@ -71,9 +72,14 @@ final global = UnmodifiableListView([
7172
})
7273
]);
7374

74-
/// The definitions of Sass introspection functions that are only available from
75-
/// the `sass:meta` module, not as global functions.
76-
final local = UnmodifiableListView([
75+
/// The global definitions of Sass introspection functions.
76+
final global = UnmodifiableListView(
77+
[for (var function in _shared) function.withDeprecationWarning('meta')]);
78+
79+
/// The versions of Sass introspection functions defined in the `sass:meta`
80+
/// module.
81+
final moduleFunctions = UnmodifiableListView([
82+
..._shared,
7783
_function("calc-name", r"$calc", (arguments) {
7884
var calculation = arguments[0].assertCalculation("calc");
7985
return SassString(calculation.name);

‎lib/src/functions/selector.dart

+8-8
Original file line numberDiff line numberDiff line change
@@ -16,14 +16,14 @@ import '../value.dart';
1616

1717
/// The global definitions of Sass selector functions.
1818
final global = UnmodifiableListView([
19-
_isSuperselector,
20-
_simpleSelectors,
21-
_parse.withName("selector-parse"),
22-
_nest.withName("selector-nest"),
23-
_append.withName("selector-append"),
24-
_extend.withName("selector-extend"),
25-
_replace.withName("selector-replace"),
26-
_unify.withName("selector-unify")
19+
_isSuperselector.withDeprecationWarning('selector'),
20+
_simpleSelectors.withDeprecationWarning('selector'),
21+
_parse.withDeprecationWarning('selector').withName("selector-parse"),
22+
_nest.withDeprecationWarning('selector').withName("selector-nest"),
23+
_append.withDeprecationWarning('selector').withName("selector-append"),
24+
_extend.withDeprecationWarning('selector').withName("selector-extend"),
25+
_replace.withDeprecationWarning('selector').withName("selector-replace"),
26+
_unify.withDeprecationWarning('selector').withName("selector-unify")
2727
]);
2828

2929
/// The Sass selector module.

‎lib/src/functions/string.dart

+9-5
Original file line numberDiff line numberDiff line change
@@ -22,11 +22,15 @@ var _previousUniqueId = _random.nextInt(math.pow(36, 6) as int);
2222

2323
/// The global definitions of Sass string functions.
2424
final global = UnmodifiableListView([
25-
_unquote, _quote, _toUpperCase, _toLowerCase, _uniqueId, //
26-
_length.withName("str-length"),
27-
_insert.withName("str-insert"),
28-
_index.withName("str-index"),
29-
_slice.withName("str-slice")
25+
_unquote.withDeprecationWarning('string'),
26+
_quote.withDeprecationWarning('string'),
27+
_toUpperCase.withDeprecationWarning('string'),
28+
_toLowerCase.withDeprecationWarning('string'),
29+
_uniqueId.withDeprecationWarning('string'),
30+
_length.withDeprecationWarning('string').withName("str-length"),
31+
_insert.withDeprecationWarning('string').withName("str-insert"),
32+
_index.withDeprecationWarning('string').withName("str-index"),
33+
_slice.withDeprecationWarning('string').withName("str-slice")
3034
]);
3135

3236
/// The Sass string module.

‎lib/src/visitor/async_evaluate.dart

+9-2
Original file line numberDiff line numberDiff line change
@@ -575,14 +575,21 @@ final class _EvaluateVisitor
575575
];
576576

577577
var metaModule = BuiltInModule("meta",
578-
functions: [...meta.global, ...meta.local, ...metaFunctions],
578+
functions: [...meta.moduleFunctions, ...metaFunctions],
579579
mixins: metaMixins);
580580

581581
for (var module in [...coreModules, metaModule]) {
582582
_builtInModules[module.url] = module;
583583
}
584584

585-
functions = [...?functions, ...globalFunctions, ...metaFunctions];
585+
functions = [
586+
...?functions,
587+
...globalFunctions,
588+
...[
589+
for (var function in metaFunctions)
590+
function.withDeprecationWarning('meta')
591+
]
592+
];
586593
for (var function in functions) {
587594
_builtInFunctions[function.name.replaceAll("_", "-")] = function;
588595
}

‎lib/src/visitor/evaluate.dart

+10-3
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
// DO NOT EDIT. This file was generated from async_evaluate.dart.
66
// See tool/grind/synchronize.dart for details.
77
//
8-
// Checksum: 2ab69d23a3b34cb54ddd74e2e854614dda582174
8+
// Checksum: 548c4265a8e0aecca7a24fd52561ef17f29f34d2
99
//
1010
// ignore_for_file: unused_import
1111

@@ -577,14 +577,21 @@ final class _EvaluateVisitor
577577
];
578578

579579
var metaModule = BuiltInModule("meta",
580-
functions: [...meta.global, ...meta.local, ...metaFunctions],
580+
functions: [...meta.moduleFunctions, ...metaFunctions],
581581
mixins: metaMixins);
582582

583583
for (var module in [...coreModules, metaModule]) {
584584
_builtInModules[module.url] = module;
585585
}
586586

587-
functions = [...?functions, ...globalFunctions, ...metaFunctions];
587+
functions = [
588+
...?functions,
589+
...globalFunctions,
590+
...[
591+
for (var function in metaFunctions)
592+
function.withDeprecationWarning('meta')
593+
]
594+
];
588595
for (var function in functions) {
589596
_builtInFunctions[function.name.replaceAll("_", "-")] = function;
590597
}

‎pkg/sass_api/CHANGELOG.md

+5-3
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
1-
## 11.0.0
2-
3-
* Remove the `CallableDeclaration()` constructor.
1+
## 11.1.0
42

53
* Loud comments in the Sass syntax no longer automatically inject ` */` to the
64
end when parsed.
75

6+
## 11.0.0
7+
8+
* Remove the `CallableDeclaration()` constructor.
9+
810
## 10.4.8
911

1012
* No user-visible changes.

‎pkg/sass_api/pubspec.yaml

+2-2
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,15 @@ name: sass_api
22
# Note: Every time we add a new Sass AST node, we need to bump the *major*
33
# version because it's a breaking change for anyone who's implementing the
44
# visitor interface(s).
5-
version: 11.0.0
5+
version: 11.1.0
66
description: Additional APIs for Dart Sass.
77
homepage: https://github.com/sass/dart-sass
88

99
environment:
1010
sdk: ">=3.0.0 <4.0.0"
1111

1212
dependencies:
13-
sass: 1.78.0
13+
sass: 1.79.0
1414

1515
dev_dependencies:
1616
dartdoc: ^8.0.14

‎pubspec.yaml

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
name: sass
2-
version: 1.78.0
2+
version: 1.79.0-dev
33
description: A Sass implementation in Dart.
44
homepage: https://github.com/sass/dart-sass
55

0 commit comments

Comments
 (0)
Please sign in to comment.