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}