Skip to main content

nu_protocol/pipeline/
out_dest.rs

1use std::{fs::File, io, process::Stdio, sync::Arc};
2
3/// Describes where to direct a command's stdout or stderr.
4///
5/// Used both for external-process stdio wiring and for Nushell's internal
6/// pipeline destination (print vs pipe vs collect-to-value, etc.).
7#[derive(Debug, Clone)]
8pub enum OutDest {
9    /// Redirect the stdout and/or stderr of one command as the input for the next command in the pipeline.
10    ///
11    /// The output pipe will be available as the `stdout` of [`ChildProcess`](crate::process::ChildProcess).
12    ///
13    /// If stdout and stderr are both set to `Pipe`,
14    /// then they will combined into the `stdout` of [`ChildProcess`](crate::process::ChildProcess).
15    Pipe,
16    /// Redirect stdout as the input for the next command, when that command reads the output as
17    /// text rather than as data: an external command, `run-external` or `print`.
18    ///
19    /// Commands treat this exactly like `Pipe`, except an extern with `@structured`, which runs
20    /// as written instead of decoding its output. Only stdout is ever set to this, and only by a
21    /// plain `|`, so it reaches the last command of a `do` block or custom command piped into
22    /// such a command too.
23    PipeRaw,
24    /// Redirect the stdout and/or stderr of one command as the input for the next command in the pipeline.
25    ///
26    /// The output stream(s) will be available in the `stdout` or `stderr` of [`ChildProcess`](crate::process::ChildProcess).
27    ///
28    /// This is similar to `Pipe` but will never combine stdout and stderr
29    /// or place an external command's stderr into `stdout` of [`ChildProcess`](crate::process::ChildProcess).
30    PipeSeparate,
31    /// Signifies the result of the pipeline will be immediately collected into a value after this command.
32    ///
33    /// So, it is fine to collect the stream ahead of time in the current command.
34    Value,
35    /// Ignore output.
36    ///
37    /// This will forward output to the null device for the platform.
38    Null,
39    /// Output to nushell's stdout or stderr (only for external commands).
40    ///
41    /// This causes external commands to inherit nushell's stdout or stderr. This also causes
42    /// [`ListStream`](crate::ListStream)s to be drained, but not to be printed.
43    Inherit,
44    /// Print to nushell's stdout or stderr.
45    ///
46    /// This is just like `Inherit`, except that [`ListStream`](crate::ListStream)s and
47    /// [`Value`](crate::Value)s are also printed.
48    ///
49    /// This is the only destination treated as "not redirected" by
50    /// [`OutDest::is_redirected`] / the `is-redirected` command.
51    Print,
52    /// Redirect output to a file.
53    File(Arc<File>), // Arc<File>, since we sometimes need to clone `OutDest` into iterators, etc.
54}
55
56impl OutDest {
57    /// Returns `true` when output is *not* sent through the interactive display path.
58    ///
59    /// Only [`OutDest::Print`] is treated as displayed. Every other variant means the
60    /// pipeline result is consumed elsewhere (next command, `let`/subexpression,
61    /// file, null device, or inherit-without-printing).
62    ///
63    /// This is **not** an OS-level TTY check. For whether process stdio is a terminal,
64    /// use the `is-terminal` command (`std::io::IsTerminal`).
65    ///
66    /// # Examples
67    ///
68    /// ```
69    /// # use nu_protocol::OutDest;
70    /// assert!(!OutDest::Print.is_redirected());
71    /// assert!(OutDest::Pipe.is_redirected());
72    /// assert!(OutDest::Value.is_redirected());
73    /// ```
74    #[must_use]
75    pub fn is_redirected(&self) -> bool {
76        !matches!(self, Self::Print)
77    }
78}
79
80impl From<File> for OutDest {
81    fn from(file: File) -> Self {
82        Arc::new(file).into()
83    }
84}
85
86impl From<Arc<File>> for OutDest {
87    fn from(file: Arc<File>) -> Self {
88        Self::File(file)
89    }
90}
91
92impl TryFrom<&OutDest> for Stdio {
93    type Error = io::Error;
94
95    fn try_from(out_dest: &OutDest) -> Result<Self, Self::Error> {
96        match out_dest {
97            OutDest::Pipe | OutDest::PipeRaw | OutDest::PipeSeparate | OutDest::Value => {
98                Ok(Self::piped())
99            }
100            OutDest::Null => Ok(Self::null()),
101            OutDest::Print | OutDest::Inherit => Ok(Self::inherit()),
102            OutDest::File(file) => Ok(file.try_clone()?.into()),
103        }
104    }
105}