Home Explore Blog CI



nushell

19th chunk of `contributor-book/plugin_protocol_reference.md`
8429d1519ce7507695cffd3c59c4363e4ff3c6f8ab7d359c0000000100000fa5
```

### `Binary`

An array of raw bytes. This is sometimes returned from operations that detect data that isn't valid as UTF-8, but can also be created with `into binary` or binary literals.

| Field    | Type            |
| -------- | --------------- |
| **val**  | byte array      |
| **span** | [`Span`](#span) |

Note that the encoding of byte arrays in [JSON](#json) and [MessagePack](#messagepack) is different - the former uses an array of numbers, but the latter uses the native byte array support.

Example:

```nu
0x[aa bb cc dd]
```

```json
{
  "Binary": {
    "val": [170, 187, 204, 221],
    "span": {
      "start": 659637,
      "end": 659652
    }
  }
}
```

### `CellPath`

Represents a path into subfields of lists, records, and tables.

| Field    | Type            |
| -------- | --------------- |
| **val**  | `CellPath`      |
| **span** | [`Span`](#span) |

`CellPath` is defined as:

| Field       | Type         |
| ----------- | ------------ |
| **members** | `PathMember` |

`PathMember` has two variants, `String` or `Int`, and both contain the following fields:

| Field        | Type                      |
| ------------ | ------------------------- |
| **val**      | string / unsigned integer |
| **span**     | [`Span`](#span)           |
| **optional** | boolean                   |

Optional path members will not cause errors if they can't be accessed - the path access will just return [`Nothing`](#nothing) instead.

Example:

```nu
foo.0?.bar
# [foo {value: 0, optional: true} bar] | into cell-path
```

```json
{
  "CellPath": {
    "val": {
      "members": [
        {
          "String": {
            "val": "foo",
            "span": {
              "start": 659835,
              "end": 659838
            },
            "optional": false
          }
        },
        {
          "Int": {
            "val": 0,
            "span": {
              "start": 659847,
              "end": 659848
            },
            "optional": true
          }
        },
        {
          "String": {
            "val": "bar",
            "span": {
              "start": 659866,
              "end": 659869
            },
            "optional": false
          }
        }
      ]
    },
    "span": {
      "start": 659873,
      "end": 659887
    }
  }
}
```

### `Custom`

Represents data types that extend the base nushell types with custom functionality. Plugins can use custom values to implement native-like data types that can be indexed by cell paths, operated on by operators, and compared in plugin-defined ways.

`Custom` values for plugins **may** only contain the following content map:

| Field              | Type       | Description                                                                               |
| ------------------ | ---------- | ----------------------------------------------------------------------------------------- |
| **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],

Title: Nu Value Types: CellPath and Custom
Summary
This section details the Nu `Value` types `CellPath` and `Custom`. `CellPath` represents paths into subfields of lists, records, and tables, with examples of how `PathMember` can be a `String` or an `Int` and can be optional. `Custom` values are data types that extend the base Nu types with custom functionality, allowing plugins to implement native-like data types, with specified constraints on content and interaction between plugins and the core engine.