extern/nushell
1
0
Fork 1
mirror of https://github.com/nushell/nushell.git synced 2024-12-22 23:23:12 +01:00
Code Issues Packages Projects Releases Wiki Activity

Rework help generation internals (#13531)

Browse Source 
Reworking some of the sprawling code we use to generate the `help cmd`
or `cmd --help` output.

This touches mainly the rendering and not the gathering of the necessary
data (see open bugs under
[label:help-system](https://github.com/nushell/nushell/issues?q=sort%3Aupdated-desc+is%3Aopen+label%3Ahelp-system))

Fixes #9076 
Fixes the syntax shape output on flags to be consistent.

## Example
```nushell
def test [
  positional: int,
  documented: float, # this has documentation
  default = 50,
  optional?,
  --a = "bla",
  --bla (-b) = "bla", # named with default
] {}
```

### before

![grafik](https://github.com/user-attachments/assets/1867984f-1289-4ad0-bdf5-c49ec56dfddb)


### after


![grafik](https://github.com/user-attachments/assets/8fca526f-d878-4d52-b970-fc41c7e8859c)
This commit is contained in:
Stefan Holderbach 2024-08-05 22:44:24 +02:00 committed by GitHub
parent 1c37f4b958
commit 9172b22985
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 244 additions and 304 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
crates/nu-cli/src/menus/help_completions.rs
View File

@ -1,4 +1,4 @@
use nu_engine::documentation::get_flags_section;
use nu_engine::documentation::{get_flags_section, HelpStyle};
use nu_protocol::{engine::EngineState, levenshtein_distance, Config};
use nu_utils::IgnoreCaseExt;
use reedline::{Completer, Suggestion};
@ -20,6 +20,9 @@ impl NuHelpCompleter {
fn completion_helper(&self, line: &str, pos: usize) -> Vec<Suggestion> {
let folded_line = line.to_folded_case();
let mut help_style = HelpStyle::default();
help_style.update_from_config(&self.engine_state, &self.config);
let mut commands = self
.engine_state
.get_decls_sorted(false)
@ -60,12 +63,9 @@ impl NuHelpCompleter {
let _ = write!(long_desc, "Usage:\r\n > {}\r\n", sig.call_signature());
if !sig.named.is_empty() {
long_desc.push_str(&get_flags_section(
Some(&self.engine_state),
Some(&self.config),
&sig,
|v| v.to_parsable_string(", ", &self.config),
))
long_desc.push_str(&get_flags_section(&sig, &help_style, |v| {
v.to_parsable_string(", ", &self.config)
}))
}
if !sig.required_positional.is_empty()

529
crates/nu-engine/src/documentation.rs
View File

@ -3,25 +3,28 @@ use nu_protocol::{
ast::{Argument, Call, Expr, Expression, RecordItem},
debugger::WithoutDebug,
engine::{Command, EngineState, Stack, UNKNOWN_SPAN_ID},
record, Category, Config, Example, IntoPipelineData, PipelineData, Signature, Span, SpanId,
Spanned, SyntaxShape, Type, Value,
record, Category, Config, Example, IntoPipelineData, PipelineData, PositionalArg, Signature,
Span, SpanId, Spanned, SyntaxShape, Type, Value,
};
use std::{collections::HashMap, fmt::Write};
use terminal_size::{Height, Width};
/// ANSI style reset
const RESET: &str = "\x1b[0m";
/// ANSI set default color (as set in the terminal)
const DEFAULT_COLOR: &str = "\x1b[39m";
pub fn get_full_help(
command: &dyn Command,
engine_state: &EngineState,
stack: &mut Stack,
) -> String {
let config = stack.get_config(engine_state);
let doc_config = DocumentationConfig {
no_subcommands: false,
no_color: !config.use_ansi_coloring,
brief: false,
};
// Precautionary step to capture any command output generated during this operation. We
// internally call several commands (`table`, `ansi`, `nu-highlight`) and get their
// `PipelineData` using this `Stack`, any other output should not be redirected like the main
// execution.
let stack = &mut stack.start_capture();
let signature = command.signature().update_from_command(command);
get_documentation(
@ -29,19 +32,11 @@ pub fn get_full_help(
&command.examples(),
engine_state,
stack,
&doc_config,
command.is_keyword(),
)
}
#[derive(Default)]
struct DocumentationConfig {
no_subcommands: bool,
no_color: bool,
brief: bool,
}
// Utility returns nu-highlighted string
/// Syntax highlight code using the `nu-highlight` command if available
fn nu_highlight_string(code_string: &str, engine_state: &EngineState, stack: &mut Stack) -> String {
if let Some(highlighter) = engine_state.find_decl(b"nu-highlight", &[]) {
let decl = engine_state.get_decl(highlighter);
@ -68,35 +63,15 @@ fn get_documentation(
examples: &[Example],
engine_state: &EngineState,
stack: &mut Stack,
config: &DocumentationConfig,
is_parser_keyword: bool,
) -> String {
let nu_config = stack.get_config(engine_state);
// Create ansi colors
//todo make these configurable -- pull from enginestate.config
let help_section_name: String = get_ansi_color_for_component_or_default(
engine_state,
&nu_config,
"shape_string",
"\x1b[32m",
); // default: green
let help_subcolor_one: String = get_ansi_color_for_component_or_default(
engine_state,
&nu_config,
"shape_external",
"\x1b[36m",
); // default: cyan
// was const bb: &str = "\x1b[1;34m"; // bold blue
let help_subcolor_two: String = get_ansi_color_for_component_or_default(
engine_state,
&nu_config,
"shape_block",
"\x1b[94m",
); // default: light blue (nobold, should be bolding the *names*)
const RESET: &str = "\x1b[0m"; // reset
let mut help_style = HelpStyle::default();
help_style.update_from_config(engine_state, &nu_config);
let help_section_name = &help_style.section_name;
let help_subcolor_one = &help_style.subcolor_one;
let cmd_name = &sig.name;
let mut long_desc = String::new();
@ -107,44 +82,46 @@ fn get_documentation(
long_desc.push_str("\n\n");
}
let extra_usage = if config.brief { "" } else { &sig.extra_usage };
let extra_usage = &sig.extra_usage;
if !extra_usage.is_empty() {
long_desc.push_str(extra_usage);
long_desc.push_str("\n\n");
}
let mut subcommands = vec![];
if !config.no_subcommands {
let signatures = engine_state.get_signatures(true);
for sig in signatures {
if sig.name.starts_with(&format!("{cmd_name} "))
// Don't display removed/deprecated commands in the Subcommands list
&& !matches!(sig.category, Category::Removed)
{
subcommands.push(format!(
" {help_subcolor_one}{}{RESET} - {}",
sig.name, sig.usage
));
}
}
}
if !sig.search_terms.is_empty() {
let text = format!(
"{help_section_name}Search terms{RESET}: {help_subcolor_one}{}{}\n\n",
let _ = write!(
long_desc,
"{help_section_name}Search terms{RESET}: {help_subcolor_one}{}{RESET}\n\n",
sig.search_terms.join(", "),
RESET
);
let _ = write!(long_desc, "{text}");
}
let text = format!(
"{}Usage{}:\n > {}\n",
help_section_name,
RESET,
let _ = write!(
long_desc,
"{help_section_name}Usage{RESET}:\n > {}\n",
sig.call_signature()
);
let _ = write!(long_desc, "{text}");
// TODO: improve the subcommand name resolution
// issues:
// - Aliases are included
// - https://github.com/nushell/nushell/issues/11657
// - Subcommands are included violating module scoping
// - https://github.com/nushell/nushell/issues/11447
// - https://github.com/nushell/nushell/issues/11625
let mut subcommands = vec![];
let signatures = engine_state.get_signatures(true);
for sig in signatures {
// Don't display removed/deprecated commands in the Subcommands list
if sig.name.starts_with(&format!("{cmd_name} "))
&& !matches!(sig.category, Category::Removed)
{
subcommands.push(format!(
" {help_subcolor_one}{}{RESET} - {}",
sig.name, sig.usage
));
}
}
if !subcommands.is_empty() {
let _ = write!(long_desc, "\n{help_section_name}Subcommands{RESET}:\n");
@ -154,12 +131,9 @@ fn get_documentation(
}
if !sig.named.is_empty() {
long_desc.push_str(&get_flags_section(
Some(engine_state),
Some(&nu_config),
sig,
|v| nu_highlight_string(&v.to_parsable_string(", ", &nu_config), engine_state, stack),
))
long_desc.push_str(&get_flags_section(sig, &help_style, |v| {
nu_highlight_string(&v.to_parsable_string(", ", &nu_config), engine_state, stack)
}))
}
if !sig.required_positional.is_empty()
@ -168,70 +142,38 @@ fn get_documentation(
{
let _ = write!(long_desc, "\n{help_section_name}Parameters{RESET}:\n");
for positional in &sig.required_positional {
let text = match &positional.shape {
SyntaxShape::Keyword(kw, shape) => {
format!(
" {help_subcolor_one}\"{}\" + {RESET}<{help_subcolor_two}{}{RESET}>: {}",
String::from_utf8_lossy(kw),
document_shape(*shape.clone()),
positional.desc
)
}
_ => {
format!(
" {help_subcolor_one}{}{RESET} <{help_subcolor_two}{}{RESET}>: {}",
positional.name,
document_shape(positional.shape.clone()),
positional.desc
)
}
};
let _ = writeln!(long_desc, "{text}");
write_positional(
&mut long_desc,
positional,
PositionalKind::Required,
&help_style,
&nu_config,
engine_state,
stack,
);
}
for positional in &sig.optional_positional {
let text = match &positional.shape {
SyntaxShape::Keyword(kw, shape) => {
format!(
" {help_subcolor_one}\"{}\" + {RESET}<{help_subcolor_two}{}{RESET}>: {} (optional)",
String::from_utf8_lossy(kw),
document_shape(*shape.clone()),
positional.desc
)
}
_ => {
let opt_suffix = if let Some(value) = &positional.default_value {
format!(
" (optional, default: {})",
nu_highlight_string(
&value.to_parsable_string(", ", &nu_config),
engine_state,
stack
)
)
} else {
(" (optional)").to_string()
};
format!(
" {help_subcolor_one}{}{RESET} <{help_subcolor_two}{}{RESET}>: {}{}",
positional.name,
document_shape(positional.shape.clone()),
positional.desc,
opt_suffix,
)
}
};
let _ = writeln!(long_desc, "{text}");
write_positional(
&mut long_desc,
positional,
PositionalKind::Optional,
&help_style,
&nu_config,
engine_state,
stack,
);
}
if let Some(rest_positional) = &sig.rest_positional {
let text = format!(
" ...{help_subcolor_one}{}{RESET} <{help_subcolor_two}{}{RESET}>: {}",
rest_positional.name,
document_shape(rest_positional.shape.clone()),
rest_positional.desc
write_positional(
&mut long_desc,
rest_positional,
PositionalKind::Rest,
&help_style,
&nu_config,
engine_state,
stack,
);
let _ = writeln!(long_desc, "{text}");
}
}
@ -300,36 +242,12 @@ fn get_documentation(
long_desc.push_str(" ");
long_desc.push_str(example.description);
if config.no_color {
if !nu_config.use_ansi_coloring {
let _ = write!(long_desc, "\n > {}\n", example.example);
} else if let Some(highlighter) = engine_state.find_decl(b"nu-highlight", &[]) {
let decl = engine_state.get_decl(highlighter);
let call = Call::new(Span::unknown());
match decl.run(
engine_state,
stack,
&(&call).into(),
Value::string(example.example, Span::unknown()).into_pipeline_data(),
) {
Ok(output) => {
let result = output.into_value(Span::unknown());
match result.and_then(Value::coerce_into_string) {
Ok(s) => {
let _ = write!(long_desc, "\n > {s}\n");
}
_ => {
let _ = write!(long_desc, "\n > {}\n", example.example);
}
}
}
Err(_) => {
let _ = write!(long_desc, "\n > {}\n", example.example);
}
}
} else {
let _ = write!(long_desc, "\n > {}\n", example.example);
}
let code_string = nu_highlight_string(example.example, engine_state, stack);
let _ = write!(long_desc, "\n > {code_string}\n");
};
if let Some(result) = &example.result {
let mut table_call = Call::new(Span::unknown());
@ -395,19 +313,19 @@ fn get_documentation(
long_desc.push('\n');
if config.no_color {
if !nu_config.use_ansi_coloring {
nu_utils::strip_ansi_string_likely(long_desc)
} else {
long_desc
}
}
fn get_ansi_color_for_component_or_default(
fn update_ansi_from_config(
ansi_code: &mut String,
engine_state: &EngineState,
nu_config: &Config,
theme_component: &str,
default: &str,
) -> String {
) {
if let Some(color) = &nu_config.color_config.get(theme_component) {
let caller_stack = &mut Stack::new().capture();
let span = Span::unknown();
@ -430,14 +348,12 @@ fn get_ansi_color_for_component_or_default(
PipelineData::Empty,
) {
if let Ok((str, ..)) = result.collect_string_strict(span) {
return str;
*ansi_code = str;
}
}
}
}
}
default.to_string()
}
fn get_argument_for_color_value(
@ -491,151 +407,174 @@ fn get_argument_for_color_value(
}
}
// document shape helps showing more useful information
pub fn document_shape(shape: SyntaxShape) -> SyntaxShape {
/// Contains the settings for ANSI colors in help output
///
/// By default contains a fixed set of (4-bit) colors
///
/// Can reflect configuration using [`HelpStyle::update_from_config`]
pub struct HelpStyle {
section_name: String,
subcolor_one: String,
subcolor_two: String,
}
impl Default for HelpStyle {
fn default() -> Self {
HelpStyle {
// default: green
section_name: "\x1b[32m".to_string(),
// default: cyan
subcolor_one: "\x1b[36m".to_string(),
// default: light blue
subcolor_two: "\x1b[94m".to_string(),
}
}
}
impl HelpStyle {
/// Pull colors from the [`Config`]
///
/// Uses some arbitrary `shape_*` settings, assuming they are well visible in the terminal theme.
///
/// Implementation detail: currently executes `ansi` command internally thus requiring the
/// [`EngineState`] for execution.
/// See <https://github.com/nushell/nushell/pull/10623> for details
pub fn update_from_config(&mut self, engine_state: &EngineState, nu_config: &Config) {
update_ansi_from_config(
&mut self.section_name,
engine_state,
nu_config,
"shape_string",
);
update_ansi_from_config(
&mut self.subcolor_one,
engine_state,
nu_config,
"shape_external",
);
update_ansi_from_config(
&mut self.subcolor_two,
engine_state,
nu_config,
"shape_block",
);
}
}
/// Make syntax shape presentable by stripping custom completer info
fn document_shape(shape: &SyntaxShape) -> &SyntaxShape {
match shape {
SyntaxShape::CompleterWrapper(inner_shape, _) => *inner_shape,
SyntaxShape::CompleterWrapper(inner_shape, _) => inner_shape,
_ => shape,
}
}
#[derive(PartialEq)]
enum PositionalKind {
Required,
Optional,
Rest,
}
fn write_positional(
long_desc: &mut String,
positional: &PositionalArg,
arg_kind: PositionalKind,
help_style: &HelpStyle,
nu_config: &Config,
engine_state: &EngineState,
stack: &mut Stack,
) {
let help_subcolor_one = &help_style.subcolor_one;
let help_subcolor_two = &help_style.subcolor_two;
// Indentation
long_desc.push_str(" ");
if arg_kind == PositionalKind::Rest {
long_desc.push_str("...");
}
match &positional.shape {
SyntaxShape::Keyword(kw, shape) => {
let _ = write!(
long_desc,
"{help_subcolor_one}\"{}\" + {RESET}<{help_subcolor_two}{}{RESET}>",
String::from_utf8_lossy(kw),
document_shape(shape),
);
}
_ => {
let _ = write!(
long_desc,
"{help_subcolor_one}{}{RESET} <{help_subcolor_two}{}{RESET}>",
positional.name,
document_shape(&positional.shape),
);
}
};
if !positional.desc.is_empty() || arg_kind == PositionalKind::Optional {
let _ = write!(long_desc, ": {}", positional.desc);
}
if arg_kind == PositionalKind::Optional {
if let Some(value) = &positional.default_value {
let _ = write!(
long_desc,
" (optional, default: {})",
nu_highlight_string(
&value.to_parsable_string(", ", nu_config),
engine_state,
stack
)
);
} else {
long_desc.push_str(" (optional)");
};
}
long_desc.push('\n');
}
pub fn get_flags_section<F>(
engine_state_opt: Option<&EngineState>,
nu_config_opt: Option<&Config>,
signature: &Signature,
help_style: &HelpStyle,
mut value_formatter: F, // format default Value (because some calls cant access config or nu-highlight)
) -> String
where
F: FnMut(&nu_protocol::Value) -> String,
{
//todo make these configurable -- pull from enginestate.config
let help_section_name: String;
let help_subcolor_one: String;
let help_subcolor_two: String;
// Sometimes we want to get the flags without engine_state
// For example, in nu-plugin. In that case, we fall back on default values
if let Some(engine_state) = engine_state_opt {
let nu_config = nu_config_opt.unwrap_or_else(|| engine_state.get_config());
help_section_name = get_ansi_color_for_component_or_default(
engine_state,
nu_config,
"shape_string",
"\x1b[32m",
); // default: green
help_subcolor_one = get_ansi_color_for_component_or_default(
engine_state,
nu_config,
"shape_external",
"\x1b[36m",
); // default: cyan
// was const bb: &str = "\x1b[1;34m"; // bold blue
help_subcolor_two = get_ansi_color_for_component_or_default(
engine_state,
nu_config,
"shape_block",
"\x1b[94m",
);
// default: light blue (nobold, should be bolding the *names*)
} else {
help_section_name = "\x1b[32m".to_string();
help_subcolor_one = "\x1b[36m".to_string();
help_subcolor_two = "\x1b[94m".to_string();
}
const RESET: &str = "\x1b[0m"; // reset
const D: &str = "\x1b[39m"; // default
let help_section_name = &help_style.section_name;
let help_subcolor_one = &help_style.subcolor_one;
let help_subcolor_two = &help_style.subcolor_two;
let mut long_desc = String::new();
let _ = write!(long_desc, "\n{help_section_name}Flags{RESET}:\n");
for flag in &signature.named {
let default_str = if let Some(value) = &flag.default_value {
format!(
" (default: {help_subcolor_two}{}{RESET})",
&value_formatter(value)
)
} else {
"".to_string()
};
let msg = if let Some(arg) = &flag.arg {
if let Some(short) = flag.short {
if flag.required {
format!(
" {help_subcolor_one}-{}{}{RESET} (required parameter) {:?} - {}{}\n",
short,
if !flag.long.is_empty() {
format!("{D},{RESET} {help_subcolor_one}--{}", flag.long)
} else {
"".into()
},
arg,
flag.desc,
default_str,
)
} else {
format!(
" {help_subcolor_one}-{}{}{RESET} <{help_subcolor_two}{:?}{RESET}> - {}{}\n",
short,
if !flag.long.is_empty() {
format!("{D},{RESET} {help_subcolor_one}--{}", flag.long)
} else {
"".into()
},
arg,
flag.desc,
default_str,
)
}
} else if flag.required {
format!(
" {help_subcolor_one}--{}{RESET} (required parameter) <{help_subcolor_two}{:?}{RESET}> - {}{}\n",
flag.long, arg, flag.desc, default_str,
)
} else {
format!(
" {help_subcolor_one}--{}{RESET} <{help_subcolor_two}{:?}{RESET}> - {}{}\n",
flag.long, arg, flag.desc, default_str,
)
// Indentation
long_desc.push_str(" ");
// Short flag shown before long flag
if let Some(short) = flag.short {
let _ = write!(long_desc, "{help_subcolor_one}-{}{RESET}", short);
if !flag.long.is_empty() {
let _ = write!(long_desc, "{DEFAULT_COLOR},{RESET} ");
}
} else if let Some(short) = flag.short {
if flag.required {
format!(
" {help_subcolor_one}-{}{}{RESET} (required parameter) - {}{}\n",
short,
if !flag.long.is_empty() {
format!("{D},{RESET} {help_subcolor_one}--{}", flag.long)
} else {
"".into()
},
flag.desc,
default_str,
)
} else {
format!(
" {help_subcolor_one}-{}{}{RESET} - {}{}\n",
short,
if !flag.long.is_empty() {
format!("{D},{RESET} {help_subcolor_one}--{}", flag.long)
} else {
"".into()
},
flag.desc,
default_str
)
}
} else if flag.required {
format!(
" {help_subcolor_one}--{}{RESET} (required parameter) - {}{}\n",
flag.long, flag.desc, default_str,
)
} else {
format!(
" {help_subcolor_one}--{}{RESET} - {}\n",
flag.long, flag.desc
)
};
long_desc.push_str(&msg);
}
if !flag.long.is_empty() {
let _ = write!(long_desc, "{help_subcolor_one}--{}{RESET}", flag.long);
}
if flag.required {
long_desc.push_str(" (required parameter)")
}
// Type/Syntax shape info
if let Some(arg) = &flag.arg {
let _ = write!(
long_desc,
" <{help_subcolor_two}{}{RESET}>",
document_shape(arg)
);
}
let _ = write!(long_desc, " - {}", flag.desc);
if let Some(value) = &flag.default_value {
let _ = write!(long_desc, " (default: {})", &value_formatter(value));
}
long_desc.push('\n');
}
long_desc
}

5
crates/nu-plugin/src/plugin/mod.rs
View File

@ -9,7 +9,7 @@ use std::{
thread,
};
use nu_engine::documentation::get_flags_section;
use nu_engine::documentation::{get_flags_section, HelpStyle};
use nu_plugin_core::{
ClientCommunicationIo, CommunicationMode, InterfaceManager, PluginEncoder, PluginRead,
PluginWrite,
@ -657,6 +657,7 @@ fn print_help(plugin: &impl Plugin, encoder: impl PluginEncoder) {
println!("Encoder: {}", encoder.name());
let mut help = String::new();
let help_style = HelpStyle::default();
plugin.commands().into_iter().for_each(|command| {
let signature = command.signature();
@ -670,7 +671,7 @@ fn print_help(plugin: &impl Plugin, encoder: impl PluginEncoder) {
}
})
.and_then(|_| {
let flags = get_flags_section(None, None, &signature, |v| format!("{:#?}", v));
let flags = get_flags_section(&signature, &help_style, |v| format!("{:#?}", v));
write!(help, "{flags}")
})
.and_then(|_| writeln!(help, "\nParameters:"))