From 98d8b37d15c22b5d684aae32dabbdd6108ae67a5 Mon Sep 17 00:00:00 2001
From: Juan Ibiapina <juanibiapina@gmail.com>
Date: Thu, 20 Jun 2024 11:30:23 +0200
Subject: [PATCH 1/5] feat: Support documenting options

---
 .../fixtures/project/libexec/with-help        |  5 ++-
 integration/help.bats                         |  5 ++-
 src/error.rs                                  |  1 +
 src/main.rs                                   | 16 +++++++
 src/parser.rs                                 | 26 +++++++++++-
 src/usage.rs                                  | 42 ++++++++++++++++++-
 6 files changed, 88 insertions(+), 7 deletions(-)

diff --git a/integration/fixtures/project/libexec/with-help b/integration/fixtures/project/libexec/with-help
index 8bdce5c..823ba29 100755
--- a/integration/fixtures/project/libexec/with-help
+++ b/integration/fixtures/project/libexec/with-help
@@ -2,7 +2,10 @@
 #
 # Summary: Command with complete help
 #
-# Usage: {cmd} [args]...
+# Usage: {cmd} <positional> [args]...
+#
+# Options:
+#   positional: A positional argument
 #
 # This is a complete test script with documentation.
 #
diff --git a/integration/help.bats b/integration/help.bats
index b07c6e7..7d129df 100644
--- a/integration/help.bats
+++ b/integration/help.bats
@@ -67,10 +67,11 @@ Options:
   assert_success
   assert_output "Command with complete help
 
-Usage: main with-help [args]...
+Usage: main with-help <positional> [args]...
 
 Arguments:
-  [args]...  
+  <positional>  A positional argument
+  [args]...     
 
 Options:
   -h, --help  Print help
diff --git a/src/error.rs b/src/error.rs
index 31700d5..36b4005 100644
--- a/src/error.rs
+++ b/src/error.rs
@@ -14,5 +14,6 @@ pub enum Error {
     SubCommandInterrupted,
     UnknownSubCommand(String),
     InvalidUsageString(Vec<Simple<char>>),
+    InvalidOptionString(Vec<Simple<char>>),
     InvalidUTF8,
 }
diff --git a/src/main.rs b/src/main.rs
index ce760c9..602dd89 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -91,6 +91,13 @@ fn print_error(error: Error) -> String {
             }
             message
         }
+        Error::InvalidOptionString(errors) => {
+            let mut message = "invalid option string".to_string();
+            for error in errors {
+                message.push_str(&format!("\n  {}", error));
+            }
+            message
+        }
         Error::InvalidUTF8 => "invalid UTF-8".to_string(),
         Error::NoLibexecDir => "libexec directory not found in root".to_string(),
         Error::SubCommandIoError(e) => format!("IO Error: {}", e),
@@ -117,6 +124,15 @@ fn handle_error(config: &Config, error: Error, silent: bool) -> ! {
             }
             exit(1);
         }
