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}