Files
Darren Schroeder 85fba6f2d1 Run commands found by id through one IR call path (AST migration phase 3) (#19351)
## Description

This continues the AST → IR call migration (#18808, #18813, #18967). One
commit per step:

1. **Drop argument AST retention.** No command has opted into
`requires_ast_for_arguments` since #18813, so every `IrBlock.ast` entry
was `None`. The opt-in, `IrAstRef`, `IrBlock.ast`, the `ast` field of
`engine::Argument` and `engine::Call::positional_nth` are gone.
`Let::run`, which only an indirect call can reach, now returns an error
like `unlet`'s.
2. **One IR path for running a command by id.**
`nu_engine::eval_ir_call` runs an `ir::Call` the way compiled code does:
input type check, argument normalization, and parameter binding for a
custom command. The VM's call instruction shares the same code. `open`,
`http`, `save`, `%(...)` and a plugin's `call_decl` use it, which fixes
custom commands in three of them.
3. **Display call sites.** `help` (`nu-highlight`, `table`, `ansi`),
`tutor`, `print`, the DAP `print`, `clip copy` and table rendering for
an external's stdin build IR calls. `tutor` highlights through `help`'s
`nu_highlight_string`, so a snippet it can't highlight shows as plain
text instead of disappearing. `engine::Call::new` is deleted.
`CallImpl::to_owned` still turns an `AstRef` into an `AstBox`; phase 4
removes both variants.

## User-facing changes (Release notes)

- `http` commands can convert a response with a custom `from <ext>`
command, as `open` already could.
- `save` binds the flags and defaults of a custom `to <ext>` command.
- A plugin's `call_decl` can call a custom command.

## Breaking changes

### Scripts

- `save` checks a custom `to <ext>` converter's input type, as a direct
call does. A converter whose signature doesn't cover the data now errors
instead of running. Built-in `to` commands are unaffected: inputs they
already rejected now fail with `Input type not supported` instead of the
converter's own message. `open` and `http` hand converters an untyped
byte stream, which any input type accepts, so they don't change.
- `save` keeps a custom `to <ext>` converter's `$env` changes inside it
unless it is `def --env`, the same as `... | to <ext>`.
- `%($cmd)` checks its input and arguments as a direct call does.
Spreading a list into a command without a rest parameter is an error
instead of being ignored.
- `view ir --json` no longer has an `ast` field in `ir_block`. It was
always `null`.

| Command | main | branch |
|---|---|---|
| `def "to foo" []: int -> string { "int" }; [1 2] \| save out.foo; open
--raw out.foo` | `int` | `Input type not supported` (`only int input
data is supported`, input type `list<int>`) |
| `def "to foo" [] { $env.FOO = 1; "x" }; [1] \| save out.foo; $env.FOO?
\| describe` | `int` | `nothing` |
| `def --env "to foo" [] { $env.FOO = 1; "x" }; [1] \| save out.foo;
$env.FOO? \| describe` | `int` | `int` |
| `let cmd = 'length'; let args = [1]; [1 2] \| %($cmd) ...$args` | `2`
(the spread is dropped) | `Cannot spread a list into this command`
(`length ...$args` is a parse error) |
| `view ir --json {\|\| 1 } \| from json \| get ir_block \| columns` |
`[instructions, spans, data, ast, comments, register_count, file_count]`
| `[instructions, spans, data, comments, register_count, file_count]` |

### Plugins

`call_decl` checks the input type, including empty input, as a direct
call does. A call that the command's signature doesn't allow now errors,
the same as when the call is written in a script.

| Command (with `nu_plugin_example`) | main | branch |
|---|---|---|
| `'a' \| example call-decl uniq` | `[a]` | `Input type not supported`
(`only list<any> input data is supported`) |
| `example call-decl 'str join'` | `""` | `Pipeline empty` |

The `IrBlock` returned by the `get_block_ir` engine call no longer has
an `ast` field. Nushell only loads plugins built for the same minor
version, so a plugin never reads the old format from a newer engine.

### Rust API (embedders and out-of-tree `Command` implementations)

Plugins implement `PluginCommand` and are not affected.

| Removed | Instead |
|---|---|
| `engine::Call::new` | Build an `ir::Call` and run it with
`nu_engine::eval_ir_call` (example below). |
| `Command::requires_ast_for_arguments` | Delete the override. No
command has needed it since #18813. |
| `engine::Call::positional_nth`, `ir::Call::positional_ast`,
`engine::Argument::ast_expression` | Read argument values with `CallExt`
(`req`, `opt`, `rest`). On a compiled call these always returned `None`.
|
| The `ast` field of `engine::Argument::{Positional, Spread, Named}` |
Drop it from patterns and struct literals. |
| `ir::IrAstRef`, `IrBlock.ast` | Nothing. |

```diff
-let call = engine::Call::new(span);
-decl.run(engine_state, stack, &call, input)
+let call = ir::Call::build(decl_id, span).finish();
+nu_engine::eval_ir_call(engine_state, stack, &call, input)
```

With arguments, add them to the builder and call `leave` afterwards:

```rust
let mut builder = ir::Call::build(decl_id, span);
builder.add_named(stack, "width", "", span, Value::int(80, span));
let call = builder.finish();
let result = nu_engine::eval_ir_call(engine_state, stack, &call, input);
call.leave(stack);
```

Unlike `decl.run`, `eval_ir_call` also runs custom commands, checks the
input type and normalizes the arguments. Code that can't depend on
`nu-engine` can still pass `&(&call).into()` to `decl.run`.

`ir::Call::leave` on a call without arguments now does nothing. It used
to clear the whole argument stack, including the caller's arguments.

## Additional notes

- Closes #16974.
- Added `nu_engine::eval_ir_call`, which returns an error unless the
call's arguments are the last ones on the stack, and made
`nu_engine::nu_highlight_string` public.
- Next: phase 4 deletes `CallImpl::AstRef`/`AstBox` and the AST
evaluator's call path.
2026-10-28 06:40:31 -05:00

42 lines
927 B
Rust

use nu_test_support::prelude::*;
#[test]
#[deps(NU_PLUGIN_EXAMPLE)]
fn call_to_json() -> Result {
test()
.run("[42] | example call-decl 'to json' {indent: 4}")
.expect_value_eq("[\n 42\n]")
}
#[test]
#[deps(NU_PLUGIN_EXAMPLE)]
fn call_reduce() -> Result {
test()
.run("[1 2 3] | example call-decl 'reduce' {fold: 10} {|it, acc| $it + $acc}")
.expect_value_eq(16)
}
#[test]
#[deps(NU_PLUGIN_EXAMPLE)]
fn call_scope_variables() -> Result {
let code = "
let test_var = 10
example call-decl 'scope variables'
| where name == '$test_var'
| length
";
test().run(code).expect_value_eq(1)
}
#[test]
#[deps(NU_PLUGIN_EXAMPLE)]
fn call_custom_command() -> Result {
let code = "
def double [x: int, --plus: int = 0] { $x * 2 + $plus }
example call-decl double {plus: 1} 21
";
test().run(code).expect_value_eq(43)
}