shannon_nu_command/help/
help_modules.rs

1use crate::filters::find_internal;
2use nu_engine::{command_prelude::*, scope::ScopeData};
3use nu_protocol::DeclId;
4use std::fmt::Write;
5
6#[derive(Clone)]
7pub struct HelpModules;
8
9impl Command for HelpModules {
10    fn name(&self) -> &str {
11        "help modules"
12    }
13
14    fn description(&self) -> &str {
15        "Show help on nushell modules."
16    }
17
18    fn extra_description(&self) -> &str {
19        "When requesting help for a single module, its commands and aliases will be highlighted if they
20are also available in the current scope. Commands/aliases that were imported under a different name
21(such as with a prefix after `use some-module`) will be highlighted in parentheses."
22    }
23
24    fn signature(&self) -> Signature {
25        Signature::build("help modules")
26            .category(Category::Core)
27            .rest(
28                "rest",
29                SyntaxShape::String,
30                "The name of module to get help on.",
31            )
32            .named(
33                "find",
34                SyntaxShape::String,
35                "String to find in module names and descriptions.",
36                Some('f'),
37            )
38            .input_output_types(vec![(Type::Nothing, Type::table())])
39            .allow_variants_without_examples(true)
40    }
41
42    fn examples(&self) -> Vec<Example<'_>> {
43        vec![
44            Example {
45                description: "Show all modules.",
46                example: "help modules",
47                result: None,
48            },
49            Example {
50                description: "Show help for single module.",
51                example: "help modules my-module",
52                result: None,
53            },
54            Example {
55                description: "Search for string in module names and descriptions.",
56                example: "help modules --find my-module",
57                result: None,
58            },
59        ]
60    }
61
62    fn run(
63        &self,
64        engine_state: &EngineState,
65        stack: &mut Stack,
66        call: &Call,
67        _input: PipelineData,
68    ) -> Result<PipelineData, ShellError> {
69        help_modules(engine_state, stack, call)
70    }
71}
72
73pub fn help_modules(
74    engine_state: &EngineState,
75    stack: &mut Stack,
76    call: &Call,
77) -> Result<PipelineData, ShellError> {
78    let head = call.head;
79    let find: Option<Spanned<String>> = call.get_flag(engine_state, stack, "find")?;
80    let rest: Vec<Spanned<String>> = call.rest(engine_state, stack, 0)?;
81
82    if let Some(f) = find {
83        let all_cmds_vec = build_help_modules(engine_state, stack, head);
84        return find_internal(
85            all_cmds_vec,
86            engine_state,
87            stack,
88            &f.item,
89            &["name", "description"],
90            true,
91        );
92    }
93
94    if rest.is_empty() {
95        Ok(build_help_modules(engine_state, stack, head))
96    } else {
97        let mut name = String::new();
98
99        for r in &rest {
100            if !name.is_empty() {
101                name.push(' ');
102            }
103            name.push_str(&r.item);
104        }
105
106        let Some(module_id) = engine_state.find_module(name.as_bytes(), &[]) else {
107            return Err(ShellError::ModuleNotFoundAtRuntime {
108                mod_name: name,
109                span: Span::merge_many(rest.iter().map(|s| s.span)),
110            });
111        };
112
113        let module = engine_state.get_module(module_id);
114
115        let module_desc = engine_state.build_module_desc(module_id);
116
117        // TODO: merge this into documentation.rs at some point
118        const G: &str = "\x1b[32m"; // green
119        const C: &str = "\x1b[36m"; // cyan
120        const CB: &str = "\x1b[1;36m"; // cyan bold
121        const RESET: &str = "\x1b[0m"; // reset
122
123        let mut long_desc = String::new();
124
125        if let Some((desc, extra_desc)) = module_desc {
126            long_desc.push_str(&desc);
127            long_desc.push_str("\n\n");
128
129            if !extra_desc.is_empty() {
130                long_desc.push_str(&extra_desc);
131                long_desc.push_str("\n\n");
132            }
133        }
134
135        write!(long_desc, "{G}Module{RESET}: {C}{name}{RESET}")
136            .expect("writing to a String is infallible");
137        long_desc.push_str("\n\n");
138
139        if !module.decls.is_empty() || module.main.is_some() {
140            let commands: Vec<(Vec<u8>, DeclId)> = engine_state
141                .get_decls_sorted(false)
142                .into_iter()
143                .filter(|(_, id)| !engine_state.get_decl(*id).is_alias())
144                .collect();
145
146            let mut module_commands: Vec<(Vec<u8>, DeclId)> = module
147                .decls()
148                .into_iter()
149                .filter(|(_, id)| !engine_state.get_decl(*id).is_alias())
150                .collect();
151            module_commands.sort_by(|a, b| a.0.cmp(&b.0));
152
153            let commands_str = module_commands
154                .iter()
155                .map(|(name_bytes, id)| {
156                    let name = String::from_utf8_lossy(name_bytes);
157                    if let Some((used_name_bytes, _)) =
158                        commands.iter().find(|(_, decl_id)| id == decl_id)
159                    {
160                        if engine_state.find_decl(name.as_bytes(), &[]).is_some() {
161                            format!("{CB}{name}{RESET}")
162                        } else {
163                            let command_name = String::from_utf8_lossy(used_name_bytes);
164                            format!("{name} ({CB}{command_name}{RESET})")
165                        }
166                    } else {
167                        format!("{name}")
168                    }
169                })
170                .collect::<Vec<String>>()
171                .join(", ");
172
173            write!(long_desc, "{G}Exported commands{RESET}:\n  {commands_str}")
174                .expect("writing to a String is infallible");
175            long_desc.push_str("\n\n");
176        }
177
178        if !module.decls.is_empty() {
179            let aliases: Vec<(Vec<u8>, DeclId)> = engine_state
180                .get_decls_sorted(false)
181                .into_iter()
182                .filter(|(_, id)| engine_state.get_decl(*id).is_alias())
183                .collect();
184
185            let mut module_aliases: Vec<(Vec<u8>, DeclId)> = module
186                .decls()
187                .into_iter()
188                .filter(|(_, id)| engine_state.get_decl(*id).is_alias())
189                .collect();
190            module_aliases.sort_by(|a, b| a.0.cmp(&b.0));
191
192            let aliases_str = module_aliases
193                .iter()
194                .map(|(name_bytes, id)| {
195                    let name = String::from_utf8_lossy(name_bytes);
196                    if let Some((used_name_bytes, _)) =
197                        aliases.iter().find(|(_, alias_id)| id == alias_id)
198                    {
199                        if engine_state.find_decl(name.as_bytes(), &[]).is_some() {
200                            format!("{CB}{name}{RESET}")
201                        } else {
202                            let alias_name = String::from_utf8_lossy(used_name_bytes);
203                            format!("{name} ({CB}{alias_name}{RESET})")
204                        }
205                    } else {
206                        format!("{name}")
207                    }
208                })
209                .collect::<Vec<String>>()
210                .join(", ");
211
212            write!(long_desc, "{G}Exported aliases{RESET}:\n  {aliases_str}")
213                .expect("writing to a String is infallible");
214            long_desc.push_str("\n\n");
215        }
216
217        if module.env_block.is_some() {
218            write!(long_desc, "This module {C}exports{RESET} environment.")
219                .expect("writing to a String is infallible");
220        } else {
221            write!(
222                long_desc,
223                "This module {C}does not export{RESET} environment."
224            )
225            .expect("writing to a String is infallible");
226        }
227
228        let config = stack.get_config(engine_state);
229        if !config.use_ansi_coloring.get(engine_state) {
230            long_desc = nu_utils::strip_ansi_string_likely(long_desc);
231        }
232
233        Ok(Value::string(long_desc, call.head).into_pipeline_data())
234    }
235}
236
237fn build_help_modules(engine_state: &EngineState, stack: &Stack, span: Span) -> PipelineData {
238    let mut scope_data = ScopeData::new(engine_state, stack);
239    scope_data.populate_modules();
240
241    Value::list(scope_data.collect_modules(span), span).into_pipeline_data()
242}
243
244#[cfg(test)]
245mod test {
246    #[test]
247    fn test_examples() -> nu_test_support::Result {
248        use super::HelpModules;
249        nu_test_support::test().examples(HelpModules)
250    }
251}
shannon_nu_command/help/help_modules.rs

shannon_nu_command/help/
help_modules.rs
