#121 updated: don't try to match top-level command as first argument …

…(it may be part of a longer path); better comments

src/test/resources/basic.bash

@@ -3,7 +3,7 @@
 # basicExample Bash Completion
 # =======================
 #
-# Bash completion support for basicExample,
+# Bash completion support for the `basicExample` command,
 # generated by [picocli](http://picocli.info/).
 #
 # Installation
@@ -31,6 +31,7 @@
 # [2] http://tiswww.case.edu/php/chet/bash/FAQ
 # [3] https://www.gnu.org/software/bash/manual/html_node/The-Shopt-Builtin.html
 # [4] https://stackoverflow.com/questions/17042057/bash-check-element-in-array-for-elements-in-another-array/17042655#17042655
+# [5] https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion.html#Programmable-Completion
 #
 
 # Enable programmable completion facilities (see [3])
@@ -59,13 +60,13 @@ function ArrContains() {
 # on the command line and delegates to the appropriate function
 # to generate possible options and subcommands for the last specified subcommand.
 function _complete_basicExample() {
-  CMDS0=(basicExample)
 
-  ArrContains COMP_WORDS CMDS0 && { _picocli_basicExample; return $?; }
-  echo "not found"
+
+  # No subcommands were specified; generate completions for the top-level command.
   _picocli_basicExample; return $?;
 }
 
+# Generates completions for the options and subcommands of the `basicExample` command.
 function _picocli_basicExample() {
   # Get completion data
   CURR_WORD=${COMP_WORDS[COMP_CWORD]}
@@ -93,4 +94,11 @@ function _picocli_basicExample() {
   COMPREPLY=( $(compgen -W "${FLAG_OPTS} ${ARG_OPTS} ${COMMANDS}" -- ${CURR_WORD}) )
 }
 
-complete -F _complete_basicExample basicExample
+# Define a completion specification (a compspec) for the
+# `basicExample`, `basicExample.sh`, and `basicExample.bash` commands.
+# Uses the bash `complete` builtin (see [5]) to specify that shell function
+# `_complete_basicExample` is responsible for generating possible completions for the
+# current word on the command line.
+# The `-o default` option means that if the function generated no matches, the
+# default Bash completions and the Readline default filename completions are performed.
+complete -F _complete_basicExample -o default basicExample basicExample.sh basicExample.bash

src/test/resources/nestedSubcommands.bash

@@ -3,7 +3,7 @@
 # hierarchy Bash Completion
 # =======================
 #
-# Bash completion support for hierarchy,
+# Bash completion support for the `hierarchy` command,
 # generated by [picocli](http://picocli.info/).
 #
 # Installation
@@ -31,6 +31,7 @@
 # [2] http://tiswww.case.edu/php/chet/bash/FAQ
 # [3] https://www.gnu.org/software/bash/manual/html_node/The-Shopt-Builtin.html
 # [4] https://stackoverflow.com/questions/17042057/bash-check-element-in-array-for-elements-in-another-array/17042655#17042655
+# [5] https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion.html#Programmable-Completion
 #
 
 # Enable programmable completion facilities (see [3])
@@ -59,21 +60,21 @@ function ArrContains() {
 # on the command line and delegates to the appropriate function
 # to generate possible options and subcommands for the last specified subcommand.
 function _complete_hierarchy() {
-  CMDS0=(hierarchy)
-  CMDS1=(hierarchy sub1)
-  CMDS2=(hierarchy sub2)
-  CMDS3=(hierarchy sub2 subsub1)
-  CMDS4=(hierarchy sub2 subsub2)
-
-  ArrContains COMP_WORDS CMDS4 && { _picocli_hierarchy_sub2_subsub2; return $?; }
-  ArrContains COMP_WORDS CMDS3 && { _picocli_hierarchy_sub2_subsub1; return $?; }
-  ArrContains COMP_WORDS CMDS2 && { _picocli_hierarchy_sub2; return $?; }
-  ArrContains COMP_WORDS CMDS1 && { _picocli_hierarchy_sub1; return $?; }
-  ArrContains COMP_WORDS CMDS0 && { _picocli_hierarchy; return $?; }
-  echo "not found"
+  CMDS0=(sub1)
+  CMDS1=(sub2)
+  CMDS2=(sub2 subsub1)
+  CMDS3=(sub2 subsub2)
+
+  ArrContains COMP_WORDS CMDS3 && { _picocli_hierarchy_sub2_subsub2; return $?; }
+  ArrContains COMP_WORDS CMDS2 && { _picocli_hierarchy_sub2_subsub1; return $?; }
+  ArrContains COMP_WORDS CMDS1 && { _picocli_hierarchy_sub2; return $?; }
+  ArrContains COMP_WORDS CMDS0 && { _picocli_hierarchy_sub1; return $?; }
+
+  # No subcommands were specified; generate completions for the top-level command.
   _picocli_hierarchy; return $?;
 }
 
+# Generates completions for the options and subcommands of the `hierarchy` command.
 function _picocli_hierarchy() {
   # Get completion data
   CURR_WORD=${COMP_WORDS[COMP_CWORD]}
@@ -86,6 +87,7 @@ function _picocli_hierarchy() {
   COMPREPLY=( $(compgen -W "${FLAG_OPTS} ${ARG_OPTS} ${COMMANDS}" -- ${CURR_WORD}) )
 }
 
+# Generates completions for the options and subcommands of the `sub1` subcommand.
 function _picocli_hierarchy_sub1() {
   # Get completion data
   CURR_WORD=${COMP_WORDS[COMP_CWORD]}
@@ -98,6 +100,7 @@ function _picocli_hierarchy_sub1() {
   COMPREPLY=( $(compgen -W "${FLAG_OPTS} ${ARG_OPTS} ${COMMANDS}" -- ${CURR_WORD}) )
 }
 
+# Generates completions for the options and subcommands of the `sub2` subcommand.
 function _picocli_hierarchy_sub2() {
   # Get completion data
   CURR_WORD=${COMP_WORDS[COMP_CWORD]}
@@ -126,6 +129,7 @@ function _picocli_hierarchy_sub2() {
   COMPREPLY=( $(compgen -W "${FLAG_OPTS} ${ARG_OPTS} ${COMMANDS}" -- ${CURR_WORD}) )
 }
 
+# Generates completions for the options and subcommands of the `subsub1` subcommand.
 function _picocli_hierarchy_sub2_subsub1() {
   # Get completion data
   CURR_WORD=${COMP_WORDS[COMP_CWORD]}
@@ -154,6 +158,7 @@ function _picocli_hierarchy_sub2_subsub1() {
   COMPREPLY=( $(compgen -W "${FLAG_OPTS} ${ARG_OPTS} ${COMMANDS}" -- ${CURR_WORD}) )
 }
 
+# Generates completions for the options and subcommands of the `subsub2` subcommand.
 function _picocli_hierarchy_sub2_subsub2() {
   # Get completion data
   CURR_WORD=${COMP_WORDS[COMP_CWORD]}
@@ -181,4 +186,11 @@ function _picocli_hierarchy_sub2_subsub2() {
   COMPREPLY=( $(compgen -W "${FLAG_OPTS} ${ARG_OPTS} ${COMMANDS}" -- ${CURR_WORD}) )
 }
 
-complete -F _complete_hierarchy hierarchy
+# Define a completion specification (a compspec) for the
+# `hierarchy`, `hierarchy.sh`, and `hierarchy.bash` commands.
+# Uses the bash `complete` builtin (see [5]) to specify that shell function
+# `_complete_hierarchy` is responsible for generating possible completions for the
+# current word on the command line.
+# The `-o default` option means that if the function generated no matches, the
+# default Bash completions and the Readline default filename completions are performed.
+complete -F _complete_hierarchy -o default hierarchy hierarchy.sh hierarchy.bash