+        Error::InvalidOptionString(errors) => {
+            if !silent {
+                println!("{}: invalid option string", config.name);
+                for error in errors {
+                    println!("  {}", error);
+                }
+            }
+            exit(1);
+        }
         Error::InvalidUTF8 => {
             if !silent {
                 println!("invalid UTF-8");
diff --git a/src/parser.rs b/src/parser.rs
index c5a4e3e..f4cc5a5 100644
--- a/src/parser.rs
+++ b/src/parser.rs
@@ -27,12 +27,14 @@ fn extract_initial_comment_block(path: &Path) -> String {
 #[derive(PartialEq)]
 enum Mode {
     Out,
+    Options,
     Description,
 }
 
 pub struct Docs {
-    pub usage: Option<String>,
     pub summary: Option<String>,
+    pub usage: Option<String>,
+    pub options: Vec<String>,
     pub description: Option<String>,
 }
 
@@ -47,6 +49,7 @@ pub fn extract_docs(path: &Path) -> Docs {
 
     let mut summary = None;
     let mut usage = None;
+    let mut options = Vec::new();
     let mut description = Vec::new();
 
     let mut mode = Mode::Out;
@@ -69,6 +72,11 @@ pub fn extract_docs(path: &Path) -> Docs {
                 continue;
             }
 
+            if line == "# Options:" {
+                mode = Mode::Options;
+                continue;
+            }
+
             if let Some(caps) = EXTENDED_RE.captures(&line) {
                 if let Some(m) = caps.get(1) {
                     description.push(m.as_str().trim().to_owned());
@@ -78,6 +86,19 @@ pub fn extract_docs(path: &Path) -> Docs {
             }
         }
 
+        if mode == Mode::Options {
+            if line == "#" {
+                mode = Mode::Out;
+            }
+
+            if let Some(caps) = INDENTED_RE.captures(&line) {
+                if let Some(m) = caps.get(1) {
+                    options.push(m.as_str().trim().to_owned());
+                    continue;
+                }
+            }
+        }
+
         if mode == Mode::Description {
             if line == "#" {
                 description.push("".to_owned());
@@ -94,8 +115,9 @@ pub fn extract_docs(path: &Path) -> Docs {
     }
 
     Docs {
-        usage,
         summary,
+        usage,
+        options,
         description: if description.is_empty() { None } else { Some(description.join("\n")) },
     }
 }
diff --git a/src/usage.rs b/src/usage.rs
index 3b36150..f869436 100644
--- a/src/usage.rs
+++ b/src/usage.rs
@@ -5,6 +5,7 @@ use chumsky::prelude::*;
 use clap::{Command, Arg};
 
 use std::path::Path;
+use std::collections::HashMap;
 
 use crate::parser;
 use crate::error::{Error, Result};
@@ -30,6 +31,25 @@ struct UsageLang {
     rest: Option<String>,
 }
 
+#[derive(Debug, PartialEq)]
+struct OptionSpec {
+    name: String,
+    description: Option<String>,
+}
+
+fn option_parser() -> impl Parser<char, OptionSpec, Error = Simple<char>> {
+    let ident = filter(|c: &char| c.is_ascii_alphabetic())
+        .chain(filter(|c: &char| c.is_ascii_alphanumeric() || *c == '_' || *c == '-').repeated())
+        .collect();
+
+    let description = take_until(end()).padded().map(|(s, _)| s.into_iter().collect());
+
+    ident.padded().then_ignore(just(':')).then(description.padded()).map(|(name, description)| OptionSpec {
+        name,
+        description: Some(description),
+    })
+}
+
 fn usage_parser() -> impl Parser<char, UsageLang, Error = Simple<char>> {
     let prefix = just("# Usage:").padded();
 
@@ -173,12 +193,24 @@ pub fn extract_usage(config: &Config, path: &Path, cmd: &str) -> Usage {
         command = command.after_help(description);
     }
 
+    // TODO: make this a vec of errors
     let mut error = None;
 
+    let mut options = HashMap::<String, OptionSpec>::new();
+
+    for line in docs.options {
+        match option_parser().parse(line) {
+            Ok(option) => {
+                options.insert(option.name.clone(), option);
+            },
+            Err(e) => error = Some(Error::InvalidOptionString(e)),
+        }
+    }
+
     if let Some(line) = docs.usage {
         match usage_parser().parse(line) {
             Ok(usage_lang) => {
-                command = apply_arguments(command, usage_lang);
+                command = apply_arguments(command, usage_lang, options);
             },
             Err(e) => error = Some(Error::InvalidUsageString(e)),
         }
@@ -191,7 +223,7 @@ pub fn extract_usage(config: &Config, path: &Path, cmd: &str) -> Usage {
     return Usage::new(command, error);
 }
 
-fn apply_arguments(mut command: Command, usage_lang: UsageLang) -> Command {
+fn apply_arguments(mut command: Command, usage_lang: UsageLang, options: HashMap<String, OptionSpec>) -> Command {
     for arg in usage_lang.arguments {
         let mut clap_arg = match arg.base {
             ArgBase::Positional(ref name) => {
@@ -214,6 +246,12 @@ fn apply_arguments(mut command: Command, usage_lang: UsageLang) -> Command {
         clap_arg = clap_arg.exclusive(arg.exclusive);
         clap_arg = clap_arg.required(arg.required);
 
+        if let Some(option) = options.get(clap_arg.get_id().as_str()) {
+            if let Some(description) = &option.description {
+                clap_arg = clap_arg.help(description);
+            }
+        }
+
         command = command.arg(clap_arg);
     }
 

From 2918c1c3e1db345e84dcd707fbdc1964d0f8e3a8 Mon Sep 17 00:00:00 2001
From: Juan Ibiapina <juanibiapina@gmail.com>
Date: Thu, 20 Jun 2024 11:33:10 +0200
Subject: [PATCH 2/5] feat: Add args description for commands with default
 usage

---
 integration/help.bats | 2 +-
 src/usage.rs          | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/integration/help.bats b/integration/help.bats
index 7d129df..40408cb 100644
--- a/integration/help.bats
+++ b/integration/help.bats
@@ -53,7 +53,7 @@ Available subcommands:
   assert_output "Usage: main no-doc [args]...
 
 Arguments:
-  [args]...  
+  [args]...  other arguments
 
 Options:
   -h, --help  Print help"
diff --git a/src/usage.rs b/src/usage.rs
index f869436..a86b4f3 100644
--- a/src/usage.rs
+++ b/src/usage.rs
@@ -215,7 +215,7 @@ pub fn extract_usage(config: &Config, path: &Path, cmd: &str) -> Usage {
             Err(e) => error = Some(Error::InvalidUsageString(e)),
         }
     } else {
-        command = command.arg(Arg::new("args").trailing_var_arg(true).num_args(..).allow_hyphen_values(true));
+        command = command.arg(Arg::new("args").help("other arguments").trailing_var_arg(true).num_args(..).allow_hyphen_values(true));
     }
 
     // both command and error are returned because an invalid usage string doesn't prevent the

From b930e278adb7c6b6c7e6dba8c9c04d155b331219 Mon Sep 17 00:00:00 2001
From: Juan Ibiapina <juanibiapina@gmail.com>
Date: Thu, 20 Jun 2024 13:36:32 +0200
Subject: [PATCH 3/5] feat: New completion system

---
 integration/completions-old.bats              | 68 +++++++++++++++++
 integration/completions.bats                  | 12 ++-
 integration/fixtures/completions-old/bin/main |  5 ++
 .../completions-old/libexec/directory/d       |  0
 .../libexec/directory/double/with-completions |  8 ++
 .../completions-old/libexec/no-completions    |  0
 .../completions-old/libexec/with-completions  |  8 ++
 .../libexec/directory/double/with-completions | 14 ++--
 .../completions/libexec/no-completions        |  5 ++
 .../completions/libexec/with-completions      | 31 ++++++--
 src/commands/directory.rs                     |  5 +-
 src/commands/file.rs                          | 34 +++++++++
 src/usage.rs                                  | 75 +++++++++++++++++--
 13 files changed, 246 insertions(+), 19 deletions(-)
 create mode 100644 integration/completions-old.bats
 create mode 100755 integration/fixtures/completions-old/bin/main
 create mode 100755 integration/fixtures/completions-old/libexec/directory/d
 create mode 100755 integration/fixtures/completions-old/libexec/directory/double/with-completions
 create mode 100755 integration/fixtures/completions-old/libexec/no-completions
 create mode 100755 integration/fixtures/completions-old/libexec/with-completions

diff --git a/integration/completions-old.bats b/integration/completions-old.bats
new file mode 100644
index 0000000..e3ab1ce
--- /dev/null
+++ b/integration/completions-old.bats
@@ -0,0 +1,68 @@
+#!/usr/bin/env bats
+
+load test_helper
+
+@test "completions: without arguments, lists commands" {
+  fixture "completions-old"
+
+  run main --completions
+
+  assert_success
+  assert_output "$(main --commands)"
+}
+
+@test "completions: fails gracefully when command is not found" {
+  fixture "completions-old"
+
+  run main --completions not-found
+
+  assert_failure
+  assert_output ""
+}
+
+@test "completions: invokes command completions" {
+  fixture "completions-old"
+
+  run main --completions with-completions
+
+  assert_success
+  assert_output "comp1
+comp2"
+}
+
+@test "completions: lists nothing if command provides no completions" {
+  fixture "completions-old"
+
+  run main --completions no-completions
+
+  assert_success
+  assert_output ""
+}
+
+@test "completions: displays for directory commands" {
+  fixture "completions-old"
+
+  run main --completions directory
+
+  assert_success
+  assert_output "$(main --commands directory)"
+}
+
+@test "completions: displays double nested directory commands" {
+  fixture "completions-old"
+
+  run main --completions directory double
+
+  assert_success
+  assert_output "$(main --commands directory double)"
+}
+
+@test "completions: displays double nested subcommands" {
+  fixture "completions-old"
+
+  run main --completions directory double with-completions
+
+  assert_success
+  assert_output "comp11
+comp21"
+}
diff --git a/integration/completions.bats b/integration/completions.bats
index 2596f45..5e4b9e0 100644
--- a/integration/completions.bats
+++ b/integration/completions.bats
@@ -20,7 +20,7 @@ load test_helper
   assert_output ""
 }
 
-@test "completions: invokes command completions" {
+@test "completions: script: invokes command completions for first argument" {
   fixture "completions"
 
   run main --completions with-completions
@@ -30,6 +30,16 @@ load test_helper
 comp2"
 }
 
+@test "completions: script: invokes command completions for second argument" {
+  fixture "completions"
+
+  run main --completions with-completions value1
+
+  assert_success
+  assert_output "comp3
+comp4"
+}
+
 @test "completions: lists nothing if command provides no completions" {
   fixture "completions"
 
diff --git a/integration/fixtures/completions-old/bin/main b/integration/fixtures/completions-old/bin/main
new file mode 100755
index 0000000..2791125
--- /dev/null
+++ b/integration/fixtures/completions-old/bin/main
@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+
+set -e
+
+$SUB_BIN --color never --name main --executable "${BASH_SOURCE[0]}" --relative ".." -- "$@"
diff --git a/integration/fixtures/completions-old/libexec/directory/d b/integration/fixtures/completions-old/libexec/directory/d
new file mode 100755
index 0000000..e69de29
diff --git a/integration/fixtures/completions-old/libexec/directory/double/with-completions b/integration/fixtures/completions-old/libexec/directory/double/with-completions
new file mode 100755
index 0000000..5d24f95
--- /dev/null
+++ b/integration/fixtures/completions-old/libexec/directory/double/with-completions
@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+
+# Provide completions
+if [ "$1" = "--complete" ]; then
+  echo comp11
+  echo comp21
+  exit
+fi
diff --git a/integration/fixtures/completions-old/libexec/no-completions b/integration/fixtures/completions-old/libexec/no-completions
new file mode 100755
index 0000000..e69de29
diff --git a/integration/fixtures/completions-old/libexec/with-completions b/integration/fixtures/completions-old/libexec/with-completions
new file mode 100755
index 0000000..3a3141b
--- /dev/null
+++ b/integration/fixtures/completions-old/libexec/with-completions
@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+
+# Provide completions
+if [ "$1" = "--complete" ]; then
+  echo comp1
+  echo comp2
+  exit
+fi
diff --git a/integration/fixtures/completions/libexec/directory/double/with-completions b/integration/fixtures/completions/libexec/directory/double/with-completions
index 5d24f95..4b93d60 100755
--- a/integration/fixtures/completions/libexec/directory/double/with-completions
+++ b/integration/fixtures/completions/libexec/directory/double/with-completions
@@ -1,8 +1,10 @@
 #!/usr/bin/env bash
+#
+# Usage: {cmd} <option>
+# Options:
+#   option(script): Description of the option
 
-# Provide completions
-if [ "$1" = "--complete" ]; then
-  echo comp11
-  echo comp21
-  exit
-fi
+set -e
+
+echo "comp11"
+echo "comp21"
diff --git a/integration/fixtures/completions/libexec/no-completions b/integration/fixtures/completions/libexec/no-completions
index e69de29..77b1b05 100755
--- a/integration/fixtures/completions/libexec/no-completions
+++ b/integration/fixtures/completions/libexec/no-completions
@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+#
+# Usage: {cmd}
+
+exit 1
diff --git a/integration/fixtures/completions/libexec/with-completions b/integration/fixtures/completions/libexec/with-completions
index 3a3141b..7e28192 100755
--- a/integration/fixtures/completions/libexec/with-completions
+++ b/integration/fixtures/completions/libexec/with-completions
@@ -1,8 +1,29 @@
 #!/usr/bin/env bash
+#
+# Usage: {cmd} <option1> <option2>
+# Options:
+#   option1 (script): Description of option 1
+#   option2 (script): Description of option 2
 
-# Provide completions
-if [ "$1" = "--complete" ]; then
-  echo comp1
-  echo comp2
-  exit
+set -e
+
+if [[ "$_MAIN_COMPLETE" == "true" ]]; then
+  if [[ "$_MAIN_COMPLETE_ARG" == "option1" ]]; then
+    echo "comp1"
+    echo "comp2"
+
+    exit 0
+  fi
+
+  if [[ "$_MAIN_COMPLETE_ARG" == "option2" ]]; then
+    echo "comp3"
+    echo "comp4"
+
+    exit 0
+  fi
+
+  exit 201
 fi
+
+exit 202
+
diff --git a/src/commands/directory.rs b/src/commands/directory.rs
index 2d7da55..7b57d68 100644
--- a/src/commands/directory.rs
+++ b/src/commands/directory.rs
@@ -1,5 +1,6 @@
 use std::fs;
 use std::path::PathBuf;
+use std::collections::HashMap;
 
 use clap::Arg;
 
@@ -35,7 +36,7 @@ impl<'a> DirectoryCommand<'a> {
             }
         }
 
-        let usage = Usage::new(command, None);
+        let usage = Usage::new(command, HashMap::new(), None);
 
         return Self {
             names,
@@ -63,7 +64,7 @@ impl<'a> DirectoryCommand<'a> {
             }
         }
 
-        let usage = Usage::new(command, None);
+        let usage = Usage::new(command, HashMap::new(), None);
 
         return Self {
             names,
diff --git a/src/commands/file.rs b/src/commands/file.rs
index be171e1..21424a1 100644
--- a/src/commands/file.rs
+++ b/src/commands/file.rs
@@ -60,6 +60,39 @@ impl<'a> Command for FileCommand<'a> {
     }
 
     fn completions(&self) -> Result<i32> {
+        // new completion system
+        if self.usage.provides_completions() {
+            let name = self.usage.get_next_option_name_for_completions(&self.args);
+
+            let completion_type = match name {
+                Some(ref name) => self.usage.get_completion_type(name),
+                None => None,
+            };
+
+            match completion_type {
+                Some(usage::CompletionType::Script) => {
+                    let mut command = process::Command::new(&self.path);
+
+                    command.env(format!("_{}_ROOT", self.config.name.to_uppercase()), &self.config.root);
+                    command.env(format!("_{}_COMPLETE", self.config.name.to_uppercase()), "true");
+                    command.env(format!("_{}_COMPLETE_ARG", self.config.name.to_uppercase()), name.unwrap());
+
+                    let status = command.status().unwrap();
+
+                    return match status.code() {
+                        Some(code) => Ok(code),
+                        None => Err(Error::SubCommandInterrupted),
+                    };
+                },
+                None => {
+                    // do nothing
+                },
+            };
+
+            return Ok(0);
+        }
+
+        // old completion system
         if parser::provides_completions(&self.path) {
             let mut command = process::Command::new(&self.path);
 
@@ -73,6 +106,7 @@ impl<'a> Command for FileCommand<'a> {
                 None => Err(Error::SubCommandInterrupted),
             };
         }
+
         Ok(0)
     }
 
diff --git a/src/usage.rs b/src/usage.rs
index a86b4f3..3f2b644 100644
--- a/src/usage.rs
+++ b/src/usage.rs
@@ -3,6 +3,7 @@ extern crate clap;
 
 use chumsky::prelude::*;
 use clap::{Command, Arg};
+use clap::error::{ContextKind, ContextValue};
 
 use std::path::Path;
 use std::collections::HashMap;
@@ -31,9 +32,15 @@ struct UsageLang {
     rest: Option<String>,
 }
 
+#[derive(Debug, PartialEq, Clone)]
+pub enum CompletionType {
+    Script,
+}
+
 #[derive(Debug, PartialEq)]
 struct OptionSpec {
     name: String,
+    completion_type: Option<CompletionType>,
     description: Option<String>,
 }
 
@@ -42,10 +49,15 @@ fn option_parser() -> impl Parser<char, OptionSpec, Error = Simple<char>> {
         .chain(filter(|c: &char| c.is_ascii_alphanumeric() || *c == '_' || *c == '-').repeated())
         .collect();
 
+    let completion_type_script = just("script").map(|_| CompletionType::Script);
+
+    let completion_type = completion_type_script;
+
     let description = take_until(end()).padded().map(|(s, _)| s.into_iter().collect());
 
-    ident.padded().then_ignore(just(':')).then(description.padded()).map(|(name, description)| OptionSpec {
+    ident.padded().then(completion_type.delimited_by(just('('), just(')')).or_not()).then_ignore(just(':')).then(description.padded()).map(|((name, completion_type), description)| OptionSpec {
         name,
+        completion_type,
         description: Some(description),
     })
 }
@@ -124,13 +136,15 @@ mod tests {
 
 pub struct Usage {
     command: Command,
+    completions: HashMap<String, CompletionType>,
     error: Option<Error>,
 }
 
 impl Usage {
-    pub fn new(command: Command, error: Option<Error>) -> Self {
+    pub fn new(command: Command, completions: HashMap<String, CompletionType>, error: Option<Error>) -> Self {
         Self {
             command,
+            completions,
             error,
         }
     }
@@ -157,6 +171,49 @@ impl Usage {
         Ok(self.command.clone().render_help().ansi().to_string())
     }
 
+    pub fn provides_completions(&self) -> bool {
+        !self.completions.is_empty()
+    }
+
+    pub fn get_completion_type(&self, name: &str) -> Option<CompletionType> {
+        self.completions.get(name).cloned()
+    }
+
+    pub fn get_next_option_name_for_completions(&self, args: &Vec<String>) -> Option<String> {
+        let clap_args = self.command.clone().try_get_matches_from(args);
+
+        let name = match clap_args {
+            Ok(_) => None,
+            Err(e) => {
+                let mut result = None;
+
+                for (k, v) in e.context() {
+                    match k {
+                        ContextKind::InvalidArg => {
+                            match v {
+                                ContextValue::Strings(args) => {
+                                    for arg in args {
+                                        // look for first positional argument that's missing
+                                        if arg.starts_with("<") && arg.ends_with(">") {
+                                            result = Some(arg.trim_matches(|c| c == '<' || c == '>').to_owned());
+                                            break;
+                                        }
+                                    }
+                                },
+                                _ => {},
+                            }
+                        }
+                        _ => {},
+                    }
+                }
+
+                result
+            }
+        };
+
+        name
+    }
+
     pub fn parse_into_kv(&self, args: &Vec<String>) -> Result<String> {
         let clap_args = self.command.clone().get_matches_from(args);
 
@@ -210,7 +267,7 @@ pub fn extract_usage(config: &Config, path: &Path, cmd: &str) -> Usage {
     if let Some(line) = docs.usage {
         match usage_parser().parse(line) {
             Ok(usage_lang) => {
-                command = apply_arguments(command, usage_lang, options);
+                command = apply_arguments(command, usage_lang, &options);
             },
             Err(e) => error = Some(Error::InvalidUsageString(e)),
         }
@@ -218,12 +275,20 @@ pub fn extract_usage(config: &Config, path: &Path, cmd: &str) -> Usage {
         command = command.arg(Arg::new("args").help("other arguments").trailing_var_arg(true).num_args(..).allow_hyphen_values(true));
     }
 
+    let completions: HashMap<String, CompletionType> = options.iter().filter_map(|(name, spec)| {
+        if let Some(completion_type) = &spec.completion_type {
+            Some((name.clone(), completion_type.clone()))
+        } else {
+            None
+        }
+    }).collect();
+
     // both command and error are returned because an invalid usage string doesn't prevent the
     // command from being invoked, but it should be reported to the user
-    return Usage::new(command, error);
+    return Usage::new(command, completions, error);
 }
 
-fn apply_arguments(mut command: Command, usage_lang: UsageLang, options: HashMap<String, OptionSpec>) -> Command {
+fn apply_arguments(mut command: Command, usage_lang: UsageLang, options: &HashMap<String, OptionSpec>) -> Command {
     for arg in usage_lang.arguments {
         let mut clap_arg = match arg.base {
             ArgBase::Positional(ref name) => {

From c9d6d9e65d64ff2923679a9bdd4d5ef9d8f8f495 Mon Sep 17 00:00:00 2001
From: Juan Ibiapina <juanibiapina@gmail.com>
Date: Thu, 20 Jun 2024 13:47:16 +0200
Subject: [PATCH 4/5] doc: Explain new completion system

---
 README.md | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/README.md b/README.md
index 57dfb99..fbd5a42 100644
--- a/README.md
+++ b/README.md
@@ -193,6 +193,9 @@ file. The special comments are:
   Usage comment, when present, has specific syntactic rules and is used to
   parse command line arguments. See [Validating arguments](#validating-arguments)
   and [Parsing arguments](#parsing-arguments) for more information.
+- `Options:` A description of the options the script accepts. This is used to
+  display help information and generate completions. See
+  [Completions](#completions) for more details.
 - Extended documentation: Any other comment lines in this initial block will be
   considered part of the extended documentation.
 
@@ -255,6 +258,42 @@ if [[ "${args[long]}" == "true" ]]; then
 fi
 ```
 
+## Completions
+
+`sub` automatically provides completions for subcommand names.
+
+To enable completions for positional arguments in the `Usage` comment, add an
+`Options:` comment with a list of arguments. An option must have the format:
+`name (completion_type): description`. Completion type is optional. Currently,
+the only supported completion type is `script`, which allows for dynamic
+completions like the following example:
+
+```sh
+# Usage: {cmd} <name>
+# Options:
+#   name (script): A name
+
+# check if we're being requested completions
+if [[ "$_HAT_COMPLETE" == "true" ]]; then
+  if [[ "$_HAT_COMPLETE_ARG" == "name" ]]; then
+    echo "Alice"
+    echo "Bob"
+    echo "Charlie"
+    # note that you can run any command here to generate completions
+  fi
+
+  # make sure to exit when generating completions to prevent the script from running
+  exit 0
+fi
+
+# read arguments
+declare -A args="($_HAT_ARGS)"
+
+# say hello
+echo "Hello, ${args[name]}!"
+```
+
+
 ## Nested subcommands
 
 `sub` supports nested directories for hierarchical command structures. For

From f92468d813f219ff37b584c9db4a402697f4b8d9 Mon Sep 17 00:00:00 2001
From: Juan Ibiapina <juanibiapina@gmail.com>
Date: Thu, 20 Jun 2024 14:10:05 +0200
Subject: [PATCH 5/5] chore: Bump version to 2.2.0

---
 CHANGELOG.md | 6 ++++++
 Cargo.lock   | 2 +-
 Cargo.toml   | 2 +-
 default.nix  | 2 +-
 4 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ee977b2..870dfc0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## v2.2.0 - 20.06.2024
+
+- Add new completions system. The old system is still supported so this isn't a
+  breaking change. The new system has priority over the old system when both
+  are present.
+
 ## v2.1.0 - 16.06.2024
 
 - Rework `--validation` flag. It now needs to come after `--` and validates any
diff --git a/Cargo.lock b/Cargo.lock
index 23a3469..a2b14e6 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -262,7 +262,7 @@ checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
 
 [[package]]
 name = "sub"
-version = "2.1.0"
+version = "2.2.0"
 dependencies = [
  "chumsky",
  "clap",
diff --git a/Cargo.toml b/Cargo.toml
index 7daa4bf..e9fe03b 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "sub"
-version = "2.1.0"
+version = "2.2.0"
 description = "Dynamically generate rich CLIs from scripts."
 authors = ["Juan Ibiapina <juanibiapina@gmail.com>"]
 edition = "2021"
diff --git a/default.nix b/default.nix
index 7802f74..1bda694 100644
--- a/default.nix
+++ b/default.nix
@@ -3,7 +3,7 @@
 with pkgs;
 rustPlatform.buildRustPackage rec {
   name = "sub-${version}";
-  version = "2.1.0";
+  version = "2.2.0";
   src = ./.;
 
   cargoLock = {