Merge pull request #81 from DannyBen/add/extensible

Add support for extensible commands

Author: DannyBen

README.md

@@ -31,6 +31,7 @@ Create beautiful bash scripts from simple YAML configuration
   - [Argument options](#argument-options)
   - [Flag options](#flag-options)
   - [Environment Variable options](#environment-variable-options)
+- [Extensible Commands](#extensible-commands)
 - [Real World Examples](#real-world-examples)
 - [Contributing / Support](#contributing--support)
 
@@ -203,6 +204,7 @@ command and subcommands (under the `commands` definition).
 `help`     | The header text to display when using `--help`. This option can have multiple lines. In this case, the first line will be used as summary wherever appropriate.
 `version`  | The string to display when using `--version`. *Applicable only in the main command*.
 `default`  | Setting this to `true` on any command, will cause any unrecognized command line to be passed to this command. *Applicable only in subcommands*.
+`extensible` | Specify that this command can be [externally extended](#extensible-commands).
 `examples` | Specify an array of examples to show when using `--help`. Each example can have multiple lines.
 `environment_variables` | Specify an array of [environment variables](#environment-variable-options) needed by your script. 
 `commands` | Specify the array of [commands](#command-options). Each command will have its own args and flags. Note: if `commands` is provided, you cannot specify flags or args at the same level.
@@ -262,6 +264,82 @@ set.
 `required` | Specify if this variable is required.
 
 
+## Extensible Commands
+
+You may configure your generated bash script to delegate any unknown command
+to an external executable, by setting the `extensible` option to either `true`,
+or to a different external command.
+
+This is similar to how `git` works. When you execute `git whatever`, the `git`
+command will look for a file named `git-whatever` in the path, and execute it.
+
+Note that this option cannot be specified together with the `default` option,
+since both specify a handler for unknown commands.
+
+Bashly supports two operation modes.
+
+### Extension Mode (`extensible: true`)
+
+By setting `extensible` to `true`, a specially named executable will be called
+when an unknown command is called by the user.
+
+Given this `bashly.yml` configuration:
+
+```yaml
+name: myscript
+help: Example
+version: 0.1.0
+extensible: true
+
+commands:
+- name: upload
+  help: Upload a file
+```
+
+And this user command:
+
+```
+$ myscript something
+
+```
+
+The generated script will look for an executable named `myscript-something` 
+in the path. If found, it will be called.
+
+See the [extensible example](examples/extensible)
+
+
+### Delegate Mode (`extensible: <executable name>`)
+
+By setting `extensible` to any string, unknown command calls by the user will
+be delegated to the executable with that name.
+
+Given this `bashly.yml` configuration:
+
+```yaml
+name: mygit
+help: Example
+version: 0.1.0
+extensible: git
+
+commands:
+- name: push
+  help: Push to my repository
+```
+
+And this user command:
+
+```
+$ mygit status
+
+```
+
+The generated script will execute `git status`.
+
+See the [extensible-delegate example](examples/extensible-delegate)
+
+
+
 ## Real World Examples
 
 - [Rush][rush] - a Personal Package Manager

Runfile

@@ -33,21 +33,30 @@ end
 
 def examples
   [
+    "examples/catch_all/download",
+    "examples/catch_all_advanced/cli",
     "examples/colors/colorly",
     "examples/command-default/ftp",
     "examples/command-groups/ftp",
+    "examples/commands-nested/cli",
     "examples/commands/cli",
     "examples/config-ini/configly",
     "examples/custom-includes/download",
     "examples/custom-strings/download",
+    "examples/default-values/convert",
     "examples/dependencies/cli",
     "examples/docker-like/docker",
     "examples/environment-variables/cli",
+    "examples/extensible-delegate/mygit",
+    "examples/extensible/cli",
     "examples/git-like/git",
     "examples/minimal/download",
     "examples/minus-v/cli",
     "examples/multiline/multi",
+    "examples/whitelist/login",
     "examples/yaml/yaml",
+    "spec/fixtures/workspaces/catch-all-no-args/download",
+    "spec/fixtures/workspaces/flag-args-with-dash/argflag",
     "spec/fixtures/workspaces/short-command-code/rush",
   ]
 end

examples/catch_all_advanced/cli

@@ -221,6 +221,7 @@ parse_requirements() {
     shift $#
     ;;    
 
+  # :command.command_fallback
   * )
     cli_usage
     exit 1

examples/command-default/ftp

@@ -191,6 +191,7 @@ parse_requirements() {
     shift $#
     ;;    
 
+  # :command.command_fallback
   "" )
     ftp_usage
     exit 1

examples/command-groups/ftp

@@ -270,6 +270,7 @@ parse_requirements() {
     shift $#
     ;;    
 
+  # :command.command_fallback
   * )
     ftp_usage
     exit 1

examples/commands-nested/cli

@@ -340,6 +340,7 @@ parse_requirements() {
     shift $#
     ;;    
 
+  # :command.command_fallback
   * )
     cli_usage
     exit 1
@@ -409,6 +410,7 @@ cli_dir_parse_requirements() {
     shift $#
     ;;    
 
+  # :command.command_fallback
   * )
     cli_dir_usage
     exit 1
@@ -596,6 +598,7 @@ cli_file_parse_requirements() {
     shift $#
     ;;    
 
+  # :command.command_fallback
   * )
     cli_file_usage
     exit 1

examples/commands/cli

@@ -230,6 +230,7 @@ parse_requirements() {
     shift $#
     ;;    
 
+  # :command.command_fallback
   * )
     cli_usage
     exit 1

examples/config-ini/configly

@@ -392,6 +392,7 @@ parse_requirements() {
     shift $#
     ;;    
 
+  # :command.command_fallback
   * )
     configly_usage
     exit 1

examples/dependencies/cli

@@ -169,6 +169,7 @@ parse_requirements() {
     shift $#
     ;;    
 
+  # :command.command_fallback
   * )
     cli_usage
     exit 1

examples/docker-like/docker

@@ -288,6 +288,7 @@ parse_requirements() {
     shift $#
     ;;    
 
+  # :command.command_fallback
   * )
     docker_usage
     exit 1
@@ -357,6 +358,7 @@ docker_container_parse_requirements() {
     shift $#
     ;;    
 
+  # :command.command_fallback
   * )
     docker_container_usage
     exit 1
@@ -531,6 +533,7 @@ docker_image_parse_requirements() {
     shift $#
     ;;    
 
+  # :command.command_fallback
   * )
     docker_image_usage
     exit 1