From 1616acd124433739c2122cce5bc5dd9950b15e2b Mon Sep 17 00:00:00 2001 From: Darren Schroeder <343840+fdncred@users.noreply.github.com> Date: Wed, 26 Feb 2025 09:15:14 -0600 Subject: [PATCH] update `query json` help and examples (#15190) # Description This PR adds extra_description stating what syntax query json is with links. It also adds some examples since query json was written before examples existed for plugins. # User-Facing Changes # Tests + Formatting # After Submitting --- crates/nu_plugin_query/src/query_json.rs | 52 +++++++++++++++++++++++- 1 file changed, 51 insertions(+), 1 deletion(-) diff --git a/crates/nu_plugin_query/src/query_json.rs b/crates/nu_plugin_query/src/query_json.rs index b5f8bd7add3..3e28cb2f42e 100644 --- a/crates/nu_plugin_query/src/query_json.rs +++ b/crates/nu_plugin_query/src/query_json.rs @@ -1,7 +1,9 @@ use crate::Query; use gjson::Value as gjValue; use nu_plugin::{EngineInterface, EvaluatedCall, SimplePluginCommand}; -use nu_protocol::{Category, LabeledError, Record, Signature, Span, Spanned, SyntaxShape, Value}; +use nu_protocol::{ + Category, Example, LabeledError, Record, Signature, Span, Spanned, SyntaxShape, Value, +}; pub struct QueryJson; @@ -16,12 +18,60 @@ impl SimplePluginCommand for QueryJson { "execute json query on json file (open --raw | query json 'query string')" } + fn extra_description(&self) -> &str { + "query json uses the gjson crate https://github.com/tidwall/gjson.rs to query json data. The query syntax is available at https://github.com/tidwall/gjson/blob/master/SYNTAX.md." + } + fn signature(&self) -> Signature { Signature::build(self.name()) .required("query", SyntaxShape::String, "json query") .category(Category::Filters) } + fn examples(&self) -> Vec { + vec![ + Example { + description: "Get a list of children from a json object", + example: r#"'{"children": ["Sara","Alex","Jack"]}' | query json children"#, + result: Some(Value::test_list(vec![ + Value::test_string("Sara"), + Value::test_string("Alex"), + Value::test_string("Jack"), + ])), + }, + Example { + description: "Get a list of first names of the friends from a json object", + example: r#"'{ + "friends": [ + {"first": "Dale", "last": "Murphy", "age": 44, "nets": ["ig", "fb", "tw"]}, + {"first": "Roger", "last": "Craig", "age": 68, "nets": ["fb", "tw"]}, + {"first": "Jane", "last": "Murphy", "age": 47, "nets": ["ig", "tw"]} + ] +}' | query json friends.#.first"#, + result: Some(Value::test_list(vec![ + Value::test_string("Dale"), + Value::test_string("Roger"), + Value::test_string("Jane"), + ])), + }, + Example { + description: "Get the key named last of the name from a json object", + example: r#"'{"name": {"first": "Tom", "last": "Anderson"}}' | query json name.last"#, + result: Some(Value::test_string("Anderson")), + }, + Example { + description: "Get the count of children from a json object", + example: r#"'{"children": ["Sara","Alex","Jack"]}' | query json children.#"#, + result: Some(Value::test_int(3)), + }, + Example { + description: "Get the first child from the children array in reverse the order using the @reverse modifier from a json object", + example: r#"'{"children": ["Sara","Alex","Jack"]}' | query json "children|@reverse|0""#, + result: Some(Value::test_string("Jack")), + }, + ] + } + fn run( &self, _plugin: &Query,