You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: book/dataframes.md
+10-19Lines changed: 10 additions & 19 deletions
Original file line number
Diff line number
Diff line change
@@ -1,21 +1,10 @@
1
1
# Dataframes
2
2
3
-
::: warning
4
-
5
-
To use dataframes you'll need to install [cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html) and then install `nu_plugin_polars` with commands:
6
-
7
-
```nu no-run
8
-
# Install the `polars` nushell plugin
9
-
> cargo install nu_plugin_polars
10
-
11
-
# Add the plugin's commands to your plugin registry file:
12
-
> plugin add ~/.cargo/bin/nu_plugin_polars
13
-
```
14
-
15
-
After installation, you will need to restart the nushell instance. If everything is successful,
16
-
you should be able to see command completions for `polars`. For example, you should be able to execute
17
-
`polars into-df -h`.
3
+
::: warning Important!
4
+
This feature requires the Polars plugin. See the the
5
+
[Plugins Chapter](plugins.md) to learn how to install it.
18
6
7
+
To test that this plugin is properly installed, run `help polars`.
19
8
:::
20
9
21
10
As we have seen so far, Nushell makes working with data its main priority.
@@ -34,10 +23,12 @@ Arrow](https://arrow.apache.org/) specification, and uses
Nu can be extended using plugins. Plugins behave much like Nu's built-in commands, with the added benefit that they can be added separately from Nu itself.
4
4
5
-
Nu plugins are executables; Nu launches them as needed and communicates with them over [stdin and stdout](https://en.wikipedia.org/wiki/Standard_streams) or [local sockets](https://en.wikipedia.org/wiki/Inter-process_communication). Nu plugins can use either [JSON](https://www.json.org/) or [MessagePack](https://msgpack.org/) as their communication encoding.
5
+
::: warning Important
6
+
Plugins communicate with Nushell using the `nu-plugin` protocol. This protocol is versioned, and plugins must use the same `nu-plugin` version provided by Nushell.
6
7
7
-
## Downloading and Installing a Plugin
8
+
When updating Nushell, please make sure to also update any plugins that you have registered.
9
+
:::
8
10
9
-
::: warning
11
+
[[toc]]
12
+
13
+
## Installing Plugins
14
+
15
+
### Core Plugins
10
16
11
-
Please note that plugin installation methods are still under heavy development and that the following workflow will be refined before the release of 1.0. The nupm official package manager should simplify installation in the future when it becomes ready for general use.
17
+
Nushell ships with a set of officially maintained plugins which includes:
12
18
19
+
-`polars`: Extremely fast columnar operations using DataFrames via the [Polars Library](https://github.com/pola-rs/polars). See the [DataFrames Chapter](dataframes.html) for more details.
20
+
-`formats`: Support for several additional data formats - EML, ICS, INI, plist, and VCF.
21
+
-`gstat`: Returns information on the status of a Git repository as Nushell structured data.
22
+
-`query`: Support for querying SQL, XML, JSON, HTML (via selector), and WebPage Metadata
23
+
-`inc`: Increment a value or version (e.g., semver). This plugin acts as both an end-user plugin as well as a simple developer example of how to create a plugin.
24
+
25
+
Nushell also ships with several plugins that serve as examples or tools for plugin developers. These include `nu_plugin_example`, `nu_plugin_custom_values`, and `nu_plugin_stress_internals`.
26
+
27
+
Core plugins are typically distributed with the Nushell release and should already be installed in the same directory as the Nushell executable. If this is the case on your system, core plugins should be using correct `nu-plugin` protocol version. If your package management system installs them separately, please make sure to update the core plugins whenever Nushell itself is updated.
28
+
29
+
::: tip Installing using Cargo
30
+
For example, when installing or upgrading Nushell directly from crates.io using `cargo install nu`, the corresponding core plugins for that version may also be installed or updated using `cargo install nu_plugin_<plugin_name>`.
13
31
:::
14
32
15
-
To install a plugin on your system, you first need to make sure that the plugin uses the same version of Nu as your system.
33
+
### Third-party Plugins
16
34
17
-
```nu
18
-
> version
19
-
```
35
+
You can find third-party plugins on crates.io, online Git repositories, [`awesome-nu`](https://github.com/nushell/awesome-nu/blob/main/plugin_details.md), and other sources. As with any third-party code you run on your system, please make sure you trust its source.
20
36
21
-
Find plugins that have the exact same Nushell version either on crates.io, online git repositories or [`awesome-nu`](https://github.com/nushell/awesome-nu/blob/main/plugin_details.md). You can find which version the plugin uses by checking the Cargo.toml file.
37
+
To install a third-party plugin on your system, you first need to make sure the plugin uses the same version of Nu as your system:
38
+
39
+
- Confirm your Nushell version with the `version` command
40
+
- Confirm the version the plugin requires by checking its `Cargo.toml` file
22
41
23
42
To install a plugin by name from crates.io, run:
24
43
25
44
```nu
26
-
> cargo install plugin_name
45
+
cargo install nu_plugin_<plugin_name>
27
46
```
28
47
29
-
If you chose to download the git repository instead, run this when inside the cloned repository:
48
+
When installing from a repository (e.g., GitHub), run the following from inside the cloned repository:
30
49
31
50
```nu
32
-
> cargo install --path .
51
+
cargo install --path .
33
52
```
34
53
35
54
This will create a binary file that can be used to add the plugin.
36
55
37
-
Keep in mind that when installing using crates.io, the binary can be saved in different locations depending on how your system is set up. A typical location is in the users's home directory under .cargo/bin.
56
+
::: tip Cargo installation location
57
+
By default, binaries installed with `cargo install` are placed in your home directory under `.cargo/bin`.
58
+
However, this can change depending on how your system is configured.
59
+
:::
38
60
39
-
## Adding a Plugin
61
+
## Registering Plugins
40
62
41
63
To add a plugin to the plugin registry file, call the [`plugin add`](/commands/docs/plugin_add.md) command to tell Nu where to find it.
42
64
43
-
Please note that the plugin name needs to start with `nu_plugin_`, Nu uses the name prefix to detect plugins.
65
+
::: tip Note
66
+
The plugin file name must start with `nu_plugin_`, Nu uses this filename prefix to identify plugins.
67
+
:::
44
68
45
-
Linux+macOS:
69
+
-Linux and macOS:
46
70
47
-
```nu
48
-
> plugin add ./my_plugins/nu_plugin_cool
49
-
```
71
+
```nu
72
+
plugin add ./my_plugins/nu_plugin_cool
73
+
```
50
74
51
-
Windows:
75
+
-Windows:
52
76
53
-
```nu
54
-
> plugin add .\my_plugins\nu_plugin_cool.exe
55
-
```
77
+
```nu
78
+
plugin add .\my_plugins\nu_plugin_cool.exe
79
+
```
56
80
57
-
When [`plugin add`](/commands/docs/plugin_add.md) is called, Nu runs the plugin binary and communicates via the [plugin protocol](/contributor-book/plugin_protocol_reference.md) in order to ensure compatibility and to get a list of all of the commands it supports. These are then saved to the plugin registry file (`$nu.plugin-path`) which acts as a cache.
81
+
When [`plugin add`](/commands/docs/plugin_add.md) is called, Nu:
58
82
59
-
Once added, the next time `nu` is started, the plugin should show up in [`plugin list`](/commands/docs/plugin_list.md) with all of its commands are available in scope:
83
+
- Runs the plugin binary
84
+
- Communicates via the [plugin protocol](/contributor-book/plugin_protocol_reference.md) in order to ensure compatibility and to get a list of all of the commands it supports
85
+
- This plugin information is then saved to the plugin registry file (`$nu.plugin-path`), which acts as a cache
60
86
61
-
```nu
62
-
> help commands | where command_type == "plugin"
63
-
```
87
+
Once added to the registry, the next time `nu` is started, the plugin will be available in that session.
64
88
65
-
You can also immediately reload a plugin in the current session by calling `plugin use`:
89
+
You can also immediately reload a plugin in the current session by calling `plugin use`. In this case, the name of the plugin (rather than the filename) is used without the `nu_plugin` prefix:
66
90
67
91
```nu
68
-
> plugin use cool
92
+
plugin use cool
69
93
```
70
94
71
-
It is not necessary to add `plugin use` to your config file. All previously added plugins are automatically loaded at startup.
95
+
It is not necessary to add `plugin use`statements to your config file. All previously added plugins are automatically loaded at startup.
72
96
73
-
Note that `plugin use` is a parser keyword, so when evaluating a script, it will be evaluated first. This means that while you can execute `plugin add` and then `plugin use` at the REPL on separate lines, you can't do this in a single script. If you need to run `nu` with a specific plugin or set of plugins without preparing a cache file, you can pass the `--plugins` option to `nu` with a list of plugin executable files:
97
+
::: tip Note
98
+
`plugin use` is a parser keyword, so when evaluating a script, it will be evaluated first. This means that while you can execute `plugin add` and then `plugin use` at the REPL on separate lines, you can't do this in a single script. If you need to run `nu` with a specific plugin or set of plugins without preparing a cache file, you can pass the `--plugins` option to `nu` with a list of plugin executable files:
74
99
75
100
```nu
76
-
> nu --plugins '[./my_plugins/nu_plugin_cool]'
101
+
nu --plugins '[./my_plugins/nu_plugin_cool]'
77
102
```
78
103
79
-
### Updating a Plugin
104
+
:::
105
+
106
+
### Updating Plugins
80
107
81
108
When updating a plugin, it is important to run `plugin add` again just as above to load the new signatures from the plugin and allow Nu to rewrite them to the plugin file (`$nu.plugin-path`). You can then `plugin use` to get the updated signatures within the current session.
82
109
83
110
## Managing Plugins
84
111
85
-
To view the list of plugins you have installed:
112
+
Installed plugins are displayed using [`plugin list`](/commands/docs/plugin_list.md):
All of the commands from installed plugins are available in the current scope:
137
+
138
+
```nu
139
+
scope commands | where type == "plugin"
140
+
```
141
+
142
+
### Plugin Lifecycle
143
+
108
144
Plugins stay running while they are in use, and are automatically stopped by default after a period of time of inactivity. This behavior is managed by the [plugin garbage collector](#plugin-garbage-collector). To manually stop a plugin, call `plugin stop` with its name:
109
145
146
+
For example, run the `gstat` command from the corresponding plugin, then check its `is_running` status:
147
+
110
148
```nu
111
-
> plugin stop gstat
149
+
gstat
150
+
# => gstat output
151
+
plugin list | where name == gstat | select name is_running
152
+
# =>
153
+
╭───┬───────┬────────────╮
154
+
│ # │ name │ is_running │
155
+
├───┼───────┼────────────┤
156
+
│ 0 │ gstat │ true │
157
+
╰───┴───────┴────────────╯
112
158
```
113
159
114
-
If we check `plugin list` again, we can see that it is no longer running:
160
+
Now stop the plugin manually, and we can see that it is no longer running:
115
161
116
162
```nu
117
-
> plugin list | where name == gstat | select name is_running
163
+
plugin stop gstat
164
+
plugin list | where name == gstat | select name is_running
165
+
# =>
118
166
╭───┬───────┬────────────╮
119
167
│ # │ name │ is_running │
120
168
├───┼───────┼────────────┤
@@ -124,7 +172,7 @@ If we check `plugin list` again, we can see that it is no longer running:
124
172
125
173
### Plugin Garbage Collector
126
174
127
-
Nu comes with a plugin garbage collector, which automatically stops plugins that are not actively in use after a period of time (by default, 10 seconds). This behavior is fully configurable:
175
+
As mentioned above, Nu comes with a plugin garbage collector which automatically stops plugins that are not actively in use after a period of time (by default, 10 seconds). This behavior is fully configurable:
128
176
129
177
```nu
130
178
$env.config.plugin_gc = {
@@ -149,39 +197,47 @@ $env.config.plugin_gc = {
149
197
}
150
198
```
151
199
152
-
For more information on exactly under what circumstances a plugin is considered to be active, see [the relevant section in the contributor book](/contributor-book/plugins.html#plugin-garbage-collection).
200
+
For information on when a plugin is considered to be active, see [the relevant section in the contributor book](/contributor-book/plugins.html#plugin-garbage-collection).
153
201
154
-
## Removing a Plugin
202
+
## Removing Plugins
155
203
156
-
To remove a plugin, call `plugin rm` with the name of the plugin you want to remove. For example, if you previously added the plugin `~/.cargo/bin/nu_plugin_gstat`, its name would be `gstat`. To remove it:
204
+
To remove a plugin, call `plugin rm <plugin_name>`. Note that this is the plugin name, rather than the filename. For example, if you previously added the plugin `~/.cargo/bin/nu_plugin_gstat`, its name would be `gstat`. To remove it:
157
205
158
206
```nu
159
207
plugin rm gstat
160
208
```
161
209
162
-
You can check the name of a plugin by running `plugin list`.
210
+
You can confirm the name of a plugin by running `plugin list`.
163
211
164
-
## Examples
212
+
Running `plugin rm` removes the plugin from the registry so that it will not be loaded the next time Nushell starts. However, any commands created by the plugin remain in scope until the current Nushell session ends.
213
+
214
+
## For Plugin Developers
215
+
216
+
Nu plugins are executables; Nu launches them as needed and communicates with them over [stdin and stdout](https://en.wikipedia.org/wiki/Standard_streams) or [local sockets](https://en.wikipedia.org/wiki/Inter-process_communication). Nu plugins can use either [JSON](https://www.json.org/) or [MessagePack](https://msgpack.org/) as their communication encoding.
217
+
218
+
### Examples
165
219
166
220
Nu's main repo contains example plugins that are useful for learning how the plugin protocol works:
The simplest way to debug a plugin is to print to stderr; plugins' standard error streams are redirected through Nu and displayed to the user.
174
228
175
-
### Tracing
229
+
####Tracing
176
230
177
231
The Nu plugin protocol message stream may be captured for diagnostic purposes using [trace_nu_plugin](https://crates.io/crates/trace_nu_plugin/).
178
232
179
-
**WARNING: trace output will accumulate for as long as the plugin is installed with the trace wrapper. Large files are possible. Be sure to remove the plugin with `plugin rm` when finished tracing, and reinstall without the trace wrapper.**
233
+
::: warning
234
+
Trace output will accumulate for as long as the plugin is installed with the trace wrapper. Large files are possible. Be sure to remove the plugin with `plugin rm` when finished tracing, and reinstall without the trace wrapper.\*\*
235
+
:::
180
236
181
-
## Help
237
+
### Developer Help
182
238
183
239
Nu's plugin documentation is a work in progress. If you're unsure about something, the #plugins channel on [the Nu Discord](https://discord.gg/NtAbbGn) is a great place to ask questions!
184
240
185
-
## More details
241
+
###More details
186
242
187
243
The [plugin chapter in the contributor book](/contributor-book/plugins.md) offers more details on the intricacies of how plugins work from a software developer point of view.
0 commit comments