Merge pull request #727 from async-rs/revert-719-remove_re_export

Revert "Stabilize most stream method and remove unnecessary macros"

Author: yoshuawuyts

Cargo.toml

@@ -26,6 +26,7 @@ default = [
   "async-task",
   "crossbeam-channel",
   "crossbeam-deque",
+  "futures-timer",
   "kv-log-macro",
   "log",
   "mio",
@@ -34,14 +35,13 @@ default = [
   "pin-project-lite",
 ]
 docs = ["attributes", "unstable", "default"]
-unstable = ["std", "broadcaster"]
+unstable = ["std", "broadcaster", "futures-timer"]
 attributes = ["async-attributes"]
 std = [
   "alloc",
   "crossbeam-utils",
   "futures-core/std",
   "futures-io",
-  "futures-timer",
   "memchr",
   "once_cell",
   "pin-utils",

examples/a-chat/client.rs

@@ -1,12 +1,11 @@
 use futures::select;
 use futures::FutureExt;
-use std::io::{self, BufRead, BufReader as StdBufReader};
 
 use async_std::{
-    io::BufReader,
+    io::{stdin, BufReader},
     net::{TcpStream, ToSocketAddrs},
     prelude::*,
-    stream, task,
+    task,
 };
 
 type Result<T> = std::result::Result<T, Box<dyn std::error::Error + Send + Sync>>;
@@ -21,9 +20,8 @@ async fn try_main(addr: impl ToSocketAddrs) -> Result<()> {
     let reader = BufReader::new(reader);
     let mut lines_from_server = futures::StreamExt::fuse(reader.lines());
 
-    let stdin = StdBufReader::new(io::stdin());
-    let mut lines_from_stdin = stream::from_iter(stdin.lines());
-
+    let stdin = BufReader::new(stdin());
+    let mut lines_from_stdin = futures::StreamExt::fuse(stdin.lines());
     loop {
         select! {
             line = lines_from_server.next().fuse() => match line {

examples/print-file.rs

@@ -1,7 +1,6 @@
 //! Prints a file given as an argument to stdout.
 
 use std::env::args;
-use std::io::Write;
 
 use async_std::fs::File;
 use async_std::io;
@@ -15,7 +14,7 @@ fn main() -> io::Result<()> {
 
     task::block_on(async {
         let mut file = File::open(&path).await?;
-        let mut stdout = std::io::stdout();
+        let mut stdout = io::stdout();
         let mut buf = vec![0u8; LEN];
 
         loop {
@@ -24,12 +23,12 @@ fn main() -> io::Result<()> {
 
             // If this is the end of file, clean up and return.
             if n == 0 {
-                stdout.flush()?;
+                stdout.flush().await?;
                 return Ok(());
             }
 
             // Write the buffer into stdout.
-            stdout.write_all(&buf[..n])?;
+            stdout.write_all(&buf[..n]).await?;
         }
     })
 }

examples/stdin-echo.rs

@@ -1,27 +1,27 @@
 //! Echoes lines read on stdin to stdout.
 
 use async_std::io;
+use async_std::prelude::*;
 use async_std::task;
-use std::io::Write;
 
 fn main() -> io::Result<()> {
     task::block_on(async {
-        let stdin = std::io::stdin();
-        let mut stdout = std::io::stdout();
+        let stdin = io::stdin();
+        let mut stdout = io::stdout();
         let mut line = String::new();
 
         loop {
             // Read a line from stdin.
-            let n = stdin.read_line(&mut line)?;
+            let n = stdin.read_line(&mut line).await?;
 
             // If this is the end of stdin, return.
             if n == 0 {
                 return Ok(());
             }
 
             // Write the line to stdout.
-            stdout.write_all(line.as_bytes())?;
-            stdout.flush()?;
+            stdout.write_all(line.as_bytes()).await?;
+            stdout.flush().await?;
             line.clear();
         }
     })

examples/stdin-timeout.rs

@@ -8,11 +8,11 @@ use async_std::task;
 fn main() -> io::Result<()> {
     // This async scope times out after 5 seconds.
     task::block_on(io::timeout(Duration::from_secs(5), async {
-        let stdin = std::io::stdin();
+        let stdin = io::stdin();
 
         // Read a line from the standard input and display it.
         let mut line = String::new();
-        stdin.read_line(&mut line)?;
+        stdin.read_line(&mut line).await?;
         dbg!(line);
 
         Ok(())

src/future/into_future.rs

@@ -5,10 +5,9 @@ use std::future::Future;
 /// # Examples
 ///
 /// ```
-/// use std::pin::Pin;
-///
 /// use async_std::future::{Future, IntoFuture};
 /// use async_std::io;
+/// use async_std::pin::Pin;
 ///
 /// struct Client;
 ///

src/future/mod.rs

@@ -63,14 +63,12 @@ cfg_std! {
 
 cfg_default! {
     pub use timeout::{timeout, TimeoutError};
-
     mod timeout;
 }
 
 cfg_unstable! {
     pub use into_future::IntoFuture;
     pub(crate) use maybe_done::MaybeDone;
-
     mod into_future;
     mod maybe_done;
 }

src/io/copy.rs

@@ -32,14 +32,13 @@ use crate::utils::Context as _;
 ///
 /// # Examples
 ///
-/// ```no_run
+/// ```
 /// # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
 /// #
 /// use async_std::io;
-/// use async_std::fs::File;
 ///
 /// let mut reader: &[u8] = b"hello";
-/// let mut writer = File::open("foo.txt").await?;
+/// let mut writer = io::stdout();
 ///
 /// io::copy(&mut reader, &mut writer).await?;
 /// #
@@ -120,14 +119,13 @@ where
 ///
 /// # Examples
 ///
-/// ```no_run
+/// ```
 /// # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
 /// #
 /// use async_std::io;
-/// use async_std::fs::File;
 ///
 /// let mut reader: &[u8] = b"hello";
-/// let mut writer = File::open("foo.txt").await?;
+/// let mut writer = io::stdout();
 ///
 /// io::copy(&mut reader, &mut writer).await?;
 /// #

src/io/mod.rs

@@ -122,6 +122,56 @@
 //! # Ok(()) }) }
 //! ```
 //!
+//! ## Standard input and output
+//!
+//! A very common source of input is standard input:
+//!
+//! ```no_run
+//! use async_std::io;
+//!
+//! # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
+//! #
+//! let mut input = String::new();
+//!
+//! io::stdin().read_line(&mut input).await?;
+//!
+//! println!("You typed: {}", input.trim());
+//! #
+//! # Ok(()) }) }
+//! ```
+//!
+//! Note that you cannot use the [`?` operator] in functions that do not return
+//! a [`Result<T, E>`][`Result`]. Instead, you can call [`.unwrap()`]
+//! or `match` on the return value to catch any possible errors:
+//!
+//! ```no_run
+//! use async_std::io;
+//!
+//! # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
+//! #
+//! let mut input = String::new();
+//!
+//! io::stdin().read_line(&mut input).await.unwrap();
+//! #
+//! # Ok(()) }) }
+//! ```
+//!
+//! And a very common source of output is standard output:
+//!
+//! ```no_run
+//! use async_std::io;
+//! use async_std::io::prelude::*;
+//!
+//! # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
+//! #
+//! io::stdout().write(&[42]).await?;
+//! #
+//! # Ok(()) }) }
+//! ```
+//!
+//! Of course, using [`io::stdout`] directly is less common than something like
+//! [`println!`].
+//!
 //! ## Iterator types
 //!
 //! A large number of the structures provided by `std::io` are for various
@@ -154,14 +204,10 @@
 //!
 //! ```no_run
 //! use async_std::io;
-//! use async_std::fs::File;
 //!
 //! # fn main() -> std::io::Result<()> { async_std::task::block_on(async {
 //! #
-//! let mut reader: &[u8] = b"hello";
-//! let mut writer = File::open("foo.txt").await?;
-//!
-//! io::copy(&mut reader, &mut writer).await?;
+//! io::copy(&mut io::stdin(), &mut io::stdout()).await?;
 //! #
 //! # Ok(()) }) }
 //! ```
@@ -178,14 +224,13 @@
 //! ```
 //! #![allow(dead_code)]
 //! use async_std::io;
-//! use std::time::Duration;
 //!
 //! async fn read_input() -> io::Result<()> {
-//!     let f = io::timeout(Duration::from_secs(5), async {
-//!         Ok(())
-//!     });
+//!     let mut input = String::new();
+//!
+//!     io::stdin().read_line(&mut input).await?;
 //!
-//!     assert_eq!(f.await?, ());
+//!     println!("You typed: {}", input.trim());
 //!
 //!     Ok(())
 //! }
@@ -215,6 +260,8 @@
 //! [`BufReader`]: struct.BufReader.html
 //! [`BufWriter`]: struct.BufWriter.html
 //! [`Write::write`]: trait.Write.html#tymethod.write
+//! [`io::stdout`]: fn.stdout.html
+//! [`println!`]: ../macro.println.html
 //! [`Lines`]: struct.Lines.html
 //! [`io::Result`]: type.Result.html
 //! [`?` operator]: https://doc.rust-lang.org/stable/book/appendix-02-operators.html
@@ -258,7 +305,24 @@ cfg_std! {
 }
 
 cfg_default! {
+    // For use in the print macros.
+    #[doc(hidden)]
+    pub use stdio::{_eprint, _print};
+
+    pub use stderr::{stderr, Stderr};
+    pub use stdin::{stdin, Stdin};
+    pub use stdout::{stdout, Stdout};
     pub use timeout::timeout;
 
     mod timeout;
+    mod stderr;
+    mod stdin;
+    mod stdio;
+    mod stdout;
+}
+
+cfg_unstable_default! {
+    pub use stderr::StderrLock;
+    pub use stdin::StdinLock;
+    pub use stdout::StdoutLock;
 }