Home Explore Blog CI



nushell

9th chunk of `contributor-book/plugin_protocol_reference.md`
b3ab3e56421fcab47eabc95f80ee4ba87e289e0f5613b8270000000100000faa
A successful response to the [`PartialCmp` custom value op](#partialcmp). The body is either [`Ordering`](#ordering) if the comparison is possible, or `null` if the values can't be compared.

Example:

```json
{
  "CallResponse": [
    0,
    {
      "Ordering": "Less"
    }
  ]
}
```

Example with incomparable values:

```json
{
  "CallResponse": [
    0,
    {
      "Ordering": null
    }
  ]
}
```

#### `PipelineData` plugin call response

A successful result with a Nu [`Value`](#value) or stream. The body is a [`PipelineDataHeader`](#pipelinedataheader).

Example:

```json
{
  "CallResponse": [
    0,
    {
      "Value": {
        "Int": {
          "val": 42,
          "span": {
            "start": 12,
            "end": 14
          }
        }
      }
    }
  ]
}
```

### `EngineCall`

Plugins can make engine calls during execution of a [call](#call). The body is a map with the following keys:

| Field       | Type         | Description                                                                             |
| ----------- | ------------ | --------------------------------------------------------------------------------------- |
| **context** | integer      | The ID of the [call](#call) that this engine call relates to.                           |
| **id**      | integer      | A unique ID for this engine call, in order to send the [response](#enginecallresponse). |
| **call**    | `EngineCall` | One of the options described below.                                                     |

<a name="enginecall-context"></a>

The context **must** be an ID of a [call](#call) that was received that is currently in one of two states:

1. The [response](#callresponse) has not been sent yet.
2. The response contained stream data (i.e. [`ListStream`](#liststream-header-variant) or [`ByteStream`](#bytestream-header-variant)), and at least one of the streams started by the response is still sending data (i.e. [`End`](#end) has not been sent).

After a response has been fully sent, and streams have ended, the `context` from that call can no longer be used.

The engine call ID **must** be unique for the lifetime of the plugin, and it is suggested that this be a sequentially increasing number across all engine calls made by the plugin. It is not separated by `context`; the response only contains the `id`.

#### `GetConfig` engine call

Get the Nushell engine configuration. Returns a [`Config` response](#config-engine-call-response) if
successful.

Example:

```json
{
  "EngineCall": {
    "context": 0,
    "id": 0,
    "call": "GetConfig"
  }
}
```

#### `GetPluginConfig` engine call

Get the configuration for the plugin, from its section in `$env.config.plugins.NAME` if present. Returns a [`PipelineData` response](#pipelinedata-engine-call-response) if successful, which will contain either a [`Value`](#value-header-variant) or be [`Empty`](#empty-header-variant) if there is no configuration for the plugin set.

If the plugin configuration was specified as a closure, the engine will evaluate that closure and return the result, which may cause an [error response](#error-engine-call-response).

Example:

```json
{
  "EngineCall": {
    "context": 3,
    "id": 8,
    "call": "GetPluginConfig"
  }
}
```

#### `GetEnvVar` engine call

Get an environment variable from the caller's scope. Returns a [`PipelineData` response](#pipelinedata-engine-call-response) if successful, which will contain either a [`Value`](#value-header-variant) or be [`Empty`](#empty-header-variant) if the environment variable is not present.

Example:

```json
{
  "EngineCall": {
    "context": 7,
    "id": 41,
    "call": {
      "GetEnvVar": "PATH"
    }
  }
}
```

#### `GetEnvVars` engine call

Get all environment variables from the caller's scope. Returns a [`ValueMap` response](#valuemap-engine-call-response) if successful, with all of the environment variables in the scope.

Example:

```json
{
  "EngineCall": {
    "context": 9,
    "id": 72,
    "call": "GetEnvVars"

Title: Engine Calls: Configuration, Plugin Config, Environment Variables
Summary
This section details the `EngineCall` structure that allows plugins to call back to the Nushell engine. It describes the essential fields `context` (linking to the original call), `id` (unique identifier for the engine call), and `call` (the specific engine call type). It then explains different `EngineCall` types: `GetConfig` to retrieve the Nushell engine configuration, `GetPluginConfig` to get the plugin's configuration from the environment, `GetEnvVar` to retrieve a single environment variable, and `GetEnvVars` to retrieve all environment variables from the caller's scope.