From d054a724d1e41a3d324a47e04f588ee88845b2b4 Mon Sep 17 00:00:00 2001 From: Justin Ma Date: Tue, 22 Feb 2022 23:16:56 +0800 Subject: [PATCH] Add example for enter, shells and view-source, update some docs (#4604) --- .../src/experimental/view_source.rs | 40 ++++++++++++++++++- crates/nu-command/src/shells/enter.rs | 10 ++++- crates/nu-command/src/shells/shells_.rs | 17 +++++++- docs/commands/enter.md | 7 ++++ docs/commands/gstat.md | 1 - docs/commands/inc.md | 1 - docs/commands/query.md | 1 - docs/commands/query_json.md | 1 - docs/commands/query_web.md | 7 ++-- docs/commands/query_xml.md | 1 - docs/commands/shells.md | 12 ++++++ docs/commands/view-source.md | 22 ++++++++++ 12 files changed, 108 insertions(+), 12 deletions(-) diff --git a/crates/nu-command/src/experimental/view_source.rs b/crates/nu-command/src/experimental/view_source.rs index 2226ddf7e4..ef54247ee0 100644 --- a/crates/nu-command/src/experimental/view_source.rs +++ b/crates/nu-command/src/experimental/view_source.rs @@ -2,7 +2,8 @@ use nu_engine::CallExt; use nu_protocol::ast::Call; use nu_protocol::engine::{Command, EngineState, Stack}; use nu_protocol::{ - Category, IntoPipelineData, PipelineData, ShellError, Signature, SyntaxShape, Value, + Category, Example, IntoPipelineData, PipelineData, ShellError, Signature, Span, SyntaxShape, + Value, }; #[derive(Clone)] @@ -99,4 +100,41 @@ impl Command for ViewSource { )), } } + + fn examples(&self) -> Vec { + vec![ + Example { + description: "View the source of a code block", + example: r#"let abc = { echo 'hi' }; view-source $abc"#, + result: Some(Value::String { + val: "{ echo 'hi' }".to_string(), + span: Span::test_data(), + }), + }, + Example { + description: "View the source of a custom command", + example: r#"def hi [] { echo 'Hi!' }; view-source hi"#, + result: Some(Value::String { + val: "{ echo 'Hi!' }".to_string(), + span: Span::test_data(), + }), + }, + Example { + description: "View the source of a custom command, which participates in the caller environment", + example: r#"def-env foo [] { let-env BAR = 'BAZ' }; view-source foo"#, + result: Some(Value::String { + val: "{ let-env BAR = 'BAZ' }".to_string(), + span: Span::test_data(), + }), + }, + Example { + description: "View the source of a module", + example: r#"module mod-foo { export env FOO_ENV { 'BAZ' } }; view-source mod-foo"#, + result: Some(Value::String { + val: " export env FOO_ENV { 'BAZ' }".to_string(), + span: Span::test_data(), + }), + }, + ] + } } diff --git a/crates/nu-command/src/shells/enter.rs b/crates/nu-command/src/shells/enter.rs index 3ec45ce736..b11fc252ce 100644 --- a/crates/nu-command/src/shells/enter.rs +++ b/crates/nu-command/src/shells/enter.rs @@ -1,7 +1,7 @@ use nu_engine::{current_dir, CallExt}; use nu_protocol::ast::Call; use nu_protocol::engine::{Command, EngineState, Stack}; -use nu_protocol::{Category, PipelineData, ShellError, Signature, SyntaxShape, Value}; +use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, SyntaxShape, Value}; /// Source a file for environment variables. #[derive(Clone)] @@ -105,4 +105,12 @@ impl Command for Enter { Ok(PipelineData::new(call.head)) } + + fn examples(&self) -> Vec { + vec![Example { + description: "Enter a new shell at path '../dir-foo'", + example: r#"enter ../dir-foo"#, + result: None, + }] + } } diff --git a/crates/nu-command/src/shells/shells_.rs b/crates/nu-command/src/shells/shells_.rs index b50a500884..0123ba462e 100644 --- a/crates/nu-command/src/shells/shells_.rs +++ b/crates/nu-command/src/shells/shells_.rs @@ -2,7 +2,7 @@ use nu_engine::current_dir; use nu_protocol::ast::Call; use nu_protocol::engine::{Command, EngineState, Stack}; use nu_protocol::{ - Category, IntoInterruptiblePipelineData, PipelineData, ShellError, Signature, Value, + Category, Example, IntoInterruptiblePipelineData, PipelineData, ShellError, Signature, Value, }; /// Source a file for environment variables. @@ -69,4 +69,19 @@ impl Command for Shells { Ok(output.into_pipeline_data(None)) } + + fn examples(&self) -> Vec { + vec![ + Example { + description: "Enter a new shell at parent path '..' and show all opened shells", + example: r#"enter ..; shells"#, + result: None, + }, + Example { + description: "Show currently active shell", + example: r#"shells | where active == $true"#, + result: None, + }, + ] + } } diff --git a/docs/commands/enter.md b/docs/commands/enter.md index 0e29c38241..390d0c24af 100644 --- a/docs/commands/enter.md +++ b/docs/commands/enter.md @@ -13,3 +13,10 @@ Enters a new shell at the given path. ## Parameters - `path`: the path to enter as a new shell + +## Examples + +Enter a new shell at path '../dir-foo' +```shell +> enter ../dir-foo +``` diff --git a/docs/commands/gstat.md b/docs/commands/gstat.md index 30cf48e200..1b0138bf01 100644 --- a/docs/commands/gstat.md +++ b/docs/commands/gstat.md @@ -13,4 +13,3 @@ Get the git status of a repo ## Parameters - `path`: path to repo - diff --git a/docs/commands/inc.md b/docs/commands/inc.md index 7f0f2c4c58..3fb3e25af0 100644 --- a/docs/commands/inc.md +++ b/docs/commands/inc.md @@ -15,4 +15,3 @@ Increment a value or version. Optionally use the column of a table. - `--major`: increment the major version (eg 1.2.1 -> 2.0.0) - `--minor`: increment the minor version (eg 1.2.1 -> 1.3.0) - `--patch`: increment the patch version (eg 1.2.1 -> 1.2.2) - diff --git a/docs/commands/query.md b/docs/commands/query.md index de31af2109..146aea3564 100644 --- a/docs/commands/query.md +++ b/docs/commands/query.md @@ -9,4 +9,3 @@ Show all the query commands ## Signature ```> query ``` - diff --git a/docs/commands/query_json.md b/docs/commands/query_json.md index e4c2b06e14..4667755c3a 100644 --- a/docs/commands/query_json.md +++ b/docs/commands/query_json.md @@ -13,4 +13,3 @@ execute json query on json file (open --raw | query json 'query string') ## Parameters - `query`: json query - diff --git a/docs/commands/query_web.md b/docs/commands/query_web.md index 251b648f6f..72f44f9dee 100644 --- a/docs/commands/query_web.md +++ b/docs/commands/query_web.md @@ -8,13 +8,12 @@ execute selector query on html/web ## Signature -```> query web --query --as_html --attribute --as_table --inspect``` +```> query web --query --as-html --attribute --as-table --inspect``` ## Parameters - `--query {string}`: selector query - - `--as_html`: return the query output as html + - `--as-html`: return the query output as html - `--attribute {string}`: downselect based on the given attribute - - `--as_table {any}`: find table based on column header list + - `--as-table {any}`: find table based on column header list - `--inspect`: run in inspect mode to provide more information for determining column headers - diff --git a/docs/commands/query_xml.md b/docs/commands/query_xml.md index d69648ddc6..06718afc05 100644 --- a/docs/commands/query_xml.md +++ b/docs/commands/query_xml.md @@ -13,4 +13,3 @@ execute xpath query on xml ## Parameters - `query`: xpath query - diff --git a/docs/commands/shells.md b/docs/commands/shells.md index 0cb8b3ea47..2dde1cb22a 100644 --- a/docs/commands/shells.md +++ b/docs/commands/shells.md @@ -9,3 +9,15 @@ Lists all open shells. ## Signature ```> shells ``` + +## Examples + +Enter a new shell at parent path '..' and show all opened shells +```shell +> enter ..; shells +``` + +Show currently active shell +```shell +> shells | where active == $true +``` diff --git a/docs/commands/view-source.md b/docs/commands/view-source.md index 431adbc59e..6a00840b5e 100644 --- a/docs/commands/view-source.md +++ b/docs/commands/view-source.md @@ -13,3 +13,25 @@ View a block, module, or a definition ## Parameters - `item`: name or block to view + +## Examples + +View the source of a code block +```shell +> let abc = { echo 'hi' }; view-source $abc +``` + +View the source of a custom command +```shell +> def hi [] { echo 'Hi!' }; view-source hi +``` + +View the source of a custom command, which participates in the caller environment +```shell +> def-env foo [] { let-env BAR = 'BAZ' }; view-source foo +``` + +View the source of a module +```shell +> module mod-foo { export env FOO_ENV { 'BAZ' } }; view-source mod-foo +```