Merge pull request #17 from juanibiapina/new-completions

New completions system

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

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 <[email protected]>"]
 edition = "2021"

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

default.nix

@@ -3,7 +3,7 @@
 with pkgs;
 rustPlatform.buildRustPackage rec {
   name = "sub-${version}";
-  version = "2.1.0";
+  version = "2.2.0";
   src = ./.;
 
   cargoLock = {

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"
+}

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"
 

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 ".." -- "$@"

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

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

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"

integration/fixtures/completions/libexec/no-completions

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+#
+# Usage: {cmd}
+
+exit 1

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
+

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.
 #

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"
@@ -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

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,

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)
     }
 

src/error.rs

@@ -14,5 +14,6 @@ pub enum Error {
     SubCommandInterrupted,
     UnknownSubCommand(String),
     InvalidUsageString(Vec<Simple<char>>),
+    InvalidOptionString(Vec<Simple<char>>),
     InvalidUTF8,
 }