nu_protocol/ir/mod.rs
1use crate::{
2 BlockId, DeclId, Filesize, RegId, ShellError, Span, Value, VarId,
3 ast::{CellPath, Expression, Operator, Pattern, RangeInclusion},
4 engine::{EngineState, ScopeBindings},
5};
6use chrono::{DateTime, FixedOffset};
7use serde::{Deserialize, Serialize};
8use std::{fmt, sync::Arc};
9
10mod call;
11mod display;
12
13pub use call::*;
14pub use display::{FmtInstruction, FmtIrBlock};
15
16/// Instruction-index range where a nested block's local command/module bindings apply.
17///
18/// Keyword bodies (`if`/`for`/…) are IR-**inlined** into the parent block and never enter
19/// `eval_ir_block`. The compiler records these regions so `scope` can resolve locals by
20/// comparing the current program counter.
21#[derive(Clone, Debug)]
22pub struct ScopeRegion {
23 /// Inclusive start index into [`IrBlock::instructions`].
24 pub start: usize,
25 /// Exclusive end index into [`IrBlock::instructions`].
26 pub end: usize,
27 pub bindings: Arc<ScopeBindings>,
28}
29
30impl ScopeRegion {
31 pub fn contains(&self, instruction_index: usize) -> bool {
32 self.start <= instruction_index && instruction_index < self.end
33 }
34}
35
36#[derive(Clone, Serialize, Deserialize)]
37pub struct IrBlock {
38 pub instructions: Vec<Instruction>,
39 pub spans: Vec<Span>,
40 #[serde(with = "serde_arc_u8_array")]
41 pub data: Arc<[u8]>,
42 /// Additional information that can be added to help with debugging
43 pub comments: Vec<Box<str>>,
44 pub register_count: u32,
45 pub file_count: u32,
46 /// Local scope regions for inlined nested blocks (see [`ScopeRegion`]).
47 /// Not serialized — only meaningful in the process that compiled the block.
48 #[serde(skip)]
49 pub scope_regions: Vec<ScopeRegion>,
50}
51
52impl fmt::Debug for IrBlock {
53 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
54 f.debug_struct("IrBlock")
55 .field("instructions", &self.instructions)
56 .field("spans", &self.spans)
57 .field("data", &self.data)
58 .field("comments", &self.comments)
59 .field("register_count", &self.register_count)
60 .field("file_count", &self.file_count)
61 .field("scope_regions", &self.scope_regions.len())
62 .finish()
63 }
64}
65
66impl IrBlock {
67 /// Returns a value that can be formatted with [`Display`](std::fmt::Display) to show a detailed
68 /// listing of the instructions contained within this [`IrBlock`].
69 pub fn display<'a>(&'a self, engine_state: &'a EngineState) -> FmtIrBlock<'a> {
70 FmtIrBlock {
71 engine_state,
72 ir_block: self,
73 }
74 }
75}
76
77/// A slice into the `data` array of a block. This is a compact and cache-friendly way to store
78/// string data that a block uses.
79#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
80pub struct DataSlice {
81 pub start: u32,
82 pub len: u32,
83}
84
85impl DataSlice {
86 /// A data slice that contains no data. This slice is always valid.
87 pub const fn empty() -> DataSlice {
88 DataSlice { start: 0, len: 0 }
89 }
90}
91
92impl std::ops::Index<DataSlice> for [u8] {
93 type Output = [u8];
94
95 fn index(&self, index: DataSlice) -> &Self::Output {
96 &self[index.start as usize..(index.start as usize + index.len as usize)]
97 }
98}
99
100#[derive(Debug, Clone, Serialize, Deserialize)]
101pub enum Instruction {
102 /// Unreachable code path (error)
103 Unreachable,
104 /// Load a literal value into the `dst` register
105 LoadLiteral { dst: RegId, lit: Literal },
106 /// Load a clone of a boxed value into the `dst` register (e.g. from const evaluation)
107 LoadValue { dst: RegId, val: Box<Value> },
108 /// Move a register. Value is taken from `src` (used by this instruction).
109 Move { dst: RegId, src: RegId },
110 /// Copy a register (must be a collected value). Value is still in `src` after this instruction.
111 ///
112 /// The one exception is an external whose stderr has its own pipe, which `try` passes on
113 /// uncollected (see `TryCollect`): `dst` gets the value its stdout collects to, and `src`
114 /// keeps the external.
115 Clone { dst: RegId, src: RegId },
116 /// Collect a stream in a register to a value.
117 /// Because it collects to a value, nushell will ignore the errors in the stream.
118 /// It's important when the stream is from an external command
119 Collect { src_dst: RegId },
120 /// Collect a stream in a register to a value.
121 /// But it's different from `Collect` in that if there is an error in the stream, it will be
122 /// returned as an error instead of being ignored.
123 ///
124 /// An external whose stderr has its own pipe stays a stream, so the next command still gets
125 /// stdout and stderr apart. Its output is read into memory and its exit status checked.
126 TryCollect { src_dst: RegId },
127 /// Change the span of the contents of a register to the span of this instruction.
128 Span { src_dst: RegId },
129 /// Drop the value/stream in a register, without draining
130 Drop { src: RegId },
131 /// Drain the value/stream in a register and discard (e.g. semicolon).
132 ///
133 /// If passed a stream from an external command, sets $env.LAST_EXIT_CODE to the resulting exit
134 /// code, and invokes any available error handler with Empty, or if not available, returns an
135 /// exit-code-only stream, leaving the block.
136 Drain { src: RegId },
137 /// Drain the value/stream in a register and discard only if this is the last pipeline element.
138 // TODO: see if it's possible to remove this
139 DrainIfEnd { src: RegId },
140 /// Load the value of a variable into the `dst` register.
141 ///
142 /// When `preserve_origin` is false (the default), the value is re-spanned to this
143 /// instruction's span so error labels point at the use site. When true, the value keeps
144 /// the span from where it was defined (used by `metadata $var`).
145 LoadVariable {
146 dst: RegId,
147 var_id: VarId,
148 #[serde(default)]
149 preserve_origin: bool,
150 },
151 /// Store the value of a variable from the `src` register
152 StoreVariable { var_id: VarId, src: RegId },
153 /// Remove a variable from the stack, freeing up whatever resources were associated with it
154 DropVariable { var_id: VarId },
155 /// Load the value of an environment variable into the `dst` register
156 LoadEnv { dst: RegId, key: DataSlice },
157 /// Load the value of an environment variable into the `dst` register, or `Nothing` if it
158 /// doesn't exist
159 LoadEnvOpt { dst: RegId, key: DataSlice },
160 /// Store the value of an environment variable from the `src` register
161 StoreEnv { key: DataSlice, src: RegId },
162 /// Add a positional arg to the next (internal) call.
163 PushPositional { src: RegId },
164 /// Add a list of args to the next (internal) call (spread/rest).
165 AppendRest { src: RegId },
166 /// Add a named arg with no value to the next (internal) call.
167 PushFlag { name: DataSlice },
168 /// Add a short named arg with no value to the next (internal) call.
169 PushShortFlag { short: DataSlice },
170 /// Add a named arg with a value to the next (internal) call.
171 PushNamed { name: DataSlice, src: RegId },
172 /// Add a short named arg with a value to the next (internal) call.
173 PushShortNamed { short: DataSlice, src: RegId },
174 /// Add parser info to the next (internal) call.
175 PushParserInfo {
176 name: DataSlice,
177 info: Box<Expression>,
178 },
179 /// Set the redirection for stdout for the next call (only).
180 ///
181 /// The register for a file redirection is not consumed.
182 RedirectOut { mode: RedirectMode },
183 /// Set the redirection for stderr for the next call (only).
184 ///
185 /// The register for a file redirection is not consumed.
186 RedirectErr { mode: RedirectMode },
187 /// Throw an error if stderr wasn't redirected in the given stream. `src` is preserved.
188 CheckErrRedirected { src: RegId },
189 /// Open a file for redirection, pushing it onto the file stack.
190 OpenFile {
191 file_num: u32,
192 path: RegId,
193 append: bool,
194 },
195 /// Write data from the register to a file. This is done to finish a file redirection, in case
196 /// an internal command or expression was evaluated rather than an external one.
197 ///
198 /// The register is left empty, except for an external whose stderr has its own pipe (the next
199 /// command reads stdout and stderr apart): only its stdout is written, and the register keeps
200 /// the external, so the next command still gets its stderr.
201 WriteFile { file_num: u32, src: RegId },
202 /// Pop a file used for redirection from the file stack.
203 CloseFile { file_num: u32 },
204 /// Make a call. The input is taken from `src_dst`, and the output is placed in `src_dst`,
205 /// overwriting it. The argument stack is used implicitly and cleared when the call ends.
206 Call { decl_id: DeclId, src_dst: RegId },
207 /// Append a value onto the end of a string. Uses `to_expanded_string(", ", ...)` on the value.
208 /// Used for string interpolation literals. Not the same thing as the `++` operator.
209 StringAppend { src_dst: RegId, val: RegId },
210 /// Convert a string into a glob. Used for glob interpolation and setting glob variables. If the
211 /// value is already a glob, it won't be modified (`no_expand` will have no effect).
212 GlobFrom { src_dst: RegId, no_expand: bool },
213 /// Push a value onto the end of a list. Used to construct list literals.
214 ListPush { src_dst: RegId, item: RegId },
215 /// Spread a value onto the end of a list. Used to construct list literals.
216 ListSpread { src_dst: RegId, items: RegId },
217 /// Insert a key-value pair into a record. Used to construct record literals. Raises an error if
218 /// the key already existed in the record.
219 RecordInsert {
220 src_dst: RegId,
221 key: RegId,
222 val: RegId,
223 },
224 /// Spread a record onto a record. Used to construct record literals. Any existing value for the
225 /// key is overwritten.
226 RecordSpread { src_dst: RegId, items: RegId },
227 /// Negate a boolean.
228 Not { src_dst: RegId },
229 /// Do a binary operation on `lhs_dst` (left) and `rhs` (right) and write the result to
230 /// `lhs_dst`.
231 BinaryOp {
232 lhs_dst: RegId,
233 op: Operator,
234 rhs: RegId,
235 },
236 /// Follow a cell path on the value in `src_dst`, storing the result back to `src_dst`
237 FollowCellPath { src_dst: RegId, path: RegId },
238 /// Clone the value at a cell path in `src`, storing the result to `dst`. The original value
239 /// remains in `src`. Must be a collected value.
240 CloneCellPath { dst: RegId, src: RegId, path: RegId },
241 /// Update/insert a cell path to `new_value` on the value in `src_dst`, storing the modified
242 /// value back to `src_dst`
243 UpsertCellPath {
244 src_dst: RegId,
245 path: RegId,
246 new_value: RegId,
247 },
248 /// Update/insert a cell path directly on a variable in the stack, without cloning the
249 /// variable first. Combines LoadVariable + UpsertCellPath + StoreVariable into a single
250 /// in-place mutation. The variable must be mutable.
251 UpdateVarCellPath {
252 var_id: VarId,
253 cell_path: RegId,
254 new_value: RegId,
255 },
256 /// Jump to an offset in this block
257 Jump { index: usize },
258 /// Branch to an offset in this block if the value of the `cond` register is a true boolean,
259 /// otherwise continue execution
260 BranchIf { cond: RegId, index: usize },
261 /// Branch to an offset in this block if the value of the `src` register is Empty or Nothing,
262 /// otherwise continue execution. The original value in `src` is preserved.
263 BranchIfEmpty { src: RegId, index: usize },
264 /// Match a pattern on `src`. If the pattern matches, branch to `index` after having set any
265 /// variables captured by the pattern. If the pattern doesn't match, continue execution. The
266 /// original value is preserved in `src` through this instruction.
267 Match {
268 pattern: Box<Pattern>,
269 src: RegId,
270 index: usize,
271 },
272 /// Check that a match guard is a boolean, throwing
273 /// [`MatchGuardNotBool`](crate::ShellError::MatchGuardNotBool) if it isn't. Preserves `src`.
274 CheckMatchGuard { src: RegId },
275 /// Iterate on register `stream`, putting the next value in `dst` if present, or jumping to
276 /// `end_index` if the iterator is finished
277 Iterate {
278 dst: RegId,
279 stream: RegId,
280 end_index: usize,
281 },
282 /// Jump to an offset in this block, unwinding through `handlers` entries of the `try`
283 /// handler stack first. This is how `break` and `continue` leave `try` expressions: any
284 /// `finally` block among those handlers runs before the jump completes.
285 UnwindJump { index: usize, handlers: usize },
286 /// Push a `catch` handler, without capturing the error value
287 OnError { index: usize },
288 /// Push a `catch` handler, capturing the error value into `dst`. If the error handler is not
289 /// called, the register should be freed manually.
290 OnErrorInto { index: usize, dst: RegId },
291 /// Push a `finally` handler, capturing the error value into `dst`. If the handler is entered
292 /// for any other reason than an error, `dst` is set to empty instead.
293 FinallyInto { index: usize, dst: RegId },
294 /// Pop a `catch` handler. This is not necessary when control flow is directed to the error
295 /// handler due to an error.
296 PopErrorHandler,
297 /// Mark the `finally` handler on top of the handler stack as running, on the way into its
298 /// block from the `try`/`catch` fall-through path. The unwinder does this itself when it
299 /// enters a `finally` block, so `index` of `finally` points just past this instruction.
300 BeginFinally,
301 /// Leave a `finally` block: pops its running marker and, if the block was entered by
302 /// unwinding (an error, `return`, `exit`, `break`, or `continue`), resumes that unwinding.
303 EndFinally,
304 /// Return early from the block with the value in the register.
305 ///
306 /// Unlike `return`, this runs pending `finally` handlers first (collecting the value in that
307 /// case, like the `try-collect` on the fall-through path), and flags the result as an early
308 /// return. Custom command and closure calls clear that flag; only top-level file evaluation
309 /// reads it, to skip `main`.
310 ReturnEarly { src: RegId },
311 /// Return from the block with the value in the register
312 Return { src: RegId },
313}
314
315impl Instruction {
316 /// Returns a value that can be formatted with [`Display`](std::fmt::Display) to show a detailed
317 /// listing of the instruction.
318 pub fn display<'a>(
319 &'a self,
320 engine_state: &'a EngineState,
321 data: &'a [u8],
322 ) -> FmtInstruction<'a> {
323 FmtInstruction {
324 engine_state,
325 instruction: self,
326 data,
327 }
328 }
329
330 /// Get the output register, for instructions that produce some kind of immediate result.
331 pub fn output_register(&self) -> Option<RegId> {
332 match *self {
333 Instruction::Unreachable => None,
334 Instruction::LoadLiteral { dst, .. } => Some(dst),
335 Instruction::LoadValue { dst, .. } => Some(dst),
336 Instruction::Move { dst, .. } => Some(dst),
337 Instruction::Clone { dst, .. } => Some(dst),
338 Instruction::Collect { src_dst } => Some(src_dst),
339 Instruction::TryCollect { src_dst } => Some(src_dst),
340 Instruction::Span { src_dst } => Some(src_dst),
341 Instruction::Drop { .. } => None,
342 Instruction::Drain { .. } => None,
343 Instruction::DrainIfEnd { .. } => None,
344 Instruction::LoadVariable { dst, .. } => Some(dst),
345 Instruction::StoreVariable { .. } => None,
346 Instruction::DropVariable { .. } => None,
347 Instruction::LoadEnv { dst, .. } => Some(dst),
348 Instruction::LoadEnvOpt { dst, .. } => Some(dst),
349 Instruction::StoreEnv { .. } => None,
350 Instruction::PushPositional { .. } => None,
351 Instruction::AppendRest { .. } => None,
352 Instruction::PushFlag { .. } => None,
353 Instruction::PushShortFlag { .. } => None,
354 Instruction::PushNamed { .. } => None,
355 Instruction::PushShortNamed { .. } => None,
356 Instruction::PushParserInfo { .. } => None,
357 Instruction::RedirectOut { .. } => None,
358 Instruction::RedirectErr { .. } => None,
359 Instruction::CheckErrRedirected { .. } => None,
360 Instruction::OpenFile { .. } => None,
361 Instruction::WriteFile { .. } => None,
362 Instruction::CloseFile { .. } => None,
363 Instruction::Call { src_dst, .. } => Some(src_dst),
364 Instruction::StringAppend { src_dst, .. } => Some(src_dst),
365 Instruction::GlobFrom { src_dst, .. } => Some(src_dst),
366 Instruction::ListPush { src_dst, .. } => Some(src_dst),
367 Instruction::ListSpread { src_dst, .. } => Some(src_dst),
368 Instruction::RecordInsert { src_dst, .. } => Some(src_dst),
369 Instruction::RecordSpread { src_dst, .. } => Some(src_dst),
370 Instruction::Not { src_dst } => Some(src_dst),
371 Instruction::BinaryOp { lhs_dst, .. } => Some(lhs_dst),
372 Instruction::FollowCellPath { src_dst, .. } => Some(src_dst),
373 Instruction::CloneCellPath { dst, .. } => Some(dst),
374 Instruction::UpsertCellPath { src_dst, .. } => Some(src_dst),
375 Instruction::UpdateVarCellPath { .. } => None,
376 Instruction::Jump { .. } => None,
377 Instruction::UnwindJump { .. } => None,
378 Instruction::BranchIf { .. } => None,
379 Instruction::BranchIfEmpty { .. } => None,
380 Instruction::Match { .. } => None,
381 Instruction::CheckMatchGuard { .. } => None,
382 Instruction::Iterate { dst, .. } => Some(dst),
383 Instruction::OnError { .. } => None,
384 Instruction::OnErrorInto { .. } => None,
385 Instruction::FinallyInto { .. } => None,
386 Instruction::PopErrorHandler => None,
387 Instruction::BeginFinally => None,
388 Instruction::EndFinally => None,
389 Instruction::ReturnEarly { .. } => None,
390 Instruction::Return { .. } => None,
391 }
392 }
393
394 /// Returns the branch target index of the instruction if this is a branching instruction.
395 pub fn branch_target(&self) -> Option<usize> {
396 match self {
397 Instruction::Jump { index } => Some(*index),
398 Instruction::UnwindJump { index, handlers: _ } => Some(*index),
399 Instruction::BranchIf { cond: _, index } => Some(*index),
400 Instruction::BranchIfEmpty { src: _, index } => Some(*index),
401 Instruction::Match {
402 pattern: _,
403 src: _,
404 index,
405 } => Some(*index),
406
407 Instruction::Iterate {
408 dst: _,
409 stream: _,
410 end_index,
411 } => Some(*end_index),
412 Instruction::OnError { index } => Some(*index),
413 Instruction::OnErrorInto { index, dst: _ } => Some(*index),
414 Instruction::FinallyInto { index, dst: _ } => Some(*index),
415 _ => None,
416 }
417 }
418
419 /// Sets the branch target of the instruction if this is a branching instruction.
420 ///
421 /// Returns `Err(target_index)` if it isn't a branching instruction.
422 pub fn set_branch_target(&mut self, target_index: usize) -> Result<(), usize> {
423 match self {
424 Instruction::Jump { index } => *index = target_index,
425 Instruction::UnwindJump { index, handlers: _ } => *index = target_index,
426 Instruction::BranchIf { cond: _, index } => *index = target_index,
427 Instruction::BranchIfEmpty { src: _, index } => *index = target_index,
428 Instruction::Match {
429 pattern: _,
430 src: _,
431 index,
432 } => *index = target_index,
433
434 Instruction::Iterate {
435 dst: _,
436 stream: _,
437 end_index,
438 } => *end_index = target_index,
439 Instruction::OnError { index } => *index = target_index,
440 Instruction::OnErrorInto { index, dst: _ } => *index = target_index,
441 Instruction::FinallyInto { index, dst: _ } => *index = target_index,
442 _ => return Err(target_index),
443 }
444 Ok(())
445 }
446
447 /// Check for an interrupt before certain instructions
448 pub fn check_interrupt(
449 &self,
450 engine_state: &EngineState,
451 span: &Span,
452 ) -> Result<(), ShellError> {
453 match self {
454 Instruction::Jump { .. }
455 | Instruction::UnwindJump { .. }
456 | Instruction::Return { .. } => engine_state.signals().check(span),
457 _ => Ok(()),
458 }
459 }
460}
461
462// This is to document/enforce the size of `Instruction` in bytes.
463// We should try to avoid increasing the size of `Instruction`,
464// and PRs that do so will have to change the number below so that it's noted in review.
465const _: () = assert!(std::mem::size_of::<Instruction>() <= 24);
466
467/// A literal value that can be embedded in an instruction.
468#[derive(Debug, Clone, Serialize, Deserialize)]
469pub enum Literal {
470 Bool(bool),
471 Int(i64),
472 Float(f64),
473 Filesize(Filesize),
474 Duration(i64),
475 Binary(DataSlice),
476 Block(BlockId),
477 Closure(BlockId),
478 RowCondition(BlockId),
479 Range {
480 start: RegId,
481 step: RegId,
482 end: RegId,
483 inclusion: RangeInclusion,
484 },
485 List {
486 capacity: usize,
487 },
488 Record {
489 capacity: usize,
490 },
491 Filepath {
492 val: DataSlice,
493 no_expand: bool,
494 },
495 Directory {
496 val: DataSlice,
497 no_expand: bool,
498 },
499 GlobPattern {
500 val: DataSlice,
501 no_expand: bool,
502 },
503 String(DataSlice),
504 RawString(DataSlice),
505 CellPath(Box<CellPath>),
506 Date(Box<DateTime<FixedOffset>>),
507 Nothing,
508 /// Represents an empty pipeline input (distinct from `Nothing` which is the `null` value).
509 /// Used by `load_empty` to initialize registers with no input.
510 Empty,
511}
512
513/// A redirection mode for the next call. See [`OutDest`](crate::OutDest).
514///
515/// This is generated by:
516///
517/// 1. Explicit redirection in a [`PipelineElement`](crate::ast::PipelineElement), or
518/// 2. The [`pipe_redirection()`](crate::engine::Command::pipe_redirection) of the command being
519/// piped into.
520///
521/// Not setting it uses the default, determined by [`Stack`](crate::engine::Stack).
522#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
523pub enum RedirectMode {
524 Pipe,
525 PipeRaw,
526 PipeSeparate,
527 Value,
528 Null,
529 Inherit,
530 Print,
531 /// Use the given numbered file.
532 File {
533 file_num: u32,
534 },
535 /// Use the redirection mode requested by the caller, for a pre-return call.
536 Caller,
537}
538
539/// Just a hack to allow `Arc<[u8]>` to be serialized and deserialized
540mod serde_arc_u8_array {
541 use serde::{Deserialize, Serialize};
542 use std::sync::Arc;
543
544 pub fn serialize<S>(data: &Arc<[u8]>, ser: S) -> Result<S::Ok, S::Error>
545 where
546 S: serde::Serializer,
547 {
548 data.as_ref().serialize(ser)
549 }
550
551 pub fn deserialize<'de, D>(de: D) -> Result<Arc<[u8]>, D::Error>
552 where
553 D: serde::Deserializer<'de>,
554 {
555 let data: Vec<u8> = Deserialize::deserialize(de)?;
556 Ok(data.into())
557 }
558}