Home Explore Blog CI



nushell

21th chunk of `contributor-book/plugin_protocol_reference.md`
a993e68fce2efedf37b1a216484a38f6ca38e6478ef9e6500000000100000f0e
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
{
  "ListStream": {
    "id": 2,
    "span": {
      "start": 33911,
      "end": 33942
    }
  }
}
```

#### `ByteStream` header variant

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

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

<a name="bytestreamtype"></a> Byte streams carry a `type` field with one of the three following strings:

| `type`      | Meaning                                                                                                                               |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `"Binary"`  | The stream contains binary data of unknown encoding, and should be treated as a `binary` value.                                       |
| `"String"`  | The stream contains text data that is valid UTF-8, and should be treated as a `string` value.                                         |
| `"Unknown"` | The type of the byte stream is unknown and should be inferred depending on whether its contents can be decoded as valid UTF-8 or not. |

The `Unknown` type is used by Nu to represent the output of external commands if they are not passed through [`into string`](/commands/docs/into_string.md) or [`into binary`](/commands/docs/into_binary.md) to explicitly set their type. A command that declares an output type of exclusively either `string` or `binary` **must** explicitly type its output byte streams appropriately, to ensure they coerce to the correct type, rather than using `Unknown`.

Example:

```json
{
  "ByteStream": {
    "id": 7,
    "span": {
      "start": 49011,
      "end": 49027
    },
    "type": "String"
  }
}
```

### `LabeledError`

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

A flexible, generic error type, with any number of labeled spans.

| Field      | Type                  | Description                                                                                                    |
| ---------- | --------------------- | -------------------------------------------------------------------------------------------------------------- |
| **msg**    | string                | The main error message to show at the top of the error.                                                        |

Title: PipelineDataHeader Variants and ByteStreamType
Summary
This section details the `Value`, `ListStream`, and `ByteStream` variants of the `PipelineDataHeader`. `Value` represents a single value, `ListStream` initiates a list stream and includes `ListStreamInfo` (containing the stream ID and span), and `ByteStream` starts a byte stream, including the stream ID, span, and `ByteStreamType`. It further clarifies `ByteStreamType`'s possible values: `Binary`, `String`, and `Unknown`. The section also covers `LabeledError`, an error type with a message and labeled spans.