From d9d877a27daf47e7e220fab6ebcb362b97c91a7b Mon Sep 17 00:00:00 2001
From: Marya <111139605+MaryaBelanger@users.noreply.github.com>
Date: Tue, 21 Jan 2025 15:16:06 -0800
Subject: [PATCH] Add wildcard variables (#6295)

Fixes #5833
---
 src/content/language/libraries.md |  5 +++
 src/content/language/variables.md | 66 +++++++++++++++++++++++++++++++
 2 files changed, 71 insertions(+)

diff --git a/src/content/language/libraries.md b/src/content/language/libraries.md
index 897dcd415a..84b966f37e 100644
--- a/src/content/language/libraries.md
+++ b/src/content/language/libraries.md
@@ -75,6 +75,11 @@ Element element1 = Element();
 lib2.Element element2 = lib2.Element();
 ```
 
+Import prefixes with the [wildcard][] name `_` are non-binding,
+but will provide access to the non-private extensions in that library.
+
+[wildcard]: /language/variables#wildcard-variables
+
 ### Importing only part of a library
 
 If you want to use only part of a library, you can selectively import
diff --git a/src/content/language/variables.md b/src/content/language/variables.md
index fc1979eca4..5d7d5c0ad8 100644
--- a/src/content/language/variables.md
+++ b/src/content/language/variables.md
@@ -291,6 +291,70 @@ For more information on using `const` to create constant values, see
 [Lists][], [Maps][], and [Classes][].
 
 
+## Wildcard variables
+
+:::version-note
+Wildcard variables require
+a [language version][] of at least 3.7.
+:::
+
+A wildcard variable with the name `_` declares a local variable or parameter
+that is non-binding; essentially, a placeholder.
+The initializer, if there is one, is still executed, but the value isn't accessible.
+Multiple declarations named `_` can exist in the same namespace without a collision error.
+
+Top-level declarations or members where library privacy might be affected are
+not valid uses for wildcard variables.
+Declarations local to a block scope, such as the following examples,
+can declare a wildcard:
+
+* Local variable declaration.
+  ```dart
+  main() {
+    var _ = 1;
+    int _ = 2;
+  }
+  ```
+
+* For loop variable declartaion.
+  ```dart
+  for (var _ in list) {}
+  ```
+
+* Catch clause parameters.
+  ```dart
+  try {
+    throw '!';
+  } catch (_) {
+    print('oops');
+  }
+  ```
+
+* Generic type and function type parameters.
+  ```dart
+  class T<_> {}
+  void genericFunction<_>() {}
+
+  takeGenericCallback(<_>() => true);
+  ```
+
+* Function parameters.
+  ```dart
+  Foo(_, this._, super._, void _()) {}
+
+  list.where((_) => true);
+
+  void f(void g(int _, bool _)) {}
+
+  typedef T = void Function(String _, String _);
+  ```
+
+:::tip
+Enable the lint [`unnecessary_underscores`][] to identify where a single
+non-binding wildcard variable `_` can replace the previous convention of using
+multiple binding underscores (`__`,`___`, etc.) to avoid name collisions.
+:::
+
 [Assert]: /language/error-handling#assert
 [Instance variables]: /language/classes#instance-variables
 [DON'T use const redundantly]: /effective-dart/usage#dont-use-const-redundantly
@@ -300,3 +364,5 @@ For more information on using `const` to create constant values, see
 [Lists]: /language/collections#lists
 [Maps]: /language/collections#maps
 [Classes]: /language/classes
+[language version]: /resources/language/evolution#language-versioning
+[`unnecessary_underscores`]: /tools/linter-rules/unnecessary_underscores