add section about the nuon crate for 0.93.0
#1371
Conversation
should be a shell, not TOML
| @@ -80,6 +80,91 @@ Thanks to all the contributors below for helping us making the documentation of | |||
| | ------------------------------------ | ----------- | ------------------------------------------------------- | | |||
| | [@author](https://github.com/author) | ... | [#12345](https://github.com/nushell/nushell/pull/12345) | | |||
|
|
|||
| ## A new crate: `nuon` | |||
| NUON is the NUshell Object Notation, a superset of JSON that allows to store any kind of data. | |||
There was a problem hiding this comment.
"store any kind of data" seems like an overstatement because there are several nushell data types that nuon cannot represent already. Maybe I'm just stuck in the details?
There was a problem hiding this comment.
closures are not really data, right? that's the reason why they can't be serialized to NUON afaik
are there other types of data that can't be converted to NUON that i'm not thinking of? 😊
There was a problem hiding this comment.
From looking at to.rs in nuon, these are the nushell Values that cannot be converted to nuon.
ClosureCellPathCustomError
As far as closures are concerned, I'm not sure why they couldn't be represented as strings like {|| do something}. Also, cell-paths could be $.whatever.the.path maybe. We just have to be able to use from nuon in them if we did that.
There was a problem hiding this comment.
yeah, i share the same feeling, cell paths should be possible to serialize to NUON and some closures, probably the ones that don't capture any outer scope, too 😋
There was a problem hiding this comment.
Ok, so that was my point, that it can't serialize any kind of data. That's all.
| ### an example | ||
| in the rest of this section, we will build a very simple Rust binary application to show how this | ||
| new `nuon` crate works :) | ||
|
|
||
| first, let's define some dependencies | ||
| ```nushell | ||
| cargo add clap --features derive | ||
| cargo add nuon | ||
| ``` | ||
|
|
||
| then, we'll use Clap to have a simple and better CLI interface | ||
| ```rust | ||
| use clap::{Parser, ValueEnum}; | ||
|
|
||
| #[derive(ValueEnum, Clone)] | ||
| enum Style { | ||
| Raw, | ||
| Spaces, | ||
| Tabs, | ||
| } | ||
|
|
||
| #[derive(Parser)] | ||
| #[command(version, about, long_about = None)] | ||
| struct Cli { | ||
| /// the input raw NUON value to play with | ||
| value: String, | ||
|
|
||
| #[arg(short, long)] | ||
| /// the style to dump the value back to raw NUON | ||
| style: Option<Style>, | ||
| } | ||
| ``` | ||
| and, in the `main`, we can parse the CLI arguments | ||
| ```rust | ||
| let cli = Cli::parse(); | ||
| let style = match cli.style { | ||
| Some(Style::Raw) | None => nuon::ToStyle::Raw, | ||
| Some(Style::Spaces) => nuon::ToStyle::Spaces(4), | ||
| Some(Style::Tabs) => nuon::ToStyle::Tabs(1), | ||
| }; | ||
| let input = cli.value; | ||
| ``` | ||
|
|
||
| ```rust | ||
| fn main() { | ||
| // CLI parsing defined above | ||
|
|
||
| // convert the raw NUON input to a Nushell value | ||
| let value = match nuon::from_nuon(&input, None) { | ||
| Ok(v) => v, | ||
| Err(e) => { | ||
| // ... unless the input is not valid NUON and thus cannot be parsed | ||
| eprintln!("{}", e); | ||
| return; | ||
| } | ||
| }; | ||
|
|
||
| // convert the Nushell value back to NUON, using the style provided as argument | ||
| let output = nuon::to_nuon(&value, style, None).unwrap() | ||
|
|
||
| // give some output to see what's happening | ||
| println!("* input:\n{}", input); | ||
| println!(""); | ||
| println!("* Nushell value:\n{:?}", value); | ||
| println!(""); | ||
| println!("* NUON output:\n{}", ); | ||
| } | ||
| ``` | ||
|
|
There was a problem hiding this comment.
No offense to the effort you put into this, but I think including this whole example in the release notes is a poor use of the attention span of our readers. The general audience will be users of Nushell.
From the crate in its current form only plugin developers using Rust can truly benefit as the interface is tied to the nu_protocol specific Value and not a generalized Rust type. And for those I think pointing to the crate documentation is more than enough as they had to contend with Value already. Making sure that you can find good examples and clarifications around the edge-cases of the NUON format there helps them more than a whole contrived demo app including clap in the release notes.
I think mentioning the scope of the crate and pointing to docs.rs/nuon should be fine here.
There was a problem hiding this comment.
that section can be removed, the most important is said just before anyways 😉
the full Rust example is