Home Explore Blog CI



nushell

20th chunk of `contributor-book/plugin_protocol_reference.md`
594fe73d5c19b736c970dd262e98d7f1bf3dd39995cc8b390000000100000fa1
| **type**           | string     | **Must** be `"PluginCustomValue"`.                                                        |
| **name**           | string     | The human-readable name of the custom value emitted by the plugin.                        |
| **data**           | byte array | Plugin-defined representation of the custom value.                                        |
| **notify_on_drop** | boolean    | Enable [drop notification](plugins.md#drop-notification). Default `false` if not present. |

Plugins will only be sent custom values that they have previously emitted. Custom values from other plugins or custom values used within the Nu engine itself are not permitted to be sent to or from the plugin.

`notify_on_drop` is an optional field that **should** be omitted if `false`, to save bytes. If this is not convenient for your implementation, `"notify_on_drop": false` is still valid, but it's preferred to not include it.

Example:

```json
{
  "Custom": {
    "val": {
      "type": "PluginCustomValue",
      "name": "database",
      "data": [36, 190, 127, 40, 12, 3, 46, 83],
      "notify_on_drop": true
    },
    "span": {
      "start": 320,
      "end": 340
    }
  }
}
```

## Embedded Nu types

Several types used within the protocol come from elsewhere in Nu's source code, especially the [`nu-protocol`](https://docs.rs/nu-protocol) crate.

Rust enums are usually encoded in [serde](https://serde.rs)'s default format:

```javascript
"Variant"             // Variant
{ "Variant": value }  // Variant(value)
{ "Variant": [a, b] } // Variant(a, b)
{
  "Variant": {
    "one": 1,
    "two": 2
  }
}                     // Variant { one: 1, two: 2 }
```

Structs are encoded as maps of their fields, without the name of the struct.

### `Span`

[Documentation](https://docs.rs/nu-protocol/latest/nu_protocol/span/struct.Span.html)

Describes a region of code in the engine's memory, used mostly for providing diagnostic error messages to the user with context about where a value that caused an error came from.

| Field     | Type    | Description                                    |
| --------- | ------- | ---------------------------------------------- |
| **start** | integer | The index of the first character referenced.   |
| **end**   | integer | The index after the last character referenced. |

### `PipelineDataHeader`

Describes either a single value, or the beginning of a stream.

| Variant                                    | Description                              |
| ------------------------------------------ | ---------------------------------------- |
| [`Empty`](#empty-header-variant)           | No values produced; an empty stream.     |
| [`Value`](#value-header-variant)           | A single value                           |
| [`ListStream`](#liststream-header-variant) | Specify a list stream that will be sent. |
| [`ByteStream`](#bytestream-header-variant) | Specify a byte stream that will be sent. |

#### `Empty` header variant

An empty stream. Nothing will be sent. There is no identifier, and this is equivalent to a `Nothing` value.

The representation is the following string:

```json
"Empty"
```

#### `Value` header variant

A single value. Does not start a stream, so there is no identifier. Contains a [`Value`](#value).

Example:

```json
{
  "Value": {
    "Int": {
      "val": 2,
      "span": {
        "start": 9090,
        "end": 9093
      }
    }
  }
}
```

#### `ListStream` header variant

Starts a list stream. Expect [`Data`](#data) messages of the `List` variant with the referenced ID.

Contains <a name="liststreaminfo">`ListStreamInfo`</a>, a map:

| Field    | Type            | Description                                       |
| -------- | --------------- | ------------------------------------------------- |
| **id**   | integer         | The stream identifier                             |
| **span** | [`Span`](#span) | The source code reference that caused the stream. |

Example:

```json
{

Title: Nu Value Types: Custom example and Embedded Nu Types
Summary
This section provides an example of the `Custom` value type. Additionally, the section covers embedded Nu types, explaining how Rust enums and structs are encoded in `serde` and delving into the details of `Span` and `PipelineDataHeader`. It outlines the structure of `Span`, highlighting the start and end fields. For `PipelineDataHeader`, it elaborates on the `Empty`, `Value`, and `ListStream` variants. `Empty` indicates an empty stream, `Value` represents a single value (a Value), and `ListStream` begins a list stream, requiring subsequent Data messages of the List variant and containing a ListStreamInfo struct.