Plugin json (#474)

* json encoder

* thread to pass messages

* description for example

crates/nu_plugin_example/src/main.rs

@@ -1,6 +1,30 @@
-use nu_plugin::serve_plugin;
+use nu_plugin::{serve_plugin, CapnpSerializer};
 use nu_plugin_example::Example;
 
 fn main() {
-    serve_plugin(&mut Example {})
+    // When defining your plugin, you can select the Serializer that could be
+    // used to encode and decode the messages. The available options are
+    // CapnpSerializer and JsonSerializer. Both are defined in the serializer
+    // folder in nu-plugin.
+    serve_plugin(&mut Example {}, CapnpSerializer {})
+
+    // Note
+    // When creating plugins in other languages one needs to consider how a plugin
+    // is added and used in nushell.
+    // The steps are:
+    // - The plugin is register. In this stage nushell calls the binary file of
+    //      the plugin sending information using the encoded PluginCall::Signature object.
+    //      Use this encoded data in your plugin to design the logic that will return
+    //      the encoded signatures.
+    //      Nushell is expecting and encoded PluginResponse::Signature with all the
+    //      plugin signatures
+    // - When calling the plugin, nushell sends to the binary file the encoded
+    //      PluginCall::CallInfo which has all the call information, such as the
+    //      values of the arguments, the name of the signature called and the input
+    //      from the pipeline.
+    //      Use this data to design your plugin login and to create the value that
+    //      will be sent to nushell
+    //      Nushell expects an encoded PluginResponse::Value from the plugin
+    // - If an error needs to be sent back to nushell, one can encode PluginResponse::Error.
+    //      This is a labeled error that nushell can format for pretty printing
 }

crates/nu_plugin_example/src/nu/mod.rs

@@ -8,7 +8,7 @@ impl Plugin for Example {
         // Each signature will be converted to a command declaration once the
         // plugin is registered to nushell
         vec![
-            Signature::build("test-1")
+            Signature::build("nu-example-1")
                 .desc("Signature test 1 for plugin. Returns Value::Nothing")
                 .required("a", SyntaxShape::Int, "required integer value")
                 .required("b", SyntaxShape::String, "required string value")
@@ -17,7 +17,7 @@ impl Plugin for Example {
                 .named("named", SyntaxShape::String, "named string", Some('n'))
                 .rest("rest", SyntaxShape::String, "rest value string")
                 .category(Category::Experimental),
-            Signature::build("test-2")
+            Signature::build("nu-example-2")
                 .desc("Signature test 2 for plugin. Returns list of records")
                 .required("a", SyntaxShape::Int, "required integer value")
                 .required("b", SyntaxShape::String, "required string value")
@@ -26,7 +26,7 @@ impl Plugin for Example {
                 .named("named", SyntaxShape::String, "named string", Some('n'))
                 .rest("rest", SyntaxShape::String, "rest value string")
                 .category(Category::Experimental),
-            Signature::build("test-3")
+            Signature::build("nu-example-3")
                 .desc("Signature test 3 for plugin. Returns labeled error")
                 .required("a", SyntaxShape::Int, "required integer value")
                 .required("b", SyntaxShape::String, "required string value")
@@ -46,12 +46,12 @@ impl Plugin for Example {
     ) -> Result<Value, LabeledError> {
         // You can use the name to identify what plugin signature was called
         match name {
-            "test-1" => self.test1(call, input),
-            "test-2" => self.test2(call, input),
-            "test-3" => self.test3(call, input),
+            "nu-example-1" => self.test1(call, input),
+            "nu-example-2" => self.test2(call, input),
+            "nu-example-3" => self.test3(call, input),
             _ => Err(LabeledError {
                 label: "Plugin call with wrong name signature".into(),
-                msg: "using the wrong signature".into(),
+                msg: "the signature used to call the plugin does not match any name in the plugin signature vector".into(),
                 span: Some(call.head),
             }),
         }