nu_command/help/
help_.rs

1use crate::help::{help_aliases, help_commands, help_modules};
2use fancy_regex::{Regex, escape};
3use nu_ansi_term::Style;
4use nu_engine::command_prelude::*;
5use nu_utils::IgnoreCaseExt;
6
7#[derive(Clone)]
8pub struct Help;
9
10impl Command for Help {
11    fn name(&self) -> &str {
12        "help"
13    }
14
15    fn signature(&self) -> Signature {
16        Signature::build("help")
17            .input_output_types(vec![(Type::Nothing, Type::Any)])
18            .rest(
19                "rest",
20                SyntaxShape::String,
21                "The name of command, alias or module to get help on.",
22            )
23            .named(
24                "find",
25                SyntaxShape::String,
26                "string to find in command names, descriptions, and search terms",
27                Some('f'),
28            )
29            .category(Category::Core)
30    }
31
32    fn description(&self) -> &str {
33        "Display help information about different parts of Nushell."
34    }
35
36    fn extra_description(&self) -> &str {
37        r#"`help word` searches for "word" in commands, aliases and modules, in that order."#
38    }
39
40    fn run(
41        &self,
42        engine_state: &EngineState,
43        stack: &mut Stack,
44        call: &Call,
45        _input: PipelineData,
46    ) -> Result<PipelineData, ShellError> {
47        let head = call.head;
48        let find: Option<Spanned<String>> = call.get_flag(engine_state, stack, "find")?;
49        let rest: Vec<Spanned<String>> = call.rest(engine_state, stack, 0)?;
50
51        if rest.is_empty() && find.is_none() {
52            let msg = r#"Welcome to Nushell.
53
54Here are some tips to help you get started.
55  * help -h or help help - show available `help` subcommands and examples
56  * help commands - list all available commands
57  * help <name> - display help about a particular command, alias, or module
58  * help --find <text to search> - search through all help commands table
59
60Nushell works on the idea of a "pipeline". Pipelines are commands connected with the '|' character.
61Each stage in the pipeline works together to load, parse, and display information to you.
62
63[Examples]
64
65List the files in the current directory, sorted by size:
66    ls | sort-by size
67
68Get the current system host name:
69    sys host | get hostname
70
71Get the processes on your system actively using CPU:
72    ps | where cpu > 0
73
74You can also learn more at https://www.nushell.sh/book/"#;
75
76            Ok(Value::string(msg, head).into_pipeline_data())
77        } else if find.is_some() {
78            help_commands(engine_state, stack, call)
79        } else {
80            let result = help_aliases(engine_state, stack, call);
81
82            let result = if let Err(ShellError::AliasNotFound { .. }) = result {
83                help_commands(engine_state, stack, call)
84            } else {
85                result
86            };
87
88            let result = if let Err(ShellError::CommandNotFound { .. }) = result {
89                help_modules(engine_state, stack, call)
90            } else {
91                result
92            };
93
94            if let Err(ShellError::ModuleNotFoundAtRuntime {
95                mod_name: _,
96                span: _,
97            }) = result
98            {
99                Err(ShellError::NotFound {
100                    span: Span::merge_many(rest.iter().map(|s| s.span)),
101                })
102            } else {
103                result
104            }
105        }
106    }
107
108    fn examples(&self) -> Vec<Example> {
109        vec![
110            Example {
111                description: "show help for single command, alias, or module",
112                example: "help match",
113                result: None,
114            },
115            Example {
116                description: "show help for single sub-command, alias, or module",
117                example: "help str join",
118                result: None,
119            },
120            Example {
121                description: "search for string in command names, descriptions, and search terms",
122                example: "help --find char",
123                result: None,
124            },
125        ]
126    }
127}
128
129pub fn highlight_search_in_table(
130    table: Vec<Value>, // list of records
131    search_string: &str,
132    searched_cols: &[&str],
133    string_style: &Style,
134    highlight_style: &Style,
135) -> Result<Vec<Value>, ShellError> {
136    let orig_search_string = search_string;
137    let search_string = search_string.to_folded_case();
138    let mut matches = vec![];
139
140    for mut value in table {
141        let Value::Record {
142            val: ref mut record,
143            ..
144        } = value
145        else {
146            return Err(ShellError::NushellFailedSpanned {
147                msg: "Expected record".to_string(),
148                label: format!("got {}", value.get_type()),
149                span: value.span(),
150            });
151        };
152
153        let has_match = record.to_mut().iter_mut().try_fold(
154            false,
155            |acc: bool, (col, val)| -> Result<bool, ShellError> {
156                if !searched_cols.contains(&col.as_str()) {
157                    // don't search this column
158                    return Ok(acc);
159                }
160                let span = val.span();
161                if let Value::String { val: s, .. } = val {
162                    if s.to_folded_case().contains(&search_string) {
163                        *val = Value::string(
164                            highlight_search_string(
165                                s,
166                                orig_search_string,
167                                string_style,
168                                highlight_style,
169                            )?,
170                            span,
171                        );
172                        return Ok(true);
173                    }
174                }
175                // column does not contain the searched string
176                // ignore non-string values
177                Ok(acc)
178            },
179        )?;
180
181        if has_match {
182            matches.push(value);
183        }
184    }
185
186    Ok(matches)
187}
188
189// Highlight the search string using ANSI escape sequences and regular expressions.
190pub fn highlight_search_string(
191    haystack: &str,
192    needle: &str,
193    string_style: &Style,
194    highlight_style: &Style,
195) -> Result<String, ShellError> {
196    let escaped_needle = escape(needle);
197    let regex_string = format!("(?i){escaped_needle}");
198    let regex = match Regex::new(&regex_string) {
199        Ok(regex) => regex,
200        Err(err) => {
201            return Err(ShellError::GenericError {
202                error: "Could not compile regex".into(),
203                msg: err.to_string(),
204                span: Some(Span::test_data()),
205                help: None,
206                inner: vec![],
207            });
208        }
209    };
210    // strip haystack to remove existing ansi style
211    let stripped_haystack = nu_utils::strip_ansi_string_unlikely(haystack.to_string());
212    let mut last_match_end = 0;
213    let mut highlighted = String::new();
214
215    for cap in regex.captures_iter(stripped_haystack.as_ref()) {
216        match cap {
217            Ok(capture) => {
218                let start = match capture.get(0) {
219                    Some(acap) => acap.start(),
220                    None => 0,
221                };
222                let end = match capture.get(0) {
223                    Some(acap) => acap.end(),
224                    None => 0,
225                };
226                highlighted.push_str(
227                    &string_style
228                        .paint(&stripped_haystack[last_match_end..start])
229                        .to_string(),
230                );
231                highlighted.push_str(
232                    &highlight_style
233                        .paint(&stripped_haystack[start..end])
234                        .to_string(),
235                );
236                last_match_end = end;
237            }
238            Err(e) => {
239                return Err(ShellError::GenericError {
240                    error: "Error with regular expression capture".into(),
241                    msg: e.to_string(),
242                    span: None,
243                    help: None,
244                    inner: vec![],
245                });
246            }
247        }
248    }
249
250    highlighted.push_str(
251        &string_style
252            .paint(&stripped_haystack[last_match_end..])
253            .to_string(),
254    );
255    Ok(highlighted)
256}
nu_command/help/help_.rs

nu_command/help/
help_.rs
