From e5418bd64758d1d0444e9158005f00ca7d2bc6ee Mon Sep 17 00:00:00 2001 From: Steven Allen Date: Fri, 10 May 2024 12:13:15 -0700 Subject: [PATCH] chore: modernize doctests (#282) We no longer need wrapping "main" blocks. --- src/dir/mod.rs | 71 +++-------- src/file/mod.rs | 139 ++++------------------ src/lib.rs | 310 ++++++++++++++---------------------------------- src/spooled.rs | 12 +- 4 files changed, 129 insertions(+), 403 deletions(-) diff --git a/src/dir/mod.rs b/src/dir/mod.rs index db70dd52e..ba1b0db16 100644 --- a/src/dir/mod.rs +++ b/src/dir/mod.rs @@ -37,14 +37,8 @@ use crate::Builder; /// ``` /// use tempfile::tempdir; /// use std::fs::File; -/// use std::io::{self, Write}; -/// -/// # fn main() { -/// # if let Err(_) = run() { -/// # ::std::process::exit(1); -/// # } -/// # } -/// # fn run() -> Result<(), io::Error> { +/// use std::io::Write; +/// /// // Create a directory inside of `std::env::temp_dir()` /// let tmp_dir = tempdir()?; /// @@ -56,8 +50,7 @@ use crate::Builder; /// // `tmp_file` will be deleted here. /// drop(tmp_file); /// tmp_dir.close()?; -/// # Ok(()) -/// # } +/// # Ok::<(), std::io::Error>(()) /// ``` /// /// [`TempDir`]: struct.TempDir.html @@ -86,14 +79,8 @@ pub fn tempdir() -> io::Result { /// ``` /// use tempfile::tempdir_in; /// use std::fs::File; -/// use std::io::{self, Write}; -/// -/// # fn main() { -/// # if let Err(_) = run() { -/// # ::std::process::exit(1); -/// # } -/// # } -/// # fn run() -> Result<(), io::Error> { +/// use std::io::Write; +/// /// // Create a directory inside of the current directory. /// let tmp_dir = tempdir_in(".")?; /// @@ -105,8 +92,7 @@ pub fn tempdir() -> io::Result { /// // `tmp_file` will be deleted here. /// drop(tmp_file); /// tmp_dir.close()?; -/// # Ok(()) -/// # } +/// # Ok::<(), std::io::Error>(()) /// ``` /// /// [`TempDir`]: struct.TempDir.html @@ -158,12 +144,9 @@ pub fn tempdir_in>(dir: P) -> io::Result { /// use std::io::Write; /// use tempfile::TempDir; /// -/// # use std::io; -/// # fn run() -> Result<(), io::Error> { /// // Create a directory inside of `std::env::temp_dir()` /// let tmp_dir = TempDir::new()?; -/// # Ok(()) -/// # } +/// # Ok::<(), std::io::Error>(()) /// ``` /// /// Create a temporary directory with a prefix in its name: @@ -173,13 +156,10 @@ pub fn tempdir_in>(dir: P) -> io::Result { /// use std::io::Write; /// use tempfile::Builder; /// -/// # use std::io; -/// # fn run() -> Result<(), io::Error> { /// // Create a directory inside of `std::env::temp_dir()`, /// // whose name will begin with 'example'. /// let tmp_dir = Builder::new().prefix("example").tempdir()?; -/// # Ok(()) -/// # } +/// # Ok::<(), std::io::Error>(()) /// ``` /// /// [`File`]: http://doc.rust-lang.org/std/fs/struct.File.html @@ -216,8 +196,6 @@ impl TempDir { /// use std::io::Write; /// use tempfile::TempDir; /// - /// # use std::io; - /// # fn run() -> Result<(), io::Error> { /// // Create a directory inside of `std::env::temp_dir()` /// let tmp_dir = TempDir::new()?; /// @@ -227,8 +205,7 @@ impl TempDir { /// /// // `tmp_dir` goes out of scope, the directory as well as /// // `tmp_file` will be deleted here. - /// # Ok(()) - /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` /// /// [`Builder`]: struct.Builder.html @@ -251,15 +228,12 @@ impl TempDir { /// use std::io::Write; /// use tempfile::TempDir; /// - /// # use std::io; - /// # fn run() -> Result<(), io::Error> { /// // Create a directory inside of the current directory /// let tmp_dir = TempDir::new_in(".")?; /// let file_path = tmp_dir.path().join("my-temporary-note.txt"); /// let mut tmp_file = File::create(file_path)?; /// writeln!(tmp_file, "Brian was here. Briefly.")?; - /// # Ok(()) - /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` pub fn new_in>(dir: P) -> io::Result { Builder::new().tempdir_in(dir) @@ -280,14 +254,11 @@ impl TempDir { /// use std::io::Write; /// use tempfile::TempDir; /// - /// # use std::io; - /// # fn run() -> Result<(), io::Error> { /// // Create a directory inside of the current directory /// let tmp_dir = TempDir::with_prefix("foo-")?; /// let tmp_name = tmp_dir.path().file_name().unwrap().to_str().unwrap(); /// assert!(tmp_name.starts_with("foo-")); - /// # Ok(()) - /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` pub fn with_prefix>(prefix: S) -> io::Result { Builder::new().prefix(&prefix).tempdir() @@ -308,14 +279,11 @@ impl TempDir { /// use std::io::Write; /// use tempfile::TempDir; /// - /// # use std::io; - /// # fn run() -> Result<(), io::Error> { /// // Create a directory inside of the current directory /// let tmp_dir = TempDir::with_prefix_in("foo-", ".")?; /// let tmp_name = tmp_dir.path().file_name().unwrap().to_str().unwrap(); /// assert!(tmp_name.starts_with("foo-")); - /// # Ok(()) - /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` pub fn with_prefix_in, P: AsRef>( prefix: S, @@ -333,8 +301,6 @@ impl TempDir { /// ``` /// use tempfile::TempDir; /// - /// # use std::io; - /// # fn run() -> Result<(), io::Error> { /// let tmp_path; /// /// { @@ -349,8 +315,7 @@ impl TempDir { /// /// // Temp directory should be deleted by now /// assert_eq!(tmp_path.exists(), false); - /// # Ok(()) - /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` #[must_use] pub fn path(&self) -> &path::Path { @@ -371,8 +336,6 @@ impl TempDir { /// use std::fs; /// use tempfile::TempDir; /// - /// # use std::io; - /// # fn run() -> Result<(), io::Error> { /// let tmp_dir = TempDir::new()?; /// /// // Persist the temporary directory to disk, @@ -381,8 +344,7 @@ impl TempDir { /// /// // Delete the temporary directory ourselves. /// fs::remove_dir_all(tmp_path)?; - /// # Ok(()) - /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` #[must_use] pub fn into_path(self) -> PathBuf { @@ -416,8 +378,6 @@ impl TempDir { /// use std::io::Write; /// use tempfile::TempDir; /// - /// # use std::io; - /// # fn run() -> Result<(), io::Error> { /// // Create a directory inside of `std::env::temp_dir()`. /// let tmp_dir = TempDir::new()?; /// let file_path = tmp_dir.path().join("my-temporary-note.txt"); @@ -431,8 +391,7 @@ impl TempDir { /// // succeeded. /// drop(tmp_file); /// tmp_dir.close()?; - /// # Ok(()) - /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` pub fn close(mut self) -> io::Result<()> { let result = remove_dir_all(self.path()).with_err_path(|| self.path()); diff --git a/src/file/mod.rs b/src/file/mod.rs index f6950f383..2aad4cd9b 100644 --- a/src/file/mod.rs +++ b/src/file/mod.rs @@ -40,20 +40,13 @@ mod imp; /// /// ``` /// use tempfile::tempfile; -/// use std::io::{self, Write}; +/// use std::io::Write; /// -/// # fn main() { -/// # if let Err(_) = run() { -/// # ::std::process::exit(1); -/// # } -/// # } -/// # fn run() -> Result<(), io::Error> { /// // Create a file inside of `std::env::temp_dir()`. /// let mut file = tempfile()?; /// /// writeln!(file, "Brian was here. Briefly.")?; -/// # Ok(()) -/// # } +/// # Ok::<(), std::io::Error>(()) /// ``` /// /// [`std::env::temp_dir()`]: https://doc.rust-lang.org/std/env/fn.temp_dir.html @@ -81,20 +74,13 @@ pub fn tempfile() -> io::Result { /// /// ``` /// use tempfile::tempfile_in; -/// use std::io::{self, Write}; +/// use std::io::Write; /// -/// # fn main() { -/// # if let Err(_) = run() { -/// # ::std::process::exit(1); -/// # } -/// # } -/// # fn run() -> Result<(), io::Error> { /// // Create a file inside of the current working directory /// let mut file = tempfile_in("./")?; /// /// writeln!(file, "Brian was here. Briefly.")?; -/// # Ok(()) -/// # } +/// # Ok::<(), std::io::Error>(()) /// ``` /// /// [`std::env::temp_dir()`]: https://doc.rust-lang.org/std/env/fn.temp_dir.html @@ -159,15 +145,8 @@ impl TempPath { /// # Examples /// /// ```no_run - /// # use std::io; /// use tempfile::NamedTempFile; /// - /// # fn main() { - /// # if let Err(_) = run() { - /// # ::std::process::exit(1); - /// # } - /// # } - /// # fn run() -> Result<(), io::Error> { /// let file = NamedTempFile::new()?; /// /// // Close the file, but keep the path to it around. @@ -178,8 +157,7 @@ impl TempPath { /// // file will still be deleted when `file` goes out of scope, but we /// // won't know whether deleting the file succeeded. /// path.close()?; - /// # Ok(()) - /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` pub fn close(mut self) -> io::Result<()> { let result = fs::remove_file(&self.path).with_err_path(|| &*self.path); @@ -212,22 +190,15 @@ impl TempPath { /// # Examples /// /// ```no_run - /// # use std::io::{self, Write}; + /// use std::io::Write; /// use tempfile::NamedTempFile; /// - /// # fn main() { - /// # if let Err(_) = run() { - /// # ::std::process::exit(1); - /// # } - /// # } - /// # fn run() -> Result<(), io::Error> { /// let mut file = NamedTempFile::new()?; /// writeln!(file, "Brian was here. Briefly.")?; /// /// let path = file.into_temp_path(); /// path.persist("./saved_file.txt")?; - /// # Ok(()) - /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` /// /// [`PathPersistError`]: struct.PathPersistError.html @@ -271,22 +242,15 @@ impl TempPath { /// # Examples /// /// ```no_run - /// # use std::io::{self, Write}; /// use tempfile::NamedTempFile; + /// use std::io::Write; /// - /// # fn main() { - /// # if let Err(_) = run() { - /// # ::std::process::exit(1); - /// # } - /// # } - /// # fn run() -> Result<(), io::Error> { /// let mut file = NamedTempFile::new()?; /// writeln!(file, "Brian was here. Briefly.")?; /// /// let path = file.into_temp_path(); /// path.persist_noclobber("./saved_file.txt")?; - /// # Ok(()) - /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` /// /// [`PathPersistError`]: struct.PathPersistError.html @@ -322,22 +286,15 @@ impl TempPath { /// # Examples /// /// ```no_run - /// # use std::io::{self, Write}; + /// use std::io::Write; /// use tempfile::NamedTempFile; /// - /// # fn main() { - /// # if let Err(_) = run() { - /// # ::std::process::exit(1); - /// # } - /// # } - /// # fn run() -> Result<(), io::Error> { /// let mut file = NamedTempFile::new()?; /// writeln!(file, "Brian was here. Briefly.")?; /// /// let path = file.into_temp_path(); /// let path = path.keep()?; - /// # Ok(()) - /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` /// /// [`PathPersistError`]: struct.PathPersistError.html @@ -585,20 +542,13 @@ impl NamedTempFile { /// Create a named temporary file and write some data to it: /// /// ```no_run - /// # use std::io::{self, Write}; + /// use std::io::Write; /// use tempfile::NamedTempFile; /// - /// # fn main() { - /// # if let Err(_) = run() { - /// # ::std::process::exit(1); - /// # } - /// # } - /// # fn run() -> Result<(), ::std::io::Error> { /// let mut file = NamedTempFile::new()?; /// /// writeln!(file, "Brian was here. Briefly.")?; - /// # Ok(()) - /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` /// /// [`Builder`]: struct.Builder.html @@ -661,20 +611,12 @@ impl NamedTempFile { /// # Examples /// /// ```no_run - /// # use std::io::{self, Write}; /// use tempfile::NamedTempFile; /// - /// # fn main() { - /// # if let Err(_) = run() { - /// # ::std::process::exit(1); - /// # } - /// # } - /// # fn run() -> Result<(), ::std::io::Error> { /// let file = NamedTempFile::new()?; /// /// println!("{:?}", file.path()); - /// # Ok(()) - /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` #[inline] pub fn path(&self) -> &Path { @@ -692,15 +634,8 @@ impl NamedTempFile { /// # Examples /// /// ```no_run - /// # use std::io; /// use tempfile::NamedTempFile; /// - /// # fn main() { - /// # if let Err(_) = run() { - /// # ::std::process::exit(1); - /// # } - /// # } - /// # fn run() -> Result<(), io::Error> { /// let file = NamedTempFile::new()?; /// /// // By closing the `NamedTempFile` explicitly, we can check that it has @@ -709,8 +644,7 @@ impl NamedTempFile { /// // of scope, but we won't know whether deleting the file /// // succeeded. /// file.close()?; - /// # Ok(()) - /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` pub fn close(self) -> io::Result<()> { let NamedTempFile { path, .. } = self; @@ -741,21 +675,14 @@ impl NamedTempFile { /// # Examples /// /// ```no_run - /// # use std::io::{self, Write}; + /// use std::io::Write; /// use tempfile::NamedTempFile; /// - /// # fn main() { - /// # if let Err(_) = run() { - /// # ::std::process::exit(1); - /// # } - /// # } - /// # fn run() -> Result<(), io::Error> { /// let file = NamedTempFile::new()?; /// /// let mut persisted_file = file.persist("./saved_file.txt")?; /// writeln!(persisted_file, "Brian was here. Briefly.")?; - /// # Ok(()) - /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` /// /// [`PersistError`]: struct.PersistError.html @@ -796,21 +723,14 @@ impl NamedTempFile { /// # Examples /// /// ```no_run - /// # use std::io::{self, Write}; + /// use std::io::Write; /// use tempfile::NamedTempFile; /// - /// # fn main() { - /// # if let Err(_) = run() { - /// # ::std::process::exit(1); - /// # } - /// # } - /// # fn run() -> Result<(), io::Error> { /// let file = NamedTempFile::new()?; /// /// let mut persisted_file = file.persist_noclobber("./saved_file.txt")?; /// writeln!(persisted_file, "Brian was here. Briefly.")?; - /// # Ok(()) - /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` pub fn persist_noclobber>(self, new_path: P) -> Result> { let NamedTempFile { path, file } = self; @@ -838,21 +758,14 @@ impl NamedTempFile { /// # Examples /// /// ```no_run - /// # use std::io::{self, Write}; + /// use std::io::Write; /// use tempfile::NamedTempFile; /// - /// # fn main() { - /// # if let Err(_) = run() { - /// # ::std::process::exit(1); - /// # } - /// # } - /// # fn run() -> Result<(), io::Error> { /// let mut file = NamedTempFile::new()?; /// writeln!(file, "Brian was here. Briefly.")?; /// /// let (file, path) = file.keep()?; - /// # Ok(()) - /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` /// /// [`PathPersistError`]: struct.PathPersistError.html @@ -930,20 +843,12 @@ impl NamedTempFile { /// # Examples /// /// ```no_run - /// # use std::io; /// use tempfile::NamedTempFile; /// - /// # fn main() { - /// # if let Err(_) = run() { - /// # ::std::process::exit(1); - /// # } - /// # } - /// # fn run() -> Result<(), io::Error> { /// let file = NamedTempFile::new()?; /// /// let another_handle = file.reopen()?; - /// # Ok(()) - /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` pub fn reopen(&self) -> io::Result { imp::reopen(self.as_file(), NamedTempFile::path(self)) diff --git a/src/lib.rs b/src/lib.rs index 5424ffd11..4e78037bd 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -37,15 +37,9 @@ //! generic over `AsRef`. Consider the following example: //! //! ```no_run -//! # use tempfile::tempdir; -//! # use std::io; -//! # use std::process::Command; -//! # fn main() { -//! # if let Err(_) = run() { -//! # ::std::process::exit(1); -//! # } -//! # } -//! # fn run() -> Result<(), io::Error> { +//! use tempfile::tempdir; +//! use std::process::Command; +//! //! // Create a directory inside of `std::env::temp_dir()`. //! let temp_dir = tempdir()?; //! @@ -54,8 +48,7 @@ //! let exit_status = Command::new("touch").arg("tmp").current_dir(&temp_dir).status()?; //! assert!(exit_status.success()); //! -//! # Ok(()) -//! # } +//! # Ok::<(), std::io::Error>(()) //! ``` //! //! This works because a reference to `temp_dir` is passed to `current_dir`, resulting in the @@ -72,34 +65,21 @@ //! //! ``` //! use tempfile::tempfile; -//! use std::io::{self, Write}; -//! -//! # fn main() { -//! # if let Err(_) = run() { -//! # ::std::process::exit(1); -//! # } -//! # } -//! # fn run() -> Result<(), io::Error> { +//! use std::io::Write; +//! //! // Create a file inside of `std::env::temp_dir()`. //! let mut file = tempfile()?; //! //! writeln!(file, "Brian was here. Briefly.")?; -//! # Ok(()) -//! # } +//! # Ok::<(), std::io::Error>(()) //! ``` //! //! Create a named temporary file and open an independent file handle: //! //! ``` //! use tempfile::NamedTempFile; -//! use std::io::{self, Write, Read}; -//! -//! # fn main() { -//! # if let Err(_) = run() { -//! # ::std::process::exit(1); -//! # } -//! # } -//! # fn run() -> Result<(), io::Error> { +//! use std::io::{Write, Read}; +//! //! let text = "Brian was here. Briefly."; //! //! // Create a file inside of `std::env::temp_dir()`. @@ -115,8 +95,7 @@ //! let mut buf = String::new(); //! file2.read_to_string(&mut buf)?; //! assert_eq!(buf, text); -//! # Ok(()) -//! # } +//! # Ok::<(), std::io::Error>(()) //! ``` //! //! Create a temporary directory and add a file to it: @@ -124,14 +103,8 @@ //! ``` //! use tempfile::tempdir; //! use std::fs::File; -//! use std::io::{self, Write}; -//! -//! # fn main() { -//! # if let Err(_) = run() { -//! # ::std::process::exit(1); -//! # } -//! # } -//! # fn run() -> Result<(), io::Error> { +//! use std::io::Write; +//! //! // Create a directory inside of `std::env::temp_dir()`. //! let dir = tempdir()?; //! @@ -146,8 +119,7 @@ //! // succeeded. //! drop(file); //! dir.close()?; -//! # Ok(()) -//! # } +//! # Ok::<(), std::io::Error>(()) //! ``` //! //! [`tempfile()`]: fn.tempfile.html @@ -220,14 +192,7 @@ impl<'a, 'b> Builder<'a, 'b> { /// Create a named temporary file and write some data into it: /// /// ``` - /// # use std::io; - /// # use std::ffi::OsStr; - /// # fn main() { - /// # if let Err(_) = run() { - /// # ::std::process::exit(1); - /// # } - /// # } - /// # fn run() -> Result<(), io::Error> { + /// use std::ffi::OsStr; /// use tempfile::Builder; /// /// let named_tempfile = Builder::new() @@ -245,22 +210,15 @@ impl<'a, 'b> Builder<'a, 'b> { /// assert!(name.ends_with(".txt")); /// assert_eq!(name.len(), "my-temporary-note.txt".len() + 5); /// } - /// # Ok(()) - /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` /// /// Create a temporary directory and add a file to it: /// /// ``` - /// # use std::io::{self, Write}; - /// # use std::fs::File; - /// # use std::ffi::OsStr; - /// # fn main() { - /// # if let Err(_) = run() { - /// # ::std::process::exit(1); - /// # } - /// # } - /// # fn run() -> Result<(), io::Error> { + /// use std::io::Write; + /// use std::fs::File; + /// use std::ffi::OsStr; /// use tempfile::Builder; /// /// let dir = Builder::new() @@ -279,16 +237,18 @@ impl<'a, 'b> Builder<'a, 'b> { /// // succeeded. /// drop(file); /// dir.close()?; - /// # Ok(()) - /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` /// /// Create a temporary directory with a chosen prefix under a chosen folder: /// - /// ```ignore + /// ```no_run + /// use tempfile::Builder; + /// /// let dir = Builder::new() /// .prefix("my-temporary-dir") /// .tempdir_in("folder-with-tempdirs")?; + /// # Ok::<(), std::io::Error>(()) /// ``` #[must_use] pub fn new() -> Self { @@ -303,19 +263,12 @@ impl<'a, 'b> Builder<'a, 'b> { /// # Examples /// /// ``` - /// # use std::io; - /// # fn main() { - /// # if let Err(_) = run() { - /// # ::std::process::exit(1); - /// # } - /// # } - /// # fn run() -> Result<(), io::Error> { - /// # use tempfile::Builder; + /// use tempfile::Builder; + /// /// let named_tempfile = Builder::new() /// .prefix("my-temporary-note") /// .tempfile()?; - /// # Ok(()) - /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` pub fn prefix + ?Sized>(&mut self, prefix: &'a S) -> &mut Self { self.prefix = prefix.as_ref(); @@ -330,19 +283,12 @@ impl<'a, 'b> Builder<'a, 'b> { /// # Examples /// /// ``` - /// # use std::io; - /// # fn main() { - /// # if let Err(_) = run() { - /// # ::std::process::exit(1); - /// # } - /// # } - /// # fn run() -> Result<(), io::Error> { - /// # use tempfile::Builder; + /// use tempfile::Builder; + /// /// let named_tempfile = Builder::new() /// .suffix(".txt") /// .tempfile()?; - /// # Ok(()) - /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` pub fn suffix + ?Sized>(&mut self, suffix: &'b S) -> &mut Self { self.suffix = suffix.as_ref(); @@ -356,19 +302,12 @@ impl<'a, 'b> Builder<'a, 'b> { /// # Examples /// /// ``` - /// # use std::io; - /// # fn main() { - /// # if let Err(_) = run() { - /// # ::std::process::exit(1); - /// # } - /// # } - /// # fn run() -> Result<(), io::Error> { - /// # use tempfile::Builder; + /// use tempfile::Builder; + /// /// let named_tempfile = Builder::new() /// .rand_bytes(5) /// .tempfile()?; - /// # Ok(()) - /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` pub fn rand_bytes(&mut self, rand: usize) -> &mut Self { self.random_len = rand; @@ -382,19 +321,12 @@ impl<'a, 'b> Builder<'a, 'b> { /// # Examples /// /// ``` - /// # use std::io; - /// # fn main() { - /// # if let Err(_) = run() { - /// # ::std::process::exit(1); - /// # } - /// # } - /// # fn run() -> Result<(), io::Error> { - /// # use tempfile::Builder; + /// use tempfile::Builder; + /// /// let named_tempfile = Builder::new() /// .append(true) /// .tempfile()?; - /// # Ok(()) - /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` pub fn append(&mut self, append: bool) -> &mut Self { self.append = append; @@ -429,55 +361,41 @@ impl<'a, 'b> Builder<'a, 'b> { /// Create a named temporary file that is world-readable. /// /// ``` - /// # use std::io; - /// # fn main() { - /// # if let Err(_) = run() { - /// # ::std::process::exit(1); - /// # } - /// # } - /// # fn run() -> Result<(), io::Error> { - /// # use tempfile::Builder; - /// #[cfg(unix)] - /// { - /// use std::os::unix::fs::PermissionsExt; - /// let all_read_write = std::fs::Permissions::from_mode(0o666); - /// let tempfile = Builder::new().permissions(all_read_write).tempfile()?; - /// let actual_permissions = tempfile.path().metadata()?.permissions(); - /// assert_ne!( - /// actual_permissions.mode() & !0o170000, - /// 0o600, - /// "we get broader permissions than the default despite umask" - /// ); - /// } - /// # Ok(()) + /// # #[cfg(unix)] + /// # { + /// use tempfile::Builder; + /// use std::os::unix::fs::PermissionsExt; + /// + /// let all_read_write = std::fs::Permissions::from_mode(0o666); + /// let tempfile = Builder::new().permissions(all_read_write).tempfile()?; + /// let actual_permissions = tempfile.path().metadata()?.permissions(); + /// assert_ne!( + /// actual_permissions.mode() & !0o170000, + /// 0o600, + /// "we get broader permissions than the default despite umask" + /// ); /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` /// /// Create a named temporary directory that is restricted to the owner. /// /// ``` - /// # use std::io; - /// # fn main() { - /// # if let Err(_) = run() { - /// # ::std::process::exit(1); - /// # } - /// # } - /// # fn run() -> Result<(), io::Error> { - /// # use tempfile::Builder; - /// #[cfg(unix)] - /// { - /// use std::os::unix::fs::PermissionsExt; - /// let owner_rwx = std::fs::Permissions::from_mode(0o700); - /// let tempdir = Builder::new().permissions(owner_rwx).tempdir()?; - /// let actual_permissions = tempdir.path().metadata()?.permissions(); - /// assert_eq!( - /// actual_permissions.mode() & !0o170000, - /// 0o700, - /// "we get the narrow permissions we asked for" - /// ); - /// } - /// # Ok(()) + /// # #[cfg(unix)] + /// # { + /// use tempfile::Builder; + /// use std::os::unix::fs::PermissionsExt; + /// + /// let owner_rwx = std::fs::Permissions::from_mode(0o700); + /// let tempdir = Builder::new().permissions(owner_rwx).tempdir()?; + /// let actual_permissions = tempdir.path().metadata()?.permissions(); + /// assert_eq!( + /// actual_permissions.mode() & !0o170000, + /// 0o700, + /// "we get the narrow permissions we asked for" + /// ); /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` pub fn permissions(&mut self, permissions: std::fs::Permissions) -> &mut Self { self.permissions = Some(permissions); @@ -501,17 +419,10 @@ impl<'a, 'b> Builder<'a, 'b> { /// # Examples /// /// ``` - /// # use std::io; - /// # fn main() { - /// # if let Err(_) = run() { - /// # ::std::process::exit(1); - /// # } - /// # } - /// # fn run() -> Result<(), io::Error> { - /// # use tempfile::Builder; + /// use tempfile::Builder; + /// /// let tempfile = Builder::new().tempfile()?; - /// # Ok(()) - /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` /// /// [security]: struct.NamedTempFile.html#security @@ -537,17 +448,10 @@ impl<'a, 'b> Builder<'a, 'b> { /// # Examples /// /// ``` - /// # use std::io; - /// # fn main() { - /// # if let Err(_) = run() { - /// # ::std::process::exit(1); - /// # } - /// # } - /// # fn run() -> Result<(), io::Error> { - /// # use tempfile::Builder; + /// use tempfile::Builder; + /// /// let tempfile = Builder::new().tempfile_in("./")?; - /// # Ok(()) - /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` /// /// [security]: struct.NamedTempFile.html#security @@ -581,15 +485,10 @@ impl<'a, 'b> Builder<'a, 'b> { /// # Examples /// /// ``` - /// use std::fs::File; - /// use std::io::Write; /// use tempfile::Builder; /// - /// # use std::io; - /// # fn run() -> Result<(), io::Error> { /// let tmp_dir = Builder::new().tempdir()?; - /// # Ok(()) - /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` /// /// [resource-leaking]: struct.TempDir.html#resource-leaking @@ -612,15 +511,10 @@ impl<'a, 'b> Builder<'a, 'b> { /// # Examples /// /// ``` - /// use std::fs::{self, File}; - /// use std::io::Write; /// use tempfile::Builder; /// - /// # use std::io; - /// # fn run() -> Result<(), io::Error> { /// let tmp_dir = Builder::new().tempdir_in("./")?; - /// # Ok(()) - /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` /// /// [resource-leaking]: struct.TempDir.html#resource-leaking @@ -670,19 +564,13 @@ impl<'a, 'b> Builder<'a, 'b> { /// For example, the following is **not** secure: /// /// ``` - /// # use std::io; - /// # use std::fs::File; - /// # fn main() { - /// # if let Err(_) = run() { - /// # ::std::process::exit(1); - /// # } - /// # } - /// # fn run() -> Result<(), io::Error> { - /// # use tempfile::Builder; + /// use std::fs::File; + /// use tempfile::Builder; + /// /// // This is NOT secure! /// let tempfile = Builder::new().make(|path| { /// if path.is_file() { - /// return Err(io::ErrorKind::AlreadyExists.into()); + /// return Err(std::io::ErrorKind::AlreadyExists.into()); /// } /// /// // Between the check above and the usage below, an attacker could @@ -691,25 +579,19 @@ impl<'a, 'b> Builder<'a, 'b> { /// /// File::create(path) /// })?; - /// # Ok(()) - /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` + /// /// Note that simply using [`std::fs::File::create`] alone is not correct /// because it does not fail if the file already exists: + /// /// ``` - /// # use std::io; - /// # use std::fs::File; - /// # fn main() { - /// # if let Err(_) = run() { - /// # ::std::process::exit(1); - /// # } - /// # } - /// # fn run() -> Result<(), io::Error> { - /// # use tempfile::Builder; + /// use tempfile::Builder; + /// use std::fs::File; + /// /// // This could overwrite an existing file! /// let tempfile = Builder::new().make(|path| File::create(path))?; - /// # Ok(()) - /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` /// For creating regular temporary files, use [`Builder::tempfile`] instead /// to avoid these problems. This function is meant to enable more exotic @@ -727,20 +609,14 @@ impl<'a, 'b> Builder<'a, 'b> { /// /// # Examples /// ``` - /// # use std::io; - /// # fn main() { - /// # if let Err(_) = run() { - /// # ::std::process::exit(1); - /// # } - /// # } - /// # fn run() -> Result<(), io::Error> { - /// # use tempfile::Builder; /// # #[cfg(unix)] + /// # { /// use std::os::unix::net::UnixListener; - /// # #[cfg(unix)] + /// use tempfile::Builder; + /// /// let tempsock = Builder::new().make(|path| UnixListener::bind(path))?; - /// # Ok(()) /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` /// /// [TOCTOU]: https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use @@ -760,20 +636,14 @@ impl<'a, 'b> Builder<'a, 'b> { /// /// # Examples /// ``` - /// # use std::io; - /// # fn main() { - /// # if let Err(_) = run() { - /// # ::std::process::exit(1); - /// # } - /// # } - /// # fn run() -> Result<(), io::Error> { - /// # use tempfile::Builder; /// # #[cfg(unix)] + /// # { + /// use tempfile::Builder; /// use std::os::unix::net::UnixListener; - /// # #[cfg(unix)] + /// /// let tempsock = Builder::new().make_in("./", |path| UnixListener::bind(path))?; - /// # Ok(()) /// # } + /// # Ok::<(), std::io::Error>(()) /// ``` pub fn make_in(&self, dir: P, mut f: F) -> io::Result> where diff --git a/src/spooled.rs b/src/spooled.rs index 9b2e7e7b2..9c9846ce1 100644 --- a/src/spooled.rs +++ b/src/spooled.rs @@ -36,14 +36,8 @@ pub struct SpooledTempFile { /// /// ``` /// use tempfile::spooled_tempfile; -/// use std::io::{self, Write}; +/// use std::io::Write; /// -/// # fn main() { -/// # if let Err(_) = run() { -/// # ::std::process::exit(1); -/// # } -/// # } -/// # fn run() -> Result<(), io::Error> { /// let mut file = spooled_tempfile(15); /// /// writeln!(file, "short line")?; @@ -54,9 +48,7 @@ pub struct SpooledTempFile { /// // and the in-memory buffer will be dropped /// writeln!(file, "marvin gardens")?; /// assert!(file.is_rolled()); -/// -/// # Ok(()) -/// # } +/// # Ok::<(), std::io::Error>(()) /// ``` #[inline] pub fn spooled_tempfile(max_size: usize) -> SpooledTempFile {