mirror of
https://github.com/nushell/nushell.git
synced 2025-06-30 22:50:14 +02:00
Add backtick code formatting to help (#15892)
# Description Adds formatting for code in backticks in `help` output. If it's possible to highlight syntax (`nu-highlight` is available and there's no invalid syntax) then it's highlighted. If the syntax is invalid or not an internal command, then it's dimmed and italicized. like some of the output from `std/help`. If `use_ansi_coloring` is `false`, then we leave the backticks alone. Here's a couple examples:   (note on this one: usually we can highlight partial commands, like `get` in the `select` help page which is invalid according to `nu-check` but is still properly highlighted, however `where` is special cased and just typing `where` with no row condition is highlighted with the garbage style so `where` alone isn't highlighted here)  here's the `where` page with `$env.config.use_ansi_coloring = false`:  Technically, some syntax is valid but isn't really "Nushell code". For example, the `select` help page has a line that says "Select just the \`name\` column". If you just type `name` in the REPL, Nushell treats it as an external command, but for the purposes of highlighted we actually want this to fall back to the generic dimmed/italic style. This is accomplished by temporarily setting the `shape_external` and `shape_externalarg` color config to the generic/fallback style, and then restoring the color config after highlighting. This is a bit hack-ish but it seems to work pretty well. # User-Facing Changes - `help` command now supports code backtick formatting. Code will be highlighted using `nu-highlight` if possible, otherwise it will fall back to a generic format. - Adds `--reject-garbage` flag to `nu-highlight` which will return an error on invalid syntax (which would otherwise be highlighted with `$env.config.color_config.shape_garbage`) # Tests + Formatting Added tests for the regex. I don't think tests for the actual highlighting are very necessary since the failure mode is graceful and it would be difficult to meaningfully test. # After Submitting N/A --------- Co-authored-by: Piepmatz <git+github@cptpiepmatz.de>
This commit is contained in:
132ikl
GitHub
1
Cargo.lock
generated
1
Cargo.lock
generated
@ -3821,6 +3821,7 @@ dependencies = [
|
||||
name = "nu-engine"
|
||||
version = "0.105.2"
|
||||
dependencies = [
|
||||
"fancy-regex",
|
||||
"log",
|
||||
"nu-glob",
|
||||
"nu-path",
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
use nu_engine::documentation::{HelpStyle, get_flags_section};
|
||||
use nu_engine::documentation::{FormatterValue, HelpStyle, get_flags_section};
|
||||
use nu_protocol::{Config, engine::EngineState, levenshtein_distance};
|
||||
use nu_utils::IgnoreCaseExt;
|
||||
use reedline::{Completer, Suggestion};
|
||||
@ -66,8 +66,11 @@ 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(&sig, &help_style, |v| {
|
||||
v.to_parsable_string(", ", &self.config)
|
||||
long_desc.push_str(&get_flags_section(&sig, &help_style, |v| match v {
|
||||
FormatterValue::DefaultValue(value) => {
|
||||
value.to_parsable_string(", ", &self.config)
|
||||
}
|
||||
FormatterValue::CodeString(text) => text.to_string(),
|
||||
}))
|
||||
}
|
||||
|
||||
|
||||
@ -3,6 +3,8 @@ use std::sync::Arc;
|
||||
use nu_engine::command_prelude::*;
|
||||
use reedline::{Highlighter, StyledText};
|
||||
|
||||
use crate::syntax_highlight::highlight_syntax;
|
||||
|
||||
#[derive(Clone)]
|
||||
pub struct NuHighlight;
|
||||
|
||||
@ -14,6 +16,11 @@ impl Command for NuHighlight {
|
||||
fn signature(&self) -> Signature {
|
||||
Signature::build("nu-highlight")
|
||||
.category(Category::Strings)
|
||||
.switch(
|
||||
"reject-garbage",
|
||||
"Return an error if invalid syntax (garbage) was encountered",
|
||||
Some('r'),
|
||||
)
|
||||
.input_output_types(vec![(Type::String, Type::String)])
|
||||
}
|
||||
|
||||
@ -32,19 +39,33 @@ impl Command for NuHighlight {
|
||||
call: &Call,
|
||||
input: PipelineData,
|
||||
) -> Result<PipelineData, ShellError> {
|
||||
let reject_garbage = call.has_flag(engine_state, stack, "reject-garbage")?;
|
||||
let head = call.head;
|
||||
|
||||
let signals = engine_state.signals();
|
||||
|
||||
let highlighter = crate::NuHighlighter {
|
||||
engine_state: Arc::new(engine_state.clone()),
|
||||
stack: Arc::new(stack.clone()),
|
||||
};
|
||||
let engine_state = Arc::new(engine_state.clone());
|
||||
let stack = Arc::new(stack.clone());
|
||||
|
||||
input.map(
|
||||
move |x| match x.coerce_into_string() {
|
||||
Ok(line) => {
|
||||
let highlights = highlighter.highlight(&line, line.len());
|
||||
let result = highlight_syntax(&engine_state, &stack, &line, line.len());
|
||||
|
||||
let highlights = match (reject_garbage, result.found_garbage) {
|
||||
(false, _) => result.text,
|
||||
(true, None) => result.text,
|
||||
(true, Some(span)) => {
|
||||
let error = ShellError::OutsideSpannedLabeledError {
|
||||
src: line,
|
||||
error: "encountered invalid syntax while highlighting".into(),
|
||||
msg: "invalid syntax".into(),
|
||||
span,
|
||||
};
|
||||
return Value::error(error, head);
|
||||
}
|
||||
};
|
||||
|
||||
Value::string(highlights.render_simple(), head)
|
||||
}
|
||||
Err(err) => Value::error(err, head),
|
||||
|
||||
@ -18,11 +18,31 @@ pub struct NuHighlighter {
|
||||
|
||||
impl Highlighter for NuHighlighter {
|
||||
fn highlight(&self, line: &str, cursor: usize) -> StyledText {
|
||||
let result = highlight_syntax(&self.engine_state, &self.stack, line, cursor);
|
||||
result.text
|
||||
}
|
||||
}
|
||||
|
||||
/// Result of a syntax highlight operation
|
||||
#[derive(Default)]
|
||||
pub(crate) struct HighlightResult {
|
||||
/// The highlighted text
|
||||
pub(crate) text: StyledText,
|
||||
/// The span of any garbage that was highlighted
|
||||
pub(crate) found_garbage: Option<Span>,
|
||||
}
|
||||
|
||||
pub(crate) fn highlight_syntax(
|
||||
engine_state: &EngineState,
|
||||
stack: &Stack,
|
||||
line: &str,
|
||||
cursor: usize,
|
||||
) -> HighlightResult {
|
||||
trace!("highlighting: {}", line);
|
||||
|
||||
let config = self.stack.get_config(&self.engine_state);
|
||||
let config = stack.get_config(engine_state);
|
||||
let highlight_resolved_externals = config.highlight_resolved_externals;
|
||||
let mut working_set = StateWorkingSet::new(&self.engine_state);
|
||||
let mut working_set = StateWorkingSet::new(engine_state);
|
||||
let block = parse(&mut working_set, None, line.as_bytes(), false);
|
||||
let (shapes, global_span_offset) = {
|
||||
let mut shapes = flatten_block(&working_set, &block);
|
||||
@ -35,11 +55,8 @@ impl Highlighter for NuHighlighter {
|
||||
working_set.get_span_contents(Span::new(span.start, span.end));
|
||||
|
||||
let str_word = String::from_utf8_lossy(str_contents).to_string();
|
||||
let paths = env::path_str(&self.engine_state, &self.stack, *span).ok();
|
||||
#[allow(deprecated)]
|
||||
let res = if let Ok(cwd) =
|
||||
env::current_dir_str(&self.engine_state, &self.stack)
|
||||
{
|
||||
let paths = env::path_str(engine_state, stack, *span).ok();
|
||||
let res = if let Ok(cwd) = engine_state.cwd(Some(stack)) {
|
||||
which::which_in(str_word, paths.as_ref(), cwd).ok()
|
||||
} else {
|
||||
which::which_in_global(str_word, paths.as_ref())
|
||||
@ -52,10 +69,10 @@ impl Highlighter for NuHighlighter {
|
||||
}
|
||||
}
|
||||
}
|
||||
(shapes, self.engine_state.next_span_start())
|
||||
(shapes, engine_state.next_span_start())
|
||||
};
|
||||
|
||||
let mut output = StyledText::default();
|
||||
let mut result = HighlightResult::default();
|
||||
let mut last_seen_span = global_span_offset;
|
||||
|
||||
let global_cursor_offset = cursor + global_span_offset;
|
||||
@ -80,18 +97,28 @@ impl Highlighter for NuHighlighter {
|
||||
let gap = line
|
||||
[(last_seen_span - global_span_offset)..(shape.0.start - global_span_offset)]
|
||||
.to_string();
|
||||
output.push((Style::new(), gap));
|
||||
result.text.push((Style::new(), gap));
|
||||
}
|
||||
let next_token = line
|
||||
[(shape.0.start - global_span_offset)..(shape.0.end - global_span_offset)]
|
||||
.to_string();
|
||||
|
||||
let mut add_colored_token = |shape: &FlatShape, text: String| {
|
||||
output.push((get_shape_color(shape.as_str(), &config), text));
|
||||
result
|
||||
.text
|
||||
.push((get_shape_color(shape.as_str(), &config), text));
|
||||
};
|
||||
|
||||
match shape.1 {
|
||||
FlatShape::Garbage => add_colored_token(&shape.1, next_token),
|
||||
FlatShape::Garbage => {
|
||||
result.found_garbage.get_or_insert_with(|| {
|
||||
Span::new(
|
||||
shape.0.start - global_span_offset,
|
||||
shape.0.end - global_span_offset,
|
||||
)
|
||||
});
|
||||
add_colored_token(&shape.1, next_token)
|
||||
}
|
||||
FlatShape::Nothing => add_colored_token(&shape.1, next_token),
|
||||
FlatShape::Binary => add_colored_token(&shape.1, next_token),
|
||||
FlatShape::Bool => add_colored_token(&shape.1, next_token),
|
||||
@ -131,7 +158,7 @@ impl Highlighter for NuHighlighter {
|
||||
if highlight {
|
||||
style = get_matching_brackets_style(style, &config);
|
||||
}
|
||||
output.push((style, text));
|
||||
result.text.push((style, text));
|
||||
}
|
||||
}
|
||||
|
||||
@ -153,11 +180,10 @@ impl Highlighter for NuHighlighter {
|
||||
|
||||
let remainder = line[(last_seen_span - global_span_offset)..].to_string();
|
||||
if !remainder.is_empty() {
|
||||
output.push((Style::new(), remainder));
|
||||
result.text.push((Style::new(), remainder));
|
||||
}
|
||||
|
||||
output
|
||||
}
|
||||
result
|
||||
}
|
||||
|
||||
fn split_span_by_highlight_positions(
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
use crate::filters::find_internal;
|
||||
use nu_engine::{command_prelude::*, scope::ScopeData};
|
||||
use nu_engine::{command_prelude::*, get_full_help, scope::ScopeData};
|
||||
|
||||
#[derive(Clone)]
|
||||
pub struct HelpAliases;
|
||||
@ -101,42 +101,17 @@ pub fn help_aliases(
|
||||
});
|
||||
};
|
||||
|
||||
let Some(alias) = engine_state.get_decl(alias).as_alias() else {
|
||||
let alias = engine_state.get_decl(alias);
|
||||
|
||||
if alias.as_alias().is_none() {
|
||||
return Err(ShellError::AliasNotFound {
|
||||
span: Span::merge_many(rest.iter().map(|s| s.span)),
|
||||
});
|
||||
};
|
||||
|
||||
let alias_expansion =
|
||||
String::from_utf8_lossy(engine_state.get_span_contents(alias.wrapped_call.span));
|
||||
let description = alias.description();
|
||||
let extra_desc = alias.extra_description();
|
||||
let help = get_full_help(alias, engine_state, stack);
|
||||
|
||||
// TODO: merge this into documentation.rs at some point
|
||||
const G: &str = "\x1b[32m"; // green
|
||||
const C: &str = "\x1b[36m"; // cyan
|
||||
const RESET: &str = "\x1b[0m"; // reset
|
||||
|
||||
let mut long_desc = String::new();
|
||||
|
||||
long_desc.push_str(description);
|
||||
long_desc.push_str("\n\n");
|
||||
|
||||
if !extra_desc.is_empty() {
|
||||
long_desc.push_str(extra_desc);
|
||||
long_desc.push_str("\n\n");
|
||||
}
|
||||
|
||||
long_desc.push_str(&format!("{G}Alias{RESET}: {C}{name}{RESET}"));
|
||||
long_desc.push_str("\n\n");
|
||||
long_desc.push_str(&format!("{G}Expansion{RESET}:\n {alias_expansion}"));
|
||||
|
||||
let config = stack.get_config(engine_state);
|
||||
if !config.use_ansi_coloring.get(engine_state) {
|
||||
long_desc = nu_utils::strip_ansi_string_likely(long_desc);
|
||||
}
|
||||
|
||||
Ok(Value::string(long_desc, call.head).into_pipeline_data())
|
||||
Ok(Value::string(help, call.head).into_pipeline_data())
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@ -18,6 +18,7 @@ nu-protocol = { path = "../nu-protocol", version = "0.105.2", default-features =
|
||||
nu-path = { path = "../nu-path", version = "0.105.2" }
|
||||
nu-glob = { path = "../nu-glob", version = "0.105.2" }
|
||||
nu-utils = { path = "../nu-utils", version = "0.105.2", default-features = false }
|
||||
fancy-regex = { workspace = true }
|
||||
log = { workspace = true }
|
||||
|
||||
[features]
|
||||
|
||||
@ -1,7 +1,8 @@
|
||||
use crate::eval_call;
|
||||
use fancy_regex::{Captures, Regex};
|
||||
use nu_protocol::{
|
||||
Category, Config, Example, IntoPipelineData, PipelineData, PositionalArg, Signature, Span,
|
||||
SpanId, Spanned, SyntaxShape, Type, Value,
|
||||
Category, Config, IntoPipelineData, PipelineData, PositionalArg, Signature, Span, SpanId,
|
||||
Spanned, SyntaxShape, Type, Value,
|
||||
ast::{Argument, Call, Expr, Expression, RecordItem},
|
||||
debugger::WithoutDebug,
|
||||
engine::CommandType,
|
||||
@ -9,12 +10,21 @@ use nu_protocol::{
|
||||
record,
|
||||
};
|
||||
use nu_utils::terminal_size;
|
||||
use std::{collections::HashMap, fmt::Write};
|
||||
use std::{
|
||||
borrow::Cow,
|
||||
collections::HashMap,
|
||||
fmt::Write,
|
||||
sync::{Arc, LazyLock},
|
||||
};
|
||||
|
||||
/// ANSI style reset
|
||||
const RESET: &str = "\x1b[0m";
|
||||
/// ANSI set default color (as set in the terminal)
|
||||
const DEFAULT_COLOR: &str = "\x1b[39m";
|
||||
/// ANSI set default dimmed
|
||||
const DEFAULT_DIMMED: &str = "\x1b[2;39m";
|
||||
/// ANSI set default italic
|
||||
const DEFAULT_ITALIC: &str = "\x1b[3;39m";
|
||||
|
||||
pub fn get_full_help(
|
||||
command: &dyn Command,
|
||||
@ -27,71 +37,225 @@ pub fn get_full_help(
|
||||
// execution.
|
||||
let stack = &mut stack.start_collect_value();
|
||||
|
||||
let signature = engine_state
|
||||
let nu_config = stack.get_config(engine_state);
|
||||
|
||||
let sig = engine_state
|
||||
.get_signature(command)
|
||||
.update_from_command(command);
|
||||
|
||||
get_documentation(
|
||||
&signature,
|
||||
&command.examples(),
|
||||
engine_state,
|
||||
stack,
|
||||
command.is_keyword(),
|
||||
)
|
||||
}
|
||||
|
||||
/// 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);
|
||||
|
||||
let call = Call::new(Span::unknown());
|
||||
|
||||
if let Ok(output) = decl.run(
|
||||
engine_state,
|
||||
stack,
|
||||
&(&call).into(),
|
||||
Value::string(code_string, Span::unknown()).into_pipeline_data(),
|
||||
) {
|
||||
let result = output.into_value(Span::unknown());
|
||||
if let Ok(s) = result.and_then(Value::coerce_into_string) {
|
||||
return s; // successfully highlighted string
|
||||
}
|
||||
}
|
||||
}
|
||||
code_string.to_string()
|
||||
}
|
||||
|
||||
fn get_documentation(
|
||||
sig: &Signature,
|
||||
examples: &[Example],
|
||||
engine_state: &EngineState,
|
||||
stack: &mut Stack,
|
||||
is_parser_keyword: bool,
|
||||
) -> String {
|
||||
let nu_config = stack.get_config(engine_state);
|
||||
|
||||
// Create ansi colors
|
||||
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();
|
||||
|
||||
let desc = &sig.description;
|
||||
if !desc.is_empty() {
|
||||
long_desc.push_str(desc);
|
||||
long_desc.push_str(&highlight_code(desc, engine_state, stack));
|
||||
long_desc.push_str("\n\n");
|
||||
}
|
||||
|
||||
let extra_desc = &sig.extra_description;
|
||||
if !extra_desc.is_empty() {
|
||||
long_desc.push_str(extra_desc);
|
||||
long_desc.push_str(&highlight_code(extra_desc, engine_state, stack));
|
||||
long_desc.push_str("\n\n");
|
||||
}
|
||||
|
||||
match command.command_type() {
|
||||
CommandType::Alias => get_alias_documentation(
|
||||
&mut long_desc,
|
||||
command,
|
||||
&sig,
|
||||
&help_style,
|
||||
engine_state,
|
||||
stack,
|
||||
),
|
||||
_ => get_command_documentation(
|
||||
&mut long_desc,
|
||||
command,
|
||||
&sig,
|
||||
&nu_config,
|
||||
&help_style,
|
||||
engine_state,
|
||||
stack,
|
||||
),
|
||||
};
|
||||
|
||||
if !nu_config.use_ansi_coloring.get(engine_state) {
|
||||
nu_utils::strip_ansi_string_likely(long_desc)
|
||||
} else {
|
||||
long_desc
|
||||
}
|
||||
}
|
||||
|
||||
/// Syntax highlight code using the `nu-highlight` command if available
|
||||
fn try_nu_highlight(
|
||||
code_string: &str,
|
||||
reject_garbage: bool,
|
||||
engine_state: &EngineState,
|
||||
stack: &mut Stack,
|
||||
) -> Option<String> {
|
||||
let highlighter = engine_state.find_decl(b"nu-highlight", &[])?;
|
||||
|
||||
let decl = engine_state.get_decl(highlighter);
|
||||
let mut call = Call::new(Span::unknown());
|
||||
if reject_garbage {
|
||||
call.add_named((
|
||||
Spanned {
|
||||
item: "reject-garbage".into(),
|
||||
span: Span::unknown(),
|
||||
},
|
||||
None,
|
||||
None,
|
||||
));
|
||||
}
|
||||
|
||||
decl.run(
|
||||
engine_state,
|
||||
stack,
|
||||
&(&call).into(),
|
||||
Value::string(code_string, Span::unknown()).into_pipeline_data(),
|
||||
)
|
||||
.and_then(|pipe| pipe.into_value(Span::unknown()))
|
||||
.and_then(|val| val.coerce_into_string())
|
||||
.ok()
|
||||
}
|
||||
|
||||
/// Syntax highlight code using the `nu-highlight` command if available, falling back to the given string
|
||||
fn nu_highlight_string(code_string: &str, engine_state: &EngineState, stack: &mut Stack) -> String {
|
||||
try_nu_highlight(code_string, false, engine_state, stack)
|
||||
.unwrap_or_else(|| code_string.to_string())
|
||||
}
|
||||
|
||||
/// Apply code highlighting to code in a capture group
|
||||
fn highlight_capture_group(
|
||||
captures: &Captures,
|
||||
engine_state: &EngineState,
|
||||
stack: &mut Stack,
|
||||
) -> String {
|
||||
let Some(content) = captures.get(1) else {
|
||||
// this shouldn't happen
|
||||
return String::new();
|
||||
};
|
||||
|
||||
// Save current color config
|
||||
let config_old = stack.get_config(engine_state);
|
||||
let mut config = (*config_old).clone();
|
||||
|
||||
// Style externals and external arguments with fallback style,
|
||||
// so nu-highlight styles code which is technically valid syntax,
|
||||
// but not an internal command is highlighted with the fallback style
|
||||
let code_style = Value::record(
|
||||
record! {
|
||||
"attr" => Value::string("di", Span::unknown()),
|
||||
},
|
||||
Span::unknown(),
|
||||
);
|
||||
let color_config = &mut config.color_config;
|
||||
color_config.insert("shape_external".into(), code_style.clone());
|
||||
color_config.insert("shape_external_resolved".into(), code_style.clone());
|
||||
color_config.insert("shape_externalarg".into(), code_style);
|
||||
|
||||
// Apply config with external argument style
|
||||
stack.config = Some(Arc::new(config));
|
||||
|
||||
// Highlight and reject invalid syntax
|
||||
let highlighted = try_nu_highlight(content.into(), true, engine_state, stack)
|
||||
// // Make highlighted string italic
|
||||
.map(|text| {
|
||||
let resets = text.match_indices(RESET).count();
|
||||
// replace resets with reset + italic, so the whole string is italicized, excluding the final reset
|
||||
let text = text.replacen(RESET, &format!("{RESET}{DEFAULT_ITALIC}"), resets - 1);
|
||||
// start italicized
|
||||
format!("{DEFAULT_ITALIC}{text}")
|
||||
});
|
||||
|
||||
// Restore original config
|
||||
stack.config = Some(config_old);
|
||||
|
||||
// Use fallback style if highlight failed/syntax was invalid
|
||||
highlighted.unwrap_or_else(|| highlight_fallback(content.into()))
|
||||
}
|
||||
|
||||
/// Apply fallback code style
|
||||
fn highlight_fallback(text: &str) -> String {
|
||||
format!("{DEFAULT_DIMMED}{DEFAULT_ITALIC}{text}{RESET}")
|
||||
}
|
||||
|
||||
/// Highlight code within backticks
|
||||
///
|
||||
/// Will attempt to use nu-highlight, falling back to dimmed and italic on invalid syntax
|
||||
fn highlight_code<'a>(
|
||||
text: &'a str,
|
||||
engine_state: &EngineState,
|
||||
stack: &mut Stack,
|
||||
) -> Cow<'a, str> {
|
||||
let config = stack.get_config(engine_state);
|
||||
if !config.use_ansi_coloring.get(engine_state) {
|
||||
return Cow::Borrowed(text);
|
||||
}
|
||||
|
||||
// See [`tests::test_code_formatting`] for examples
|
||||
static PATTERN: &str = r"(?x) # verbose mode
|
||||
(?<![\p{Letter}\d]) # negative look-behind for alphanumeric: ensure backticks are not directly preceded by letter/number.
|
||||
`
|
||||
([^`\n]+?) # capture characters inside backticks, excluding backticks and newlines. ungreedy.
|
||||
`
|
||||
(?![\p{Letter}\d]) # negative look-ahead for alphanumeric: ensure backticks are not directly followed by letter/number.
|
||||
";
|
||||
static RE: LazyLock<Regex> = LazyLock::new(|| Regex::new(PATTERN).expect("valid regex"));
|
||||
|
||||
let do_try_highlight =
|
||||
|captures: &Captures| highlight_capture_group(captures, engine_state, stack);
|
||||
RE.replace_all(text, do_try_highlight)
|
||||
}
|
||||
|
||||
fn get_alias_documentation(
|
||||
long_desc: &mut String,
|
||||
command: &dyn Command,
|
||||
sig: &Signature,
|
||||
help_style: &HelpStyle,
|
||||
engine_state: &EngineState,
|
||||
stack: &mut Stack,
|
||||
) {
|
||||
let help_section_name = &help_style.section_name;
|
||||
let help_subcolor_one = &help_style.subcolor_one;
|
||||
|
||||
let alias_name = &sig.name;
|
||||
|
||||
long_desc.push_str(&format!(
|
||||
"{help_section_name}Alias{RESET}: {help_subcolor_one}{alias_name}{RESET}"
|
||||
));
|
||||
long_desc.push_str("\n\n");
|
||||
|
||||
let Some(alias) = command.as_alias() else {
|
||||
// this is already checked in `help alias`, but just omit the expansion if this is somehow not actually an alias
|
||||
return;
|
||||
};
|
||||
|
||||
let alias_expansion =
|
||||
String::from_utf8_lossy(engine_state.get_span_contents(alias.wrapped_call.span));
|
||||
|
||||
long_desc.push_str(&format!(
|
||||
"{help_section_name}Expansion{RESET}:\n {}",
|
||||
nu_highlight_string(&alias_expansion, engine_state, stack)
|
||||
));
|
||||
}
|
||||
|
||||
fn get_command_documentation(
|
||||
long_desc: &mut String,
|
||||
command: &dyn Command,
|
||||
sig: &Signature,
|
||||
nu_config: &Config,
|
||||
help_style: &HelpStyle,
|
||||
engine_state: &EngineState,
|
||||
stack: &mut Stack,
|
||||
) {
|
||||
let help_section_name = &help_style.section_name;
|
||||
let help_subcolor_one = &help_style.subcolor_one;
|
||||
|
||||
let cmd_name = &sig.name;
|
||||
|
||||
if !sig.search_terms.is_empty() {
|
||||
let _ = write!(
|
||||
long_desc,
|
||||
@ -129,12 +293,15 @@ fn get_documentation(
|
||||
{
|
||||
subcommands.push(format!(
|
||||
" {help_subcolor_one}{} {help_section_name}({}){RESET} - {}",
|
||||
sig.name, command_type, sig.description
|
||||
sig.name,
|
||||
command_type,
|
||||
highlight_code(&sig.description, engine_state, stack)
|
||||
));
|
||||
} else {
|
||||
subcommands.push(format!(
|
||||
" {help_subcolor_one}{}{RESET} - {}",
|
||||
sig.name, sig.description
|
||||
sig.name,
|
||||
highlight_code(&sig.description, engine_state, stack)
|
||||
));
|
||||
}
|
||||
}
|
||||
@ -148,8 +315,15 @@ fn get_documentation(
|
||||
}
|
||||
|
||||
if !sig.named.is_empty() {
|
||||
long_desc.push_str(&get_flags_section(sig, &help_style, |v| {
|
||||
nu_highlight_string(&v.to_parsable_string(", ", &nu_config), engine_state, stack)
|
||||
long_desc.push_str(&get_flags_section(sig, help_style, |v| match v {
|
||||
FormatterValue::DefaultValue(value) => nu_highlight_string(
|
||||
&value.to_parsable_string(", ", nu_config),
|
||||
engine_state,
|
||||
stack,
|
||||
),
|
||||
FormatterValue::CodeString(text) => {
|
||||
highlight_code(text, engine_state, stack).to_string()
|
||||
}
|
||||
}))
|
||||
}
|
||||
|
||||
@ -160,22 +334,22 @@ fn get_documentation(
|
||||
let _ = write!(long_desc, "\n{help_section_name}Parameters{RESET}:\n");
|
||||
for positional in &sig.required_positional {
|
||||
write_positional(
|
||||
&mut long_desc,
|
||||
long_desc,
|
||||
positional,
|
||||
PositionalKind::Required,
|
||||
&help_style,
|
||||
&nu_config,
|
||||
help_style,
|
||||
nu_config,
|
||||
engine_state,
|
||||
stack,
|
||||
);
|
||||
}
|
||||
for positional in &sig.optional_positional {
|
||||
write_positional(
|
||||
&mut long_desc,
|
||||
long_desc,
|
||||
positional,
|
||||
PositionalKind::Optional,
|
||||
&help_style,
|
||||
&nu_config,
|
||||
help_style,
|
||||
nu_config,
|
||||
engine_state,
|
||||
stack,
|
||||
);
|
||||
@ -183,11 +357,11 @@ fn get_documentation(
|
||||
|
||||
if let Some(rest_positional) = &sig.rest_positional {
|
||||
write_positional(
|
||||
&mut long_desc,
|
||||
long_desc,
|
||||
rest_positional,
|
||||
PositionalKind::Rest,
|
||||
&help_style,
|
||||
&nu_config,
|
||||
help_style,
|
||||
nu_config,
|
||||
engine_state,
|
||||
stack,
|
||||
);
|
||||
@ -202,7 +376,7 @@ fn get_documentation(
|
||||
}
|
||||
}
|
||||
|
||||
if !is_parser_keyword && !sig.input_output_types.is_empty() {
|
||||
if !command.is_keyword() && !sig.input_output_types.is_empty() {
|
||||
if let Some(decl_id) = engine_state.find_decl(b"table", &[]) {
|
||||
// FIXME: we may want to make this the span of the help command in the future
|
||||
let span = Span::unknown();
|
||||
@ -250,6 +424,8 @@ fn get_documentation(
|
||||
}
|
||||
}
|
||||
|
||||
let examples = command.examples();
|
||||
|
||||
if !examples.is_empty() {
|
||||
let _ = write!(long_desc, "\n{help_section_name}Examples{RESET}:");
|
||||
}
|
||||
@ -257,7 +433,7 @@ fn get_documentation(
|
||||
for example in examples {
|
||||
long_desc.push('\n');
|
||||
long_desc.push_str(" ");
|
||||
long_desc.push_str(example.description);
|
||||
long_desc.push_str(&highlight_code(example.description, engine_state, stack));
|
||||
|
||||
if !nu_config.use_ansi_coloring.get(engine_state) {
|
||||
let _ = write!(long_desc, "\n > {}\n", example.example);
|
||||
@ -320,7 +496,7 @@ fn get_documentation(
|
||||
let _ = writeln!(
|
||||
long_desc,
|
||||
" {}",
|
||||
item.to_expanded_string("", &nu_config)
|
||||
item.to_expanded_string("", nu_config)
|
||||
.replace('\n', "\n ")
|
||||
.trim()
|
||||
);
|
||||
@ -329,12 +505,6 @@ fn get_documentation(
|
||||
}
|
||||
|
||||
long_desc.push('\n');
|
||||
|
||||
if !nu_config.use_ansi_coloring.get(engine_state) {
|
||||
nu_utils::strip_ansi_string_likely(long_desc)
|
||||
} else {
|
||||
long_desc
|
||||
}
|
||||
}
|
||||
|
||||
fn update_ansi_from_config(
|
||||
@ -529,7 +699,11 @@ fn write_positional(
|
||||
}
|
||||
};
|
||||
if !positional.desc.is_empty() || arg_kind == PositionalKind::Optional {
|
||||
let _ = write!(long_desc, ": {}", positional.desc);
|
||||
let _ = write!(
|
||||
long_desc,
|
||||
": {}",
|
||||
highlight_code(&positional.desc, engine_state, stack)
|
||||
);
|
||||
}
|
||||
if arg_kind == PositionalKind::Optional {
|
||||
if let Some(value) = &positional.default_value {
|
||||
@ -549,13 +723,25 @@ fn write_positional(
|
||||
long_desc.push('\n');
|
||||
}
|
||||
|
||||
/// Helper for `get_flags_section`
|
||||
///
|
||||
/// The formatter with access to nu-highlight must be passed to `get_flags_section`, but it's not possible
|
||||
/// to pass separate closures since they both need `&mut Stack`, so this enum lets us differentiate between
|
||||
/// default values to be formatted and strings which might contain code in backticks to be highlighted.
|
||||
pub enum FormatterValue<'a> {
|
||||
/// Default value to be styled
|
||||
DefaultValue(&'a Value),
|
||||
/// String which might have code in backticks to be highlighted
|
||||
CodeString(&'a str),
|
||||
}
|
||||
|
||||
pub fn get_flags_section<F>(
|
||||
signature: &Signature,
|
||||
help_style: &HelpStyle,
|
||||
mut value_formatter: F, // format default Value (because some calls cant access config or nu-highlight)
|
||||
mut formatter: F, // format default Value or text with code (because some calls cant access config or nu-highlight)
|
||||
) -> String
|
||||
where
|
||||
F: FnMut(&nu_protocol::Value) -> String,
|
||||
F: FnMut(FormatterValue) -> String,
|
||||
{
|
||||
let help_section_name = &help_style.section_name;
|
||||
let help_subcolor_one = &help_style.subcolor_one;
|
||||
@ -588,12 +774,100 @@ where
|
||||
);
|
||||
}
|
||||
if !flag.desc.is_empty() {
|
||||
let _ = write!(long_desc, ": {}", flag.desc);
|
||||
let _ = write!(
|
||||
long_desc,
|
||||
": {}",
|
||||
&formatter(FormatterValue::CodeString(&flag.desc))
|
||||
);
|
||||
}
|
||||
if let Some(value) = &flag.default_value {
|
||||
let _ = write!(long_desc, " (default: {})", &value_formatter(value));
|
||||
let _ = write!(
|
||||
long_desc,
|
||||
" (default: {})",
|
||||
&formatter(FormatterValue::DefaultValue(value))
|
||||
);
|
||||
}
|
||||
long_desc.push('\n');
|
||||
}
|
||||
long_desc
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use nu_protocol::UseAnsiColoring;
|
||||
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn test_code_formatting() {
|
||||
let mut engine_state = EngineState::new();
|
||||
let mut stack = Stack::new();
|
||||
|
||||
// force coloring on for test
|
||||
let mut config = (*engine_state.config).clone();
|
||||
config.use_ansi_coloring = UseAnsiColoring::True;
|
||||
engine_state.config = Arc::new(config);
|
||||
|
||||
// using Cow::Owned here to mean a match, since the content changed,
|
||||
// and borrowed to mean not a match, since the content didn't change
|
||||
|
||||
// match: typical example
|
||||
let haystack = "Run the `foo` command";
|
||||
assert!(matches!(
|
||||
highlight_code(haystack, &engine_state, &mut stack),
|
||||
Cow::Owned(_)
|
||||
));
|
||||
|
||||
// no match: backticks preceded by alphanum
|
||||
let haystack = "foo`bar`";
|
||||
assert!(matches!(
|
||||
highlight_code(haystack, &engine_state, &mut stack),
|
||||
Cow::Borrowed(_)
|
||||
));
|
||||
|
||||
// match: command at beginning of string is ok
|
||||
let haystack = "`my-command` is cool";
|
||||
assert!(matches!(
|
||||
highlight_code(haystack, &engine_state, &mut stack),
|
||||
Cow::Owned(_)
|
||||
));
|
||||
|
||||
// match: preceded and followed by newline is ok
|
||||
let haystack = r"
|
||||
`command`
|
||||
";
|
||||
assert!(matches!(
|
||||
highlight_code(haystack, &engine_state, &mut stack),
|
||||
Cow::Owned(_)
|
||||
));
|
||||
|
||||
// no match: newline between backticks
|
||||
let haystack = "// hello `beautiful \n world`";
|
||||
assert!(matches!(
|
||||
highlight_code(haystack, &engine_state, &mut stack),
|
||||
Cow::Borrowed(_)
|
||||
));
|
||||
|
||||
// match: backticks followed by period, not letter/number
|
||||
let haystack = "try running `my cool command`.";
|
||||
assert!(matches!(
|
||||
highlight_code(haystack, &engine_state, &mut stack),
|
||||
Cow::Owned(_)
|
||||
));
|
||||
|
||||
// match: backticks enclosed by parenthesis, not letter/number
|
||||
let haystack = "a command (`my cool command`).";
|
||||
assert!(matches!(
|
||||
highlight_code(haystack, &engine_state, &mut stack),
|
||||
Cow::Owned(_)
|
||||
));
|
||||
|
||||
// no match: only characters inside backticks are backticks
|
||||
// (the regex sees two backtick pairs with a single backtick inside, which doesn't qualify)
|
||||
let haystack = "```\ncode block\n```";
|
||||
assert!(matches!(
|
||||
highlight_code(haystack, &engine_state, &mut stack),
|
||||
Cow::Borrowed(_)
|
||||
));
|
||||
}
|
||||
}
|
||||
|
||||
@ -9,7 +9,7 @@ use std::{
|
||||
thread,
|
||||
};
|
||||
|
||||
use nu_engine::documentation::{HelpStyle, get_flags_section};
|
||||
use nu_engine::documentation::{FormatterValue, HelpStyle, get_flags_section};
|
||||
use nu_plugin_core::{
|
||||
ClientCommunicationIo, CommunicationMode, InterfaceManager, PluginEncoder, PluginRead,
|
||||
PluginWrite,
|
||||
@ -684,7 +684,10 @@ fn print_help(plugin: &impl Plugin, encoder: impl PluginEncoder) {
|
||||
}
|
||||
})
|
||||
.and_then(|_| {
|
||||
let flags = get_flags_section(&signature, &help_style, |v| format!("{:#?}", v));
|
||||
let flags = get_flags_section(&signature, &help_style, |v| match v {
|
||||
FormatterValue::DefaultValue(value) => format!("{:#?}", value),
|
||||
FormatterValue::CodeString(text) => text.to_string(),
|
||||
});
|
||||
write!(help, "{flags}")
|
||||
})
|
||||
.and_then(|_| writeln!(help, "\nParameters:"))
|
||||
|
||||
Reference in New Issue
Block a user