Add iter macro

This adds an `iter!` macro that can be used to create movable
generators.

This also adds a yield_expr feature so the `yield` keyword can be used
within iter! macro bodies. This was needed because several unstable
features each need `yield` expressions, so this allows us to stabilize
them separately from any individual feature.

Co-authored-by: Oli Scherer <[email protected]>
Co-authored-by: Jieyou Xu <[email protected]>
Co-authored-by: Travis Cross <[email protected]>

Author: 3 people

core/src/iter/mod.rs

@@ -420,6 +420,8 @@ pub use self::adapters::{Intersperse, IntersperseWith};
     issue = "42168"
 )]
 pub use self::range::Step;
+#[unstable(feature = "iter_macro", issue = "none", reason = "generators are unstable")]
+pub use self::sources::iter;
 #[stable(feature = "iter_empty", since = "1.2.0")]
 pub use self::sources::{Empty, empty};
 #[unstable(

core/src/iter/sources.rs

@@ -1,6 +1,7 @@
 mod empty;
 mod from_coroutine;
 mod from_fn;
+mod generator;
 mod once;
 mod once_with;
 mod repeat;
@@ -18,6 +19,8 @@ pub use self::empty::{Empty, empty};
 pub use self::from_coroutine::{FromCoroutine, from_coroutine};
 #[stable(feature = "iter_from_fn", since = "1.34.0")]
 pub use self::from_fn::{FromFn, from_fn};
+#[unstable(feature = "iter_macro", issue = "none", reason = "generators are unstable")]
+pub use self::generator::iter;
 #[stable(feature = "iter_once", since = "1.2.0")]
 pub use self::once::{Once, once};
 #[stable(feature = "iter_once_with", since = "1.43.0")]

core/src/iter/sources/generator.rs

@@ -0,0 +1,29 @@
+/// Creates a new closure that returns an iterator where each iteration steps the given
+/// generator to the next `yield` statement.
+///
+/// Similar to [`iter::from_fn`], but allows arbitrary control flow.
+///
+/// [`iter::from_fn`]: crate::iter::from_fn
+///
+/// # Examples
+///
+/// ```
+/// #![feature(iter_macro, coroutines)]
+/// # #[cfg(not(bootstrap))]
+/// # {
+///
+/// let it = std::iter::iter!{|| {
+///     yield 1;
+///     yield 2;
+///     yield 3;
+/// } }();
+/// let v: Vec<_> = it.collect();
+/// assert_eq!(v, [1, 2, 3]);
+/// # }
+/// ```
+#[unstable(feature = "iter_macro", issue = "none", reason = "generators are unstable")]
+#[allow_internal_unstable(coroutines, iter_from_coroutine)]
+#[cfg_attr(not(bootstrap), rustc_builtin_macro)]
+pub macro iter($($t:tt)*) {
+    /* compiler-builtin */
+}