Basic implementation of DEBUG trap, help improvements (#16)

cli/src/main.rs

@@ -76,6 +76,8 @@ struct CommandLineArgs {
 enum TraceEvent {
     #[clap(name = "arithmetic")]
     Arithmetic,
+    #[clap(name = "commands")]
+    Commands,
     #[clap(name = "complete")]
     Complete,
     #[clap(name = "expand")]
@@ -124,6 +126,7 @@ fn main() {
     for event in enabled_trace_events {
         let targets = match event {
             TraceEvent::Arithmetic => vec!["parser::arithmetic"],
+            TraceEvent::Commands => vec!["commands"],
             TraceEvent::Complete => vec!["shell::completion", "shell::builtins::complete"],
             TraceEvent::Expand => vec![],
             TraceEvent::Parse => vec!["parse"],

cli/tests/cases/builtins/help.yaml

@@ -5,3 +5,9 @@ cases:
     ignore_stderr: true
     stdin: |
       help
+
+  - name: "Topic-specific help"
+    ignore_stdout: true
+    ignore_stderr: true
+    stdin: |
+      help echo

cli/tests/cases/builtins/trap.yaml

@@ -0,0 +1,29 @@
+name: "Builtins: trap"
+cases:
+  - name: "trap registration"
+    stdin: |
+      trap "echo 1" SIGINT
+      trap "echo 2" SIGINT
+      trap
+
+      trap "echo 3" int
+      trap
+
+      trap "echo 4" 2
+      trap
+
+  - name: "trap EXIT"
+    known_failure: true
+    stdin: |
+      trap "echo [exit]" EXIT
+      trap
+
+  - name: "trap DEBUG"
+    stdin: |
+      trap 'echo [command: ${BASH_COMMAND}]' DEBUG
+      trap
+
+  - name: "trap ERR"
+    stdin: |
+      trap "echo [err]" ERR
+      trap

shell/src/builtin.rs

@@ -116,9 +116,14 @@ pub trait BuiltinCommand: Parser {
         context: context::CommandExecutionContext<'_>,
     ) -> Result<BuiltinExitCode, error::Error>;
 
-    #[allow(dead_code)]
-    fn get_long_help() -> String {
-        Self::command().render_long_help().to_string()
+    fn get_content(name: &str, content_type: BuiltinContentType) -> String {
+        match content_type {
+            BuiltinContentType::DetailedHelp => Self::command().render_help().to_string(),
+            BuiltinContentType::ShortUsage => get_builtin_short_usage(name, &Self::command()),
+            BuiltinContentType::ShortDescription => {
+                get_builtin_short_description(name, &Self::command())
+            }
+        }
     }
 }
 
@@ -128,14 +133,21 @@ pub trait BuiltinDeclarationCommand: BuiltinCommand {
     fn set_declarations(&mut self, declarations: Vec<CommandArg>);
 }
 
+#[allow(clippy::module_name_repetitions)]
+pub enum BuiltinContentType {
+    DetailedHelp,
+    ShortUsage,
+    ShortDescription,
+}
+
 #[allow(clippy::module_name_repetitions)]
 #[derive(Clone)]
 pub struct BuiltinRegistration {
     /// Function to execute the builtin.
     pub execute_func: BuiltinCommandExecuteFunc,
 
-    /// Function to retrieve the builtin's detailed help text.
-    pub help_func: fn() -> String,
+    /// Function to retrieve the builtin's content/help text.
+    pub content_func: fn(&str, BuiltinContentType) -> String,
 
     /// Has this registration been disabled?
     pub disabled: bool,
@@ -146,3 +158,94 @@ pub struct BuiltinRegistration {
     /// Is this builtin one that takes specially handled declarations?
     pub declaration_builtin: bool,
 }
+
+fn get_builtin_short_description(name: &str, command: &clap::Command) -> String {
+    let about = command
+        .get_about()
+        .map_or_else(String::new, |s| s.to_string());
+
+    std::format!("{name} - {about}\n")
+}
+
+fn get_builtin_short_usage(name: &str, command: &clap::Command) -> String {
+    let mut usage = String::new();
+
+    let mut needs_space = false;
+
+    let mut optional_short_opts = vec![];
+    let mut required_short_opts = vec![];
+    for opt in command.get_opts() {
+        if opt.is_hide_set() {
+            continue;
+        }
+
+        if let Some(c) = opt.get_short() {
+            if !opt.is_required_set() {
+                optional_short_opts.push(c);
+            } else {
+                required_short_opts.push(c);
+            }
+        }
+    }
+
+    if !optional_short_opts.is_empty() {
+        if needs_space {
+            usage.push(' ');
+        }
+
+        usage.push('[');
+        usage.push('-');
+        for c in optional_short_opts {
+            usage.push(c);
+        }
+
+        usage.push(']');
+        needs_space = true;
+    }
+
+    if !required_short_opts.is_empty() {
+        if needs_space {
+            usage.push(' ');
+        }
+
+        usage.push('-');
+        for c in required_short_opts {
+            usage.push(c);
+        }
+
+        needs_space = true;
+    }
+
+    for pos in command.get_positionals() {
+        if pos.is_hide_set() {
+            continue;
+        }
+
+        if !pos.is_required_set() {
+            if needs_space {
+                usage.push(' ');
+            }
+
+            usage.push('[');
+            needs_space = false;
+        }
+
+        if let Some(names) = pos.get_value_names() {
+            for name in names {
+                if needs_space {
+                    usage.push(' ');
+                }
+
+                usage.push_str(name);
+                needs_space = true;
+            }
+        }
+
+        if !pos.is_required_set() {
+            usage.push(']');
+            needs_space = true;
+        }
+    }
+
+    std::format!("{name}: {name} {usage}\n")
+}

shell/src/builtins/alias.rs

@@ -10,6 +10,7 @@ pub(crate) struct AliasCommand {
     #[arg(short = 'p')]
     print: bool,
 
+    /// List of aliases to display or update.
     #[arg(name = "name[=value]")]
     aliases: Vec<String>,
 }

shell/src/builtins/bg.rs

@@ -3,8 +3,10 @@ use std::io::Write;
 
 use crate::builtin::{BuiltinCommand, BuiltinExitCode};
 
+/// Moves a job to run in the background.
 #[derive(Parser)]
 pub(crate) struct BgCommand {
+    /// List of job specs to move to background.
     job_specs: Vec<String>,
 }
 

shell/src/builtins/brea.rs → shell/src/builtins/break_.rs

@@ -2,6 +2,7 @@ use clap::Parser;
 
 use crate::builtin::{BuiltinCommand, BuiltinExitCode};
 
+/// Breaks out of a control-flow loop.
 #[derive(Parser)]
 pub(crate) struct BreakCommand {
     #[clap(default_value = "1")]

shell/src/builtins/builtin_.rs

@@ -6,10 +6,13 @@ use crate::{
     commands,
 };
 
+/// Directly invokes a built-in, without going through typical search order.
 #[derive(Parser)]
 pub(crate) struct BuiltiCommand {
+    /// Name of built-in to invoke.
     builtin_name: Option<String>,
 
+    /// Arguments for the built-in.
     #[arg(trailing_var_arg = true, allow_hyphen_values = true)]
     args: Vec<String>,
 }

shell/src/builtins/colon.rs

@@ -2,6 +2,7 @@ use clap::Parser;
 
 use crate::builtin::{BuiltinCommand, BuiltinExitCode};
 
+/// No-op command.
 #[derive(Parser)]
 #[clap(disable_help_flag = true, disable_version_flag = true)]
 pub(crate) struct ColonCommand {

shell/src/builtins/complete.rs

@@ -168,6 +168,7 @@ impl CommonCompleteCommandArgs {
     }
 }
 
+/// Configure programmable command completion.
 #[derive(Parser)]
 pub(crate) struct CompleteCommand {
     #[arg(short = 'p')]
@@ -404,6 +405,7 @@ impl CompleteCommand {
     }
 }
 
+/// Generate command completions.
 #[derive(Parser)]
 pub(crate) struct CompGenCommand {
     #[clap(flatten)]
@@ -454,6 +456,7 @@ impl BuiltinCommand for CompGenCommand {
     }
 }
 
+/// Set programmable command completion options.
 #[derive(Parser)]
 pub(crate) struct CompOptCommand {
     #[arg(short = 'D')]

shell/src/builtins/continu.rs → shell/src/builtins/continue_.rs

@@ -2,6 +2,7 @@ use clap::Parser;
 
 use crate::builtin::{BuiltinCommand, BuiltinExitCode};
 
+/// Continue to the next iteration of a control-flow loop.
 #[derive(Parser)]
 pub(crate) struct ContinueCommand {
     #[clap(default_value = "1")]

shell/src/builtins/declare.rs

@@ -23,6 +23,7 @@ builtin::minus_or_plus_flag_arg!(MakeTracedFlag, 't', "");
 builtin::minus_or_plus_flag_arg!(UppercaseValueOnAssignmentFlag, 'u', "");
 builtin::minus_or_plus_flag_arg!(MakeExportedFlag, 'x', "");
 
+/// Display or update variables and their attributes.
 #[derive(Parser)]
 pub(crate) struct DeclareCommand {
     /// Constrain to function names or definitions.
@@ -220,7 +221,7 @@ impl DeclareCommand {
 
         // Extract the variable name and the initial value being assigned (if any).
         let (name, assigned_index, initial_value, name_is_array) =
-            self.declaration_to_name_and_value(declaration)?;
+            Self::declaration_to_name_and_value(declaration)?;
 
         // Figure out where we should look.
         let lookup = if create_var_local {
@@ -283,9 +284,7 @@ impl DeclareCommand {
         Ok(true)
     }
 
-    #[allow(clippy::unused_self)]
     fn declaration_to_name_and_value(
-        &self,
         declaration: &CommandArg,
     ) -> Result<(String, Option<String>, Option<ShellValueLiteral>, bool), error::Error> {
         let name;

shell/src/builtins/dirs.rs

@@ -3,6 +3,7 @@ use std::io::Write;
 
 use crate::builtin::{BuiltinCommand, BuiltinExitCode};
 
+/// Manage the current directory stack.
 #[derive(Parser, Debug, Default)]
 pub(crate) struct DirsCommand {
     #[arg(short = 'c')]

shell/src/builtins/dot.rs

@@ -7,6 +7,7 @@ use crate::{
     interp::ExecutionParameters,
 };
 
+/// Evalute the provided script in the current shell environment.
 #[derive(Debug, Parser)]
 pub(crate) struct DotCommand {
     pub script_path: String,

shell/src/builtins/echo.rs

@@ -4,6 +4,7 @@ use std::io::Write;
 use crate::builtin::{BuiltinCommand, BuiltinExitCode};
 use crate::escape;
 
+/// Echo text to standard output.
 #[derive(Parser)]
 #[clap(disable_help_flag = true, disable_version_flag = true)]
 pub(crate) struct EchoCommand {

shell/src/builtins/enable.rs

@@ -5,6 +5,7 @@ use std::io::Write;
 use crate::builtin::{BuiltinCommand, BuiltinExitCode};
 use crate::error;
 
+/// Enable, disable, or display built-in commands.
 #[derive(Parser)]
 pub(crate) struct EnableCommand {
     #[arg(short = 'a')]

shell/src/builtins/eval.rs

@@ -4,6 +4,7 @@ use crate::{
 };
 use clap::Parser;
 
+/// Evalute the given string as script.
 #[derive(Parser)]
 pub(crate) struct EvalCommand {
     #[clap(allow_hyphen_values = true)]

shell/src/builtins/exec.rs

@@ -3,6 +3,7 @@ use std::io::Write;
 
 use crate::builtin::{BuiltinCommand, BuiltinExitCode};
 
+/// Exec the provided command.
 #[derive(Parser)]
 pub(crate) struct ExecCommand {
     /// Pass given name as zeroth argument to command.

shell/src/builtins/exit.rs

@@ -2,6 +2,7 @@ use clap::Parser;
 
 use crate::builtin::{BuiltinCommand, BuiltinExitCode};
 
+/// Exit the shell.
 #[derive(Parser)]
 pub(crate) struct ExitCommand {
     code: Option<i32>,

shell/src/builtins/export.rs

@@ -9,6 +9,7 @@ use crate::{
     variables,
 };
 
+/// Add or update exported shell variables.
 #[derive(Parser)]
 pub(crate) struct ExportCommand {
     #[arg(short = 'f')]

shell/src/builtins/false_.rs

@@ -2,6 +2,7 @@ use clap::Parser;
 
 use crate::builtin::{BuiltinCommand, BuiltinExitCode};
 
+/// Return a non-zero exit code.
 #[derive(Parser)]
 pub(crate) struct FalseCommand {}
 

shell/src/builtins/fg.rs

@@ -3,6 +3,7 @@ use std::io::Write;
 
 use crate::builtin::{BuiltinCommand, BuiltinExitCode};
 
+/// Move a specified job to the foreground.
 #[derive(Parser)]
 pub(crate) struct FgCommand {
     job_spec: Option<String>,

shell/src/builtins/getopts.rs

@@ -7,6 +7,7 @@ use crate::{
     variables,
 };
 
+/// Parse command options.
 #[derive(Parser)]
 pub(crate) struct GetOptsCommand {
     /// Specification for options