Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fixup usage->description in plugin stuff #1743

Merged
merged 3 commits into from
Jan 9, 2025
Merged

Fixup usage->description in plugin stuff #1743

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a43c138
Fixup `usage`->`description` in plugin stuff
sholderbach Jan 9, 2025
2ce4ca8
Fix table headers along similar lines
sholderbach Jan 9, 2025
688c29e
Fix whitespace in table header
sholderbach Jan 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 16 additions & 16 deletions contributor-book/plugin_protocol_reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ The engine **may** send a [`Goodbye`](#goodbye) message to the plugin indicating

After the encoding type has been decided, both the engine and plugin **must** send a `Hello` message containing relevant version and protocol support information.

| Field | Type | Usage |
| Field | Type | Description |
| ------------ | ------ | ------------------------------------------------------------------------------------- |
| **protocol** | string | **Must** be `"nu-plugin"`. |
| **version** | string | The engine's version, or the target version of Nu that the plugin supports. |
Expand Down Expand Up @@ -125,7 +125,7 @@ Example:

Tell the plugin to run a command. The argument is the following map:

| Field | Type | Usage |
| Field | Type | Description |
| --------- | ------------------------------------------- | ----------------------------------------------------- |
| **name** | string | The name of the command to run |
| **call** | [`EvaluatedCall`](#evaluatedcall) | Information about the invocation, including arguments |
Expand All @@ -135,7 +135,7 @@ Tell the plugin to run a command. The argument is the following map:

`EvaluatedCall` is a map:

| Field | Type | Usage |
| Field | Type | Description |
| -------------- | ------------------------------------------------- | ------------------------------------------------------- |
| **head** | [`Span`](#span) | The position of the beginning of the command execution. |
| **positional** | [`Value`](#value) array | Positional arguments. |
Expand Down Expand Up @@ -634,7 +634,7 @@ Example:

A successful response to a [`Metadata` plugin call](#metadata-plugin-call). The body contains fields that describe the plugin, none of which are required:

| Field | Type | Usage |
| Field | Type | Description |
| ----------- | ------- | ------------------------------------------------------------------------------------------------------------- |
| **version** | string? | The version of the plugin (not the protocol!). [SemVer](https://semver.org) is recommended, but not required. |

Expand Down Expand Up @@ -668,8 +668,8 @@ Example:
{
"sig": {
"name": "len",
"usage": "calculates the length of its input",
"extra_usage": "",
"description": "calculates the length of its input",
"extra_description": "",
"search_terms": [],
"required_positional": [],
"optional_positional": [],
Expand Down Expand Up @@ -762,7 +762,7 @@ Example:

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

| Field | Type | Usage |
| 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). |
Expand Down Expand Up @@ -975,7 +975,7 @@ Example:

Pass a [`Closure`](#closure) and arguments to the engine to be evaluated. Returns a [`PipelineData` response](#pipelinedata-engine-call-response) if successful with the output of the closure, which may be a stream.

| Field | Type | Usage |
| Field | Type | Description |
| ------------------- | ------------------------------------------- | ---------------------------------------------------------------------- |
| **closure** | spanned [`Closure`](#closure) | The closure to call, generally from a [`Value`](#value). |
| **positional** | [`Value`](#value) array | Positional arguments for the closure. |
Expand Down Expand Up @@ -1048,7 +1048,7 @@ Example:

Pass a command's declaration ID (found via [`FindDecl`](#finddecl-engine-call)) and arguments to the engine to be called. Returns a [`PipelineData` response](#pipelinedata-engine-call-response) if successful with the output of the command, which may be a stream.

| Field | Type | Usage |
| Field | Type | Description |
| ------------------- | ------------------------------------------- | ------------------------------------------------------------------------------- |
| **decl_id** | unsigned integer | The ID of the declaration to call. |
| **call** | [`EvaluatedCall`](#evaluatedcall) | Arguments and head span for the call. |
Expand Down Expand Up @@ -2082,7 +2082,7 @@ Represents data types that extend the base nushell types with custom functionali

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

| Field | Type | Usage |
| Field | Type | Description |
| ------------------ | ---------- | ----------------------------------------------------------------------------------------- |
| **type** | string | **Must** be `"PluginCustomValue"`. |
| **name** | string | The human-readable name of the custom value emitted by the plugin. |
Expand Down Expand Up @@ -2138,7 +2138,7 @@ Structs are encoded as maps of their fields, without the name of the struct.

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 | Usage |
| Field | Type | Description |
| --------- | ------- | ---------------------------------------------- |
| **start** | integer | The index of the first character referenced. |
| **end** | integer | The index after the last character referenced. |
Expand All @@ -2147,7 +2147,7 @@ Describes a region of code in the engine's memory, used mostly for providing dia

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

| Variant | Usage |
| Variant | Description |
| ------------------------------------------ | ---------------------------------------- |
| [`Empty`](#empty-header-variant) | No values produced; an empty stream. |
| [`Value`](#value-header-variant) | A single value |
Expand Down Expand Up @@ -2190,7 +2190,7 @@ Starts a list stream. Expect [`Data`](#data) messages of the `List` variant with

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

| Field | Type | Usage |
| Field | Type | Description |
| -------- | --------------- | ------------------------------------------------- |
| **id** | integer | The stream identifier |
| **span** | [`Span`](#span) | The source code reference that caused the stream. |
Expand All @@ -2213,7 +2213,7 @@ Example:

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

| Field | Type | Usage |
| Field | Type | Description |
| -------- | ----------------------------------- | ------------------------------------------------- |
| **id** | integer | The stream identifier |
| **span** | [`Span`](#span) | The source code reference that caused the stream. |
Expand Down Expand Up @@ -2250,7 +2250,7 @@ Example:

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

| Field | Type | Usage |
| Field | Type | Description |
| ---------- | --------------------- | -------------------------------------------------------------------------------------------------------------- |
| **msg** | string | The main error message to show at the top of the error. |
| **labels** | `ErrorLabel` array? | Spans and messages to label the error in the source code. |
Expand All @@ -2261,7 +2261,7 @@ A flexible, generic error type, with any number of labeled spans.

Most of the fields are not required - only `msg` must be present. `ErrorLabel` (in the `labels` array) is as follows:

| Field | Type | Usage |
| Field | Type | Description |
| -------- | --------------- | ----------------------------------------------------------- |
| **text** | string | The message for the label. |
| **span** | [`Span`](#span) | The span in the source code that the label should point to. |
Expand Down
20 changes: 10 additions & 10 deletions contributor-book/plugins.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,7 @@ impl SimplePluginCommand for Len {
"len"
}

fn usage(&self) -> &str {
fn description(&self) -> &str {
"calculates the length of its input"
}

Expand Down Expand Up @@ -160,7 +160,7 @@ impl SimplePluginCommand for Len {
"len"
}

fn usage(&self) -> &str {
fn description(&self) -> &str {
"calculates the length of its input"
}

Expand All @@ -173,7 +173,7 @@ impl SimplePluginCommand for Len {
}
```

There are a few methods required for this implementation. We first define the `name` of the command, which is what the user will type at the prompt or in their script to run the command. The `usage` is also required, which is a short documentation string for users to know what the command does, and is displayed along with completions and in `help`. Finally, we define the `signature`, which specifies arguments and types for the command.
There are a few methods required for this implementation. We first define the `name` of the command, which is what the user will type at the prompt or in their script to run the command. The `description` is also required, which is a short documentation string for users to know what the command does, and is displayed along with completions and in `help`. Finally, we define the `signature`, which specifies arguments and types for the command.

We tell Nu that the name is "len", give it a basic description for `help` to display and declare that we expect to be passed a string and will return an integer.

Expand Down Expand Up @@ -432,7 +432,7 @@ impl SimplePluginCommand for Motd {
"motd"
}

fn usage(&self) -> &str {
fn description(&self) -> &str {
"Message of the day"
}

Expand Down Expand Up @@ -505,7 +505,7 @@ impl PluginCommand for MyEach {
"my-each"
}

fn usage(&self) -> &str {
fn description(&self) -> &str {
"Run closure on each element of a list"
}

Expand Down Expand Up @@ -899,7 +899,7 @@ $ ./target/release/nu_plugin_len --stdio
json{"Hello":{"protocol":"nu-plugin","version":"0.90.2","features":[]}}
{"Hello":{"protocol":"nu-plugin","version":"0.90.2","features":[]}}
{"Call":[0,"Signature"]}
{"CallResponse":[0, {"Signature":[{"sig":{"name":"len","usage":"calculates the length of its input","extra_usage":"","search_terms":[],"required_positional":[],"optional_positional":[],"rest_positional":null,"vectorizes_over_list":false,"named":[{"long":"help","short":"h","arg":null,"required":false,"desc":"Display the help message for this command","var_id":null,"default_value":null}],"input_type":"String","output_type":"Int","input_output_types":[],"allow_variants_without_examples":false,"is_filter":false,"creates_scope":false,"allows_unknown_args":false,"category":"Default"},"examples":[]}]}]}
{"CallResponse":[0, {"Signature":[{"sig":{"name":"len","description":"calculates the length of its input","extra_description":"","search_terms":[],"required_positional":[],"optional_positional":[],"rest_positional":null,"vectorizes_over_list":false,"named":[{"long":"help","short":"h","arg":null,"required":false,"desc":"Display the help message for this command","var_id":null,"default_value":null}],"input_type":"String","output_type":"Int","input_output_types":[],"allow_variants_without_examples":false,"is_filter":false,"creates_scope":false,"allows_unknown_args":false,"category":"Default"},"examples":[]}]}]}
```

The plugin prints its signature serialized as JSON. We'll reformat for readability.
Expand All @@ -910,8 +910,8 @@ The plugin prints its signature serialized as JSON. We'll reformat for readabili
{
"sig": {
"name": "len",
"usage": "calculates the length of its input",
"extra_usage": "",
"description": "calculates the length of its input",
"extra_description": "",
"search_terms": [],
"required_positional": [],
"optional_positional": [],
Expand Down Expand Up @@ -1020,8 +1020,8 @@ def signature():
return {
"sig": {
"name": "len",
"usage": "calculates the length of its input",
"extra_usage": "",
"description": "calculates the length of its input",
"extra_description": "",
"search_terms": [],
"required_positional": [],
"optional_positional": [],
Expand Down
Loading