Struct clio::Output

pub struct Output { /* private fields */ }

A struct that represents a command line output stream, either Stdout or a File along with it’s path

It is designed to be used with the clap crate when taking a file name as an argument to CLI app

use clap::Parser;
use clio::Output;

#[derive(Parser)]
struct Opt {
    /// path to file, use '-' for stdout
    #[clap(value_parser)]
    output_file: Output,

    /// default name for file is user passes in a directory
    #[clap(value_parser = clap::value_parser!(Output).default_name("run.log"))]
    log_file: Output,

    /// Write output atomically using temp file and atomic rename
    #[clap(value_parser = clap::value_parser!(Output).atomic())]
    config_file: Output,
}

Implementations

impl Output

pub fn new<S: TryInto<ClioPath>>(path: S) -> Result<Self>where Error: From<<S as TryInto<ClioPath>>::Error>,

Contructs a new output either by opening/creating the file or for ‘-’ returning stdout

pub fn std() -> Self

Contructs a new output for stdout

pub fn try_from_os_str(path: &OsStr) -> Result<Self, OsString>

Contructs a new output either by opening/creating the file or for ‘-’ returning stdout

The error is converted to a OsString so that stuctopt can show it to the user.

It is recomended that you use TryFrom::try_from and clap 3.0 instead.

pub fn finish(self) -> Result<()>

Syncs the file to disk or closes any HTTP connections and returns any errors or on the file if a regular file For atomic files this must be called to perform the final atomic swap

pub fn lock<'a>(&'a mut self) -> Box<dyn Write + 'a>

If the output is std out locks it. usefull in multithreaded context to write lines consistently

Examples

let mut file = clio::Output::new("-")?;

writeln!(file.lock(), "hello world")?;

pub fn get_file(&mut self) -> Option<&mut File>

If output is a file, returns a reference to the file, otherwise if output is stdout or a pipe returns none.

pub fn path(&self) -> &ClioPath

The original path used to create this Output

pub fn can_seek(&self) -> bool

Returns true if this Output is a file, and false if this Output is std out or a pipe

Trait Implementations

impl Clone for Output

Available on crate feature clap-parse only.

Opens a new handle on the file from the path that was used to create it Probbably a bad idea to have two write handles to the same file or to std in There is no effort done to make the clone be at the same position as the original

This will panic if the file has been deleted

Only included when using the clap-parse fature as it is needed for value_parser

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Output

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

Formats the value using the given formatter.

impl Default for Output

fn default() -> Self

Returns the “default value” for a type.

impl Display for Output

formats as the path it was created from

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

Formats the value using the given formatter.

impl Seek for Output

fn seek(&mut self, pos: SeekFrom) -> IoResult<u64>

Seek to an offset, in bytes, in a stream.

fn rewind(&mut self) -> Result<(), Error>

Rewind to the beginning of a stream.

fn stream_len(&mut self) -> Result<u64, Error>

🔬This is a nightly-only experimental API. (seek_stream_len)

Returns the length of this stream (in bytes).

fn stream_position(&mut self) -> Result<u64, Error>

Returns the current seek position from the start of the stream.

impl TryFrom<&OsStr> for Output

type Error = Error

The type returned in the event of a conversion error.

fn try_from(file_name: &OsStr) -> Result<Self>

Performs the conversion.

impl TryFrom<&OsString> for Output

type Error = Error

The type returned in the event of a conversion error.

fn try_from(file_name: &OsString) -> Result<Self>

Performs the conversion.

impl TryFrom<&Path> for Output

type Error = Error

The type returned in the event of a conversion error.

fn try_from(file_name: &Path) -> Result<Self>

Performs the conversion.

impl TryFrom<&PathBuf> for Output

type Error = Error

The type returned in the event of a conversion error.

fn try_from(file_name: &PathBuf) -> Result<Self>

Performs the conversion.

impl TryFrom<&String> for Output

type Error = Error

The type returned in the event of a conversion error.

fn try_from(file_name: &String) -> Result<Self>

Performs the conversion.

impl TryFrom<&str> for Output

type Error = Error

The type returned in the event of a conversion error.

fn try_from(file_name: &str) -> Result<Self>

Performs the conversion.

impl TryFrom<ClioPath> for Output

type Error = Error

The type returned in the event of a conversion error.

fn try_from(file_name: ClioPath) -> Result<Self>

Performs the conversion.

impl ValueParserFactory for Output

Available on crate feature clap-parse only.

type Parser = OsStrParser<Output>

Generated parser, usually ValueParser.

fn value_parser() -> Self::Parser

Create the specified Self::Parser

impl Write for Output

fn flush(&mut self) -> IoResult<()>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write(&mut self, buf: &[u8]) -> IoResult<usize>

Write a buffer into this writer, returning how many bytes were written.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Selfwhere Self: Sized,

Creates a “by reference” adapter for this instance of Write.