Enum OutputArg

pub enum OutputArg {
    Stdout,
    Path(PathBuf),
}

An output path that can refer to either standard output or a file system path

Variants

Stdout

Refers to standard output.

This is the variant returned by OutputArg::default().

Path(PathBuf)

Refers to a file system path (stored in .0)

Implementations

impl OutputArg

pub fn from_arg<S: Into<PathBuf>>(arg: S) -> OutputArg

Construct a OutputArg from a string, usually one taken from command-line arguments. If the string equals "-" (i.e., it contains only a single hyphen/dash), OutputArg::Stdout is returned; otherwise, an OutputArg::Path is returned.

Example

use patharg::OutputArg;
use std::path::PathBuf;

let p1 = OutputArg::from_arg("-");
assert_eq!(p1, OutputArg::Stdout);

let p2 = OutputArg::from_arg("./-");
assert_eq!(p2, OutputArg::Path(PathBuf::from("./-")));

pub fn is_stdout(&self) -> bool

Returns true if the output arg is the Stdout variant of OutputArg.

Example

use patharg::OutputArg;

let p1 = OutputArg::from_arg("-");
assert!(p1.is_stdout());

let p2 = OutputArg::from_arg("file.txt");
assert!(!p2.is_stdout());

pub fn is_path(&self) -> bool

Returns true if the output arg is the Path variant of OutputArg.

Example

use patharg::OutputArg;

let p1 = OutputArg::from_arg("-");
assert!(!p1.is_path());

let p2 = OutputArg::from_arg("file.txt");
assert!(p2.is_path());

pub fn path_ref(&self) -> Option<&PathBuf>

Retrieve a reference to the inner PathBuf. If the output arg is the Stdout variant, this returns None.

Example

use patharg::OutputArg;
use std::path::PathBuf;

let p1 = OutputArg::from_arg("-");
assert_eq!(p1.path_ref(), None);

let p2 = OutputArg::from_arg("file.txt");
assert_eq!(p2.path_ref(), Some(&PathBuf::from("file.txt")));

pub fn path_mut(&mut self) -> Option<&mut PathBuf>

Retrieve a mutable reference to the inner PathBuf. If the output arg is the Stdout variant, this returns None.

Example

use patharg::OutputArg;
use std::path::PathBuf;

let mut p1 = OutputArg::from_arg("-");
assert_eq!(p1.path_mut(), None);

let mut p2 = OutputArg::from_arg("file.txt");
assert_eq!(p2.path_mut(), Some(&mut PathBuf::from("file.txt")));

pub fn into_path(self) -> Option<PathBuf>

Consume the output arg and return the inner PathBuf. If the output arg is the Stdout variant, this returns None.

Example

use patharg::OutputArg;
use std::path::PathBuf;

let p1 = OutputArg::from_arg("-");
assert_eq!(p1.into_path(), None);

let p2 = OutputArg::from_arg("file.txt");
assert_eq!(p2.into_path(), Some(PathBuf::from("file.txt")));

pub fn create(&self) -> Result<OutputArgWriter>

Open the output arg for writing.

If the output arg is the Stdout variant, this returns a locked reference to stdout. Otherwise, if the output arg is a Path variant, the given path is opened for writing; if the path does not exist, it is created.

The returned writer implements std::io::Write.

Errors

Has the same error conditions as std::fs::File::create.

Example

use patharg::OutputArg;
use std::env::args_os;
use std::io::{self, Write};

fn main() -> io::Result<()> {
    let outfile = args_os().nth(1)
                           .map(OutputArg::from_arg)
                           .unwrap_or_default();
    let mut f = outfile.create()?;
    // The "{}" is replaced by either the output filepath or a hyphen.
    write!(&mut f, "I am writing to {}.", outfile)?;
    Ok(())
}

pub fn write<C: AsRef<[u8]>>(&self, contents: C) -> Result<()>

Write a slice as the entire contents of the output arg.

If the output arg is the Stdout variant, the given data is written to stdout. Otherwise, if the output arg is a Path variant, the contents of the given path are replaced with the given data; if the path does not exist, it is created first.

Errors

Has the same error conditions as std::io::Write::write_all and std::fs::write.

Example

use patharg::OutputArg;
use std::env::args_os;
use std::io;

fn main() -> io::Result<()> {
    let outfile = args_os().nth(1)
                           .map(OutputArg::from_arg)
                           .unwrap_or_default();
    outfile.write("This is the output arg's new content.\n")?;
    Ok(())
}

impl OutputArg

pub async fn async_create(&self) -> Result<AsyncOutputArgWriter>

Available on crate feature tokio only.

Asynchronously open the output arg for writing.

If the output arg is the Stdout variant, this returns a reference to stdout. Otherwise, if the output arg is a Path variant, the given path is opened for writing; if the path does not exist, it is created.

The returned writer implements tokio::io::AsyncWrite.

Errors

Has the same error conditions as tokio::fs::File::create.

Example

use patharg::OutputArg;
use std::env::args_os;
use tokio::io::AsyncWriteExt;

#[tokio::main]
async fn main() -> std::io::Result<()> {
    let outfile = args_os().nth(1)
                           .map(OutputArg::from_arg)
                           .unwrap_or_default();
    let mut f = outfile.async_create().await?;
    // The "{}" is replaced by either the output filepath or a hyphen.
    let msg = format!("I am writing to {}.\n", outfile);
    f.write_all(msg.as_ref()).await?;
    Ok(())
}

pub async fn async_write<C: AsRef<[u8]>>(&self, contents: C) -> Result<()>

Available on crate feature tokio only.

Asynchronously write a slice as the entire contents of the output arg.

If the output arg is the Stdout variant, the given data is written to stdout. Otherwise, if the output arg is a Path variant, the contents of the given path are replaced with the given data; if the path does not exist, it is created first.

Errors

Has the same error conditions as tokio::io::AsyncWriteExt::write_all and tokio::fs::write.

Example

use patharg::OutputArg;
use std::env::args_os;

#[tokio::main]
async fn main() -> std::io::Result<()> {
    let outfile = args_os().nth(1)
                           .map(OutputArg::from_arg)
                           .unwrap_or_default();
    outfile.async_write("This is the output arg's new content.\n").await?;
    Ok(())
}

Trait Implementations

impl Clone for OutputArg

fn clone(&self) -> OutputArg

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for OutputArg

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for OutputArg

fn default() -> OutputArg

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for OutputArg

Available on crate feature serde only.

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserializes a PathBuf and converts it to an OutputArg with OutputArg::from_arg().

impl Display for OutputArg

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Displays OutputArg::Stdout as - (a single hyphen/dash) or as <stdout> if the {:#} format is used. Always displays OutputArg::Path using std::path::Path::display().

impl From<OutputArg> for OsString

fn from(arg: OutputArg) -> OsString

Convert an OutputArg back to an OsString: OutputArg::Stdout becomes "-", and OutputArg::Path(p) becomes p.into().

impl<S: Into<PathBuf>> From<S> for OutputArg

fn from(s: S) -> OutputArg

Convert an string to an OutputArg using OutputArg::from_arg().

impl FromStr for OutputArg

fn from_str(s: &str) -> Result<OutputArg, Self::Err>

Convert a string to an OutputArg using OutputArg::from_arg().

type Err = Infallible

The associated error which can be returned from parsing.

impl Hash for OutputArg

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for OutputArg

fn cmp(&self, other: &OutputArg) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for OutputArg

fn eq(&self, other: &OutputArg) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for OutputArg

fn partial_cmp(&self, other: &OutputArg) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for OutputArg

Available on crate feature serde only.

fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error>

Serializes OutputArg::Stdout as "-" (a string containing a single hyphen/dash). Serializes OutputArg::Path as the inner PathBuf; this will fail if the path is not valid UTF-8.

impl Eq for OutputArg

impl StructuralPartialEq for OutputArg