Skip to main content

shell/
shell.rs

1//! The [`Shell`] trait: the interface every shell implementation exposes.
2//!
3//! The Shell layer is a command language plus execution
4//! coordination. Concrete shells — Bash and Zsh on Unix, PowerShell and
5//! cmd on Windows — differ in their language flavor, prompt style, and
6//! builtins, but the application drives them through this trait, so a VM
7//! boots into whichever shell its OS declares (or the user selects with
8//! `--shell`).
9//!
10//! The trait is deliberately OS-agnostic: shells may sit on a Unix OS
11//! ([`Bash`](crate::bash::Bash), [`Zsh`](crate::zsh::Zsh)) or on Windows
12//! ([`PowerShell`](crate::powershell::PowerShell),
13//! [`Cmd`](crate::cmd::Cmd)), so the application (changing from Zsh → Bash
14//! changes shell behavior while preserving OS state) treats them
15//! uniformly.
16
17use engine::{Engine, Input, Output, Terminal, Timestamp, VirtualPath};
18use os::ExitStatus;
19
20/// A shell implementation.
21///
22/// Implementations own the session's working directory, environment, and
23/// command runtime; the application owns input reading and screen state.
24pub trait Shell {
25    /// The shell's name (`"bash"`, `"zsh"`, `"powershell"`, ...).
26    fn name(&self) -> &'static str;
27
28    /// The engine this shell operates on.
29    fn engine(&self) -> &Engine;
30
31    /// The acting identity (used for filesystem lookups, for example tab
32    /// completion).
33    fn actor(&self) -> engine::ActorId;
34
35    /// The shell environment (variables, `PATH`, `HOME`, ...).
36    fn environment(&self) -> &os::Environment;
37
38    /// The boot time of the underlying OS (used for login banners).
39    fn boot_time(&self) -> Timestamp;
40
41    /// The virtual host name (from `/etc/hostname` or the OS equivalent).
42    fn hostname(&self) -> String;
43
44    /// The current working directory.
45    fn cwd(&self) -> &VirtualPath;
46
47    /// The prompt string, ending with a trailing space.
48    ///
49    /// `hostname` is the virtual host name (read from `/etc/hostname` or
50    /// the equivalent by the application).
51    fn prompt(&self, hostname: &str) -> String;
52
53    /// The banner printed before the first prompt, or `None` when the
54    /// shell prints none. Unix shells print the `Last login` line; the
55    /// Windows shells print their startup banners.
56    fn banner(&self) -> Option<String>;
57
58    /// Reports the terminal size, exported as `COLUMNS`/`LINES` so commands
59    /// (for example `ls`) lay out against the live console width.
60    ///
61    /// The application calls this at session start and whenever the host
62    /// terminal is resized.
63    fn set_terminal_size(&mut self, rows: u16, cols: u16);
64
65    /// Executes a line of shell input.
66    fn execute(
67        &mut self,
68        line: &str,
69        stdin: &mut dyn Input,
70        stdout: &mut dyn Output,
71        stderr: &mut dyn Output,
72    ) -> ExitStatus;
73
74    /// Executes a line with an optional terminal.
75    fn execute_with_terminal(
76        &mut self,
77        line: &str,
78        stdin: &mut dyn Input,
79        stdout: &mut dyn Output,
80        stderr: &mut dyn Output,
81        terminal: Option<&mut dyn Terminal>,
82    ) -> ExitStatus;
83
84    /// Takes a pending session-exit request (`exit [N]`), if any.
85    ///
86    /// The application calls this after executing a line: when it returns
87    /// `Some`, the session is over — stop reading input and use the carried
88    /// status as the process exit code. This keeps exit semantics inside
89    /// the shell language (`exit`, `exit 3`, scripts) instead of the
90    /// application matching command strings.
91    fn take_exit_status(&mut self) -> Option<ExitStatus>;
92
93    /// The command history: exactly the lines the interactive application
94    /// recorded through [`Shell::record_history`].
95    fn history(&self) -> &[String];
96
97    /// Records one completed command line.
98    ///
99    /// The interactive application calls this once per executed line — the
100    /// whole of a multi-line construct, not its continuation chunks — so
101    /// `history` and the `history` builtin show what the user actually
102    /// typed. The shell owns the list; the application's prompt editor
103    /// reads it for up/down-arrow recall.
104    fn record_history(&mut self, line: &str);
105
106    /// Whether the input is an incomplete construct that needs more lines
107    /// (for example a here-document or an unclosed `if`).
108    fn needs_continuation(&self, input: &str) -> bool {
109        let _ = input;
110        false
111    }
112}