Bashly 2.0.0

.github/workflows/test.yml

@@ -14,14 +14,14 @@ jobs:
       LC_ALL: en_US.UTF-8 
 
     strategy:
-      matrix: { ruby: ['3.2', '3.3', '3.4', '4.0'] }
+      matrix: { ruby: ['3.3', '3.4', '4.0'] }
 
     steps:
     - name: Checkout code
       uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
     - name: Install OS dependencies
-      run: sudo apt-get -y install mandoc
+      run: sudo apt-get -y install mandoc zsh
 
     # Rush needed for easy installation of stuff
     - name: Install rush

.rubocop.yml

@@ -8,7 +8,7 @@ inherit_gem:
     - rspec.yml
 
 AllCops:
-  TargetRubyVersion: 3.2
+  TargetRubyVersion: 3.3
   SuggestExtensions: false
   Exclude:
     - dev/**/*

Gemfile

@@ -3,8 +3,9 @@ source 'https://rubygems.org'
 # gem 'debug'
 gem 'rspec'
 gem 'rspec_approvals'
-gem 'runfile', '~> 1.0', require: false
-gem 'runfile-tasks', '~> 1.0', require: false
+gem 'runfile', require: false
+gem 'runfile-tasks', require: false
 gem 'simplecov'
+gem 'completely'
 
 gemspec

bashly.gemspec

@@ -13,10 +13,9 @@ Gem::Specification.new do |s|
   s.executables = ['bashly']
   s.homepage    = 'https://github.com/bashly-framework/bashly'
   s.license     = 'MIT'
-  s.required_ruby_version = '>= 3.2'
+  s.required_ruby_version = '>= 3.3'
 
   s.add_dependency 'colsole', '~> 1.0'
-  s.add_dependency 'completely', '~> 0.8.0'
   s.add_dependency 'gtx', '~> 0.1.1'
   s.add_dependency 'listen', '~> 3.9'
   s.add_dependency 'lp', '~> 0.2.0'

examples/README.md

@@ -21,9 +21,11 @@ Each of these examples demonstrates one aspect or feature of bashly.
 - [default-values](default-values#readme) - arguments and flags with default values
 - [minus-v](minus-v#readme) - using `-v` and `-h` in your script
 - [multiline](multiline#readme) - help messages with multiple lines
+- [completions](completions#readme) - exposing runtime shell completions
 
 ## Advanced configuration features
 
+- [completions-advanced](completions-advanced#readme) - configuring static, dynamic, and option-based runtime completions
 - [catch-all](catch-all#readme) - a command that can receive an arbitrary number of arguments
 - [catch-all-advanced](catch-all-advanced#readme) - another example for the `catch_all` option
 - [catch-all-stdin](catch-all-stdin#readme) - combining `catch_all` with `stdin` to read multiple files
@@ -67,7 +69,6 @@ Each of these examples demonstrates one aspect or feature of bashly.
 - [ini](ini#readme) - using the ini library for direct, low level access to INI files
 - [yaml](yaml#readme) - using the YAML reading functions
 - [colors](colors#readme) - using the color print feature
-- [completions](completions#readme) - adding bash completion functionality
 - [validations](validations#readme) - adding validation functions for arguments, flags or environment variables
 - [hooks](hooks#readme) - adding before/after hooks
 - [stacktrace](stacktrace#readme) - adding stacktrace on error

examples/catch-all/README.md

@@ -79,7 +79,7 @@ Arguments:
 ````shell
 # This file is located at 'src/root_command.sh'.
 # It contains the implementation for the 'download' command.
-# The code you write here will be wrapped by a function named 'download_command()'.
+# The code you write here will be wrapped by a function named 'root_command()'.
 # Feel free to edit this file; your changes will persist when regenerating.
 args:
 - ${args[message]} = something
@@ -92,7 +92,7 @@ args:
 ````shell
 # This file is located at 'src/root_command.sh'.
 # It contains the implementation for the 'download' command.
-# The code you write here will be wrapped by a function named 'download_command()'.
+# The code you write here will be wrapped by a function named 'root_command()'.
 # Feel free to edit this file; your changes will persist when regenerating.
 args:
 - ${args[message]} = something
@@ -111,7 +111,7 @@ other_args:
 ````shell
 # This file is located at 'src/root_command.sh'.
 # It contains the implementation for the 'download' command.
-# The code you write here will be wrapped by a function named 'download_command()'.
+# The code you write here will be wrapped by a function named 'root_command()'.
 # Feel free to edit this file; your changes will persist when regenerating.
 args:
 - ${args[--debug]} = 1

examples/completions-advanced/.gitignore

@@ -0,0 +1 @@
+cli

examples/completions-advanced/README.md

@@ -0,0 +1,143 @@
+# Advanced Runtime Completions Example
+
+Demonstrates configured runtime completions, including static candidates,
+dynamic external commands and internal functions, file and directory sources,
+and the `no-space` option.
+
+Runtime completions are enabled in `settings.yml`. Users can load the generated
+wrapper for their shell with:
+
+```bash
+# Bash
+source <(cli completions)
+
+# Zsh
+source <(cli completions zsh)
+```
+
+<!-- include: settings.yml src/completions_command.sh src/lib/completions.sh -->
+
+-----
+
+## `bashly.yml`
+
+````yaml
+name: cli
+help: Advanced runtime completions example
+version: 0.1.0
+
+commands:
+- name: completions
+  help: Generate a shell completion script
+  args:
+  - name: shell
+    help: Shell to generate completions for
+    allowed: [bash, zsh]
+    default: bash
+
+- name: deploy
+  help: Deploy a branch
+  args:
+  - name: branch
+    help: Branch to deploy
+    required: true
+
+    # Run an external Bash command and add each output line as a candidate.
+    completions:
+      dynamic:
+      - git branch --format='%(refname:short)'
+  - name: environment
+    help: Environment to deploy to
+
+    # Combine literal candidates with an internal function. Prevent the shell
+    # from appending a space after the selected completion.
+    completions:
+      static: [staging, production]
+      dynamic: [completion_environments]
+      options: [no-space]
+  flags:
+  - long: --config
+    arg: file
+    help: Deployment configuration file
+
+    # Ask the shell to add file and directory candidates.
+    completions:
+      options: [files]
+  - long: --directory
+    arg: path
+    help: Deployment directory
+
+    # Ask the shell to add directory candidates only.
+    completions:
+      options: [directories]
+````
+## `settings.yml`
+
+````yaml
+completions: full
+
+````
+
+## `src/completions_command.sh`
+
+````bash
+send_completions "${args[shell]}"
+
+````
+
+## `src/lib/completions.sh`
+
+````bash
+completion_environments() {
+  printf 'development\nstaging\n'
+}
+
+````
+
+
+## Output
+
+### `$ ./cli completions | head -n3`
+
+````shell
+_cli_completions() {
+  local completion_command="${COMP_WORDS[0]}"
+  local completion_current="${COMP_WORDS[COMP_CWORD]:-}"
+
+
+````
+
+### `$ ./cli __complete ""`
+
+````shell
+completions
+deploy
+:options=
+
+
+````
+
+### `$ ./cli __complete deploy main st`
+
+````shell
+staging
+:options=no-space
+
+
+````
+
+### `$ ./cli __complete deploy --config ""`
+
+````shell
+:options=files
+
+
+````
+
+### `$ ./cli __complete deploy --directory ""`
+
+````shell
+:options=directories
+
+
+````

examples/completions-advanced/settings.yml

@@ -0,0 +1 @@
+completions: full

examples/completions-advanced/src/bashly.yml

@@ -0,0 +1,50 @@
+name: cli
+help: Advanced runtime completions example
+version: 0.1.0
+
+commands:
+- name: completions
+  help: Generate a shell completion script
+  args:
+  - name: shell
+    help: Shell to generate completions for
+    allowed: [bash, zsh]
+    default: bash
+
+- name: deploy
+  help: Deploy a branch
+  args:
+  - name: branch
+    help: Branch to deploy
+    required: true
+
+    # Run an external Bash command and add each output line as a candidate.
+    completions:
+      dynamic:
+      - git branch --format='%(refname:short)'
+  - name: environment
+    help: Environment to deploy to
+
+    # Combine literal candidates with an internal function. Prevent the shell
+    # from appending a space after the selected completion.
+    completions:
+      static: [staging, production]
+      dynamic: [completion_environments]
+      options: [no-space]
+
+  flags:
+  - long: --config
+    arg: file
+    help: Deployment configuration file
+
+    # Ask the shell to add file and directory candidates.
+    completions:
+      options: [files]
+
+  - long: --directory
+    arg: path
+    help: Deployment directory
+
+    # Ask the shell to add directory candidates only.
+    completions:
+      options: [directories]

examples/completions-advanced/src/completions_command.sh

@@ -0,0 +1 @@
+send_completions "${args[shell]}"

examples/completions-advanced/src/deploy_command.sh

@@ -0,0 +1 @@
+inspect_args

examples/completions-advanced/src/lib/completions.sh

@@ -0,0 +1,3 @@
+completion_environments() {
+  printf 'development\nstaging\n'
+}

examples/completions-advanced/test.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+
+set -x
+
+bashly generate
+
+### Try Me ###
+
+./cli completions | head -n3
+./cli __complete ""
+./cli __complete deploy main st
+./cli __complete deploy --config ""
+./cli __complete deploy --directory ""

examples/completions/.gitignore

@@ -1 +1 @@
-cli
+cli