mirror of
https://github.com/nushell/nushell.git
synced 2024-11-25 01:43:47 +01:00
Move help commands to use more structure in signatures (#9949)
# Description Signatures in `help commands` will now have more structure for params and input/output pairs. Example: Improved params  Improved input/output pairs  # User-Facing Changes This is technically a breaking change if previous code assumed the shape of things in `help commands`. # Tests + Formatting <!-- Don't forget to add tests that cover your changes. Make sure you've run and fixed any issues with these commands: - `cargo fmt --all -- --check` to check standard code formatting (`cargo fmt --all` applies these changes) - `cargo clippy --workspace -- -D warnings -D clippy::unwrap_used -A clippy::needless_collect -A clippy::result_large_err` to check that you're using the standard code style - `cargo test --workspace` to check that all tests pass - `cargo run -- -c "use std testing; testing run-tests --path crates/nu-std"` to run the tests for the standard library > **Note** > from `nushell` you can also use the `toolkit` as follows > ```bash > use toolkit.nu # or use an `env_change` hook to activate it automatically > toolkit check pr > ``` --> # After Submitting <!-- If your PR had any user-facing changes, update [the documentation](https://github.com/nushell/nushell.github.io) after the PR is merged, if necessary. This will help us keep the docs up to date. -->
This commit is contained in:
JT
GitHub
parent
c070e2d6f7
commit
4accc67843
@ -135,7 +135,6 @@ fn build_help_commands(engine_state: &EngineState, span: Span) -> Vec<Value> {
|
||||
let decl = engine_state.get_decl(decl_id);
|
||||
let sig = decl.signature().update_from_command(name, decl.borrow());
|
||||
|
||||
let signatures = sig.to_string().trim_start().replace("\n ", "\n");
|
||||
let key = sig.name;
|
||||
let usage = sig.usage;
|
||||
let search_terms = sig.search_terms;
|
||||
@ -155,15 +154,131 @@ fn build_help_commands(engine_state: &EngineState, span: Span) -> Vec<Value> {
|
||||
cols.push("usage".into());
|
||||
vals.push(Value::String { val: usage, span });
|
||||
|
||||
cols.push("signatures".into());
|
||||
vals.push(Value::String {
|
||||
val: if decl.is_parser_keyword() {
|
||||
"".to_string()
|
||||
} else {
|
||||
signatures
|
||||
},
|
||||
span,
|
||||
});
|
||||
cols.push("params".into());
|
||||
|
||||
// Build table of parameters
|
||||
let param_table = {
|
||||
let mut vals = vec![];
|
||||
|
||||
for required_param in &sig.required_positional {
|
||||
vals.push(Value::Record {
|
||||
cols: vec![
|
||||
"name".to_string(),
|
||||
"type".to_string(),
|
||||
"required".to_string(),
|
||||
"description".to_string(),
|
||||
],
|
||||
vals: vec![
|
||||
Value::string(&required_param.name, span),
|
||||
Value::string(required_param.shape.to_string(), span),
|
||||
Value::bool(true, span),
|
||||
Value::string(&required_param.desc, span),
|
||||
],
|
||||
span,
|
||||
});
|
||||
}
|
||||
|
||||
for optional_param in &sig.optional_positional {
|
||||
vals.push(Value::Record {
|
||||
cols: vec![
|
||||
"name".to_string(),
|
||||
"type".to_string(),
|
||||
"required".to_string(),
|
||||
"description".to_string(),
|
||||
],
|
||||
vals: vec![
|
||||
Value::string(&optional_param.name, span),
|
||||
Value::string(optional_param.shape.to_string(), span),
|
||||
Value::bool(false, span),
|
||||
Value::string(&optional_param.desc, span),
|
||||
],
|
||||
span,
|
||||
});
|
||||
}
|
||||
|
||||
if let Some(rest_positional) = &sig.rest_positional {
|
||||
vals.push(Value::Record {
|
||||
cols: vec![
|
||||
"name".to_string(),
|
||||
"type".to_string(),
|
||||
"required".to_string(),
|
||||
"description".to_string(),
|
||||
],
|
||||
vals: vec![
|
||||
Value::string(format!("...{}", rest_positional.name), span),
|
||||
Value::string(rest_positional.shape.to_string(), span),
|
||||
Value::bool(false, span),
|
||||
Value::string(&rest_positional.desc, span),
|
||||
],
|
||||
span,
|
||||
});
|
||||
}
|
||||
|
||||
for named_param in &sig.named {
|
||||
let name = if let Some(short) = named_param.short {
|
||||
if named_param.long.is_empty() {
|
||||
format!("-{}", short)
|
||||
} else {
|
||||
format!("--{}(-{})", named_param.long, short)
|
||||
}
|
||||
} else {
|
||||
format!("--{}", named_param.long)
|
||||
};
|
||||
|
||||
vals.push(Value::Record {
|
||||
cols: vec![
|
||||
"name".to_string(),
|
||||
"type".to_string(),
|
||||
"required".to_string(),
|
||||
"description".to_string(),
|
||||
],
|
||||
vals: vec![
|
||||
Value::string(name, span),
|
||||
Value::string(
|
||||
if let Some(arg) = &named_param.arg {
|
||||
arg.to_string()
|
||||
} else {
|
||||
"switch".to_string()
|
||||
},
|
||||
span,
|
||||
),
|
||||
Value::bool(named_param.required, span),
|
||||
Value::string(&named_param.desc, span),
|
||||
],
|
||||
span,
|
||||
});
|
||||
}
|
||||
|
||||
Value::List { vals, span }
|
||||
};
|
||||
vals.push(param_table);
|
||||
|
||||
cols.push("input_output".into());
|
||||
|
||||
// Build the signature input/output table
|
||||
let input_output_table = {
|
||||
let mut vals = vec![];
|
||||
|
||||
for (input_type, output_type) in sig.input_output_types {
|
||||
vals.push(Value::Record {
|
||||
cols: vec!["input".to_string(), "output".to_string()],
|
||||
vals: vec![
|
||||
Value::String {
|
||||
val: input_type.to_string(),
|
||||
span,
|
||||
},
|
||||
Value::String {
|
||||
val: output_type.to_string(),
|
||||
span,
|
||||
},
|
||||
],
|
||||
span,
|
||||
});
|
||||
}
|
||||
|
||||
Value::List { vals, span }
|
||||
};
|
||||
vals.push(input_output_table);
|
||||
|
||||
cols.push("search_terms".into());
|
||||
vals.push(Value::String {
|
||||
|
||||
@ -12,12 +12,6 @@ pub struct PluginSignature {
|
||||
pub examples: Vec<PluginExample>,
|
||||
}
|
||||
|
||||
impl std::fmt::Display for PluginSignature {
|
||||
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
|
||||
write!(f, "{}", self.sig)
|
||||
}
|
||||
}
|
||||
|
||||
impl PluginSignature {
|
||||
pub fn new(sig: Signature, examples: Vec<PluginExample>) -> Self {
|
||||
Self { sig, examples }
|
||||
|
||||
@ -124,72 +124,6 @@ pub struct Signature {
|
||||
pub category: Category,
|
||||
}
|
||||
|
||||
/// Format argument type for user readable output.
|
||||
///
|
||||
/// In general:
|
||||
/// if argument type is a simple type(like string), we'll wrapped with `<>`, the result will be `<string>`
|
||||
/// if argument type is already contains `<>`, like `list<any>`, the result will be `list<any>`.
|
||||
fn fmt_type(arg_type: &Type, optional: bool) -> String {
|
||||
let arg_type = arg_type.to_string();
|
||||
if arg_type.contains('<') && arg_type.contains('>') {
|
||||
if optional {
|
||||
format!("{arg_type}?")
|
||||
} else {
|
||||
arg_type
|
||||
}
|
||||
} else if optional {
|
||||
format!("<{arg_type}?>")
|
||||
} else {
|
||||
format!("<{arg_type}>")
|
||||
}
|
||||
}
|
||||
|
||||
// in general, a commands signature should looks like this:
|
||||
//
|
||||
// <string> | <string>, <int?> => string
|
||||
//
|
||||
// More detail explanation:
|
||||
// the first one is the input from previous command, aka, pipeline input
|
||||
// then followed by `|`, then positional arguments type
|
||||
// then optional arguments type, which ends with `?`
|
||||
// Then followed by `->`
|
||||
// Finally output type.
|
||||
//
|
||||
// If a command contains multiple input/output types, separate them in different lines.
|
||||
impl std::fmt::Display for Signature {
|
||||
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
|
||||
let mut args = self
|
||||
.required_positional
|
||||
.iter()
|
||||
.map(|p| fmt_type(&p.shape.to_type(), false))
|
||||
.collect::<Vec<String>>();
|
||||
args.append(
|
||||
&mut self
|
||||
.optional_positional
|
||||
.iter()
|
||||
.map(|p| fmt_type(&p.shape.to_type(), true))
|
||||
.collect::<Vec<String>>(),
|
||||
);
|
||||
let args = args.join(", ");
|
||||
|
||||
let mut signatures = vec![];
|
||||
for (input_type, output_type) in self.input_output_types.iter() {
|
||||
// ident with two spaces for user friendly output.
|
||||
let input_type = fmt_type(input_type, false);
|
||||
let output_type = fmt_type(output_type, false);
|
||||
if args.is_empty() {
|
||||
signatures.push(format!(" {input_type} | {} -> {output_type}", self.name))
|
||||
} else {
|
||||
signatures.push(format!(
|
||||
" {input_type} | {} {args} -> {output_type}",
|
||||
self.name
|
||||
))
|
||||
}
|
||||
}
|
||||
write!(f, "{}", signatures.join("\n"))
|
||||
}
|
||||
}
|
||||
|
||||
impl PartialEq for Signature {
|
||||
fn eq(&self, other: &Self) -> bool {
|
||||
self.name == other.name
|
||||
|
||||
Loading…
Reference in New Issue
Block a user