Skip to main content

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}