bashly 1.4.0.rc2 → 2.0.0.rc1

data/lib/bashly/completions/completely.yaml

@@ -60,9 +60,6 @@ tokens:
   path:
   library:
     - colors
-    - completions
-    - completions_script
-    - completions_yaml
     - config
     - help
     - hooks
@@ -91,7 +88,6 @@ tokens:
     - command.args
     - command.catch_all
     - command.commands
-    - command.completions
     - command.default
     - command.dependencies
     - command.environment_variables
@@ -118,6 +114,7 @@ tokens:
     - environment_variable.required
     - environment_variable.validate
     - flag
+    - flag.alias
     - flag.allowed
     - flag.arg
     - flag.completions
@@ -126,6 +123,7 @@ tokens:
     - flag.help
     - flag.long
     - flag.needs
+    - flag.negatable
     - flag.private
     - flag.repeatable
     - flag.required

data/lib/bashly/config_validator.rb

@@ -88,6 +88,20 @@ module Bashly
       assert [true, false, nil, 'always'].include?(value), "#{key} must be a boolean, or the string 'always'"
     end
 
+    def assert_completions(key, value)
+      return unless value
+
+      assert_hash key, value, keys: %i[static dynamic options]
+      assert_array "#{key}.static", value['static'], of: :string
+      assert_array "#{key}.dynamic", value['dynamic'], of: :string
+      assert_array "#{key}.options", value['options'], of: :string
+
+      Array(value['options']).each do |option|
+        assert %w[files directories no-space].include?(option),
+          "#{key}.options contains an unknown option: #{option}"
+      end
+    end
+
     def assert_arg(key, value)
       assert_hash key, value, keys: Script::Argument.option_keys
       refute value['allowed'] && value['completions'], "#{key} cannot have both nub`allowed` and nub`completions`"
@@ -101,7 +115,7 @@ module Bashly
       assert_boolean "#{key}.unique", value['unique']
 
       assert_array "#{key}.allowed", value['allowed'], of: :string
-      assert_array "#{key}.completions", value['completions'], of: :string
+      assert_completions "#{key}.completions", value['completions']
 
       refute value['name'].match(/^-/), "#{key}.name must not start with '-'"
 
@@ -126,23 +140,36 @@ module Bashly
       assert_optional_string "#{key}.short", value['short']
       assert_optional_string "#{key}.help", value['help']
       assert_optional_string "#{key}.arg", value['arg']
+      assert_string_or_array "#{key}.alias", value['alias']
       assert_string_or_array "#{key}.default", value['default']
       assert_string_or_array "#{key}.validate", value['validate']
 
+      assert_boolean "#{key}.negatable", value['negatable']
       assert_boolean "#{key}.private", value['private']
       assert_boolean "#{key}.repeatable", value['repeatable']
       assert_boolean "#{key}.unique", value['unique']
       assert_boolean "#{key}.required", value['required']
       assert_array "#{key}.allowed", value['allowed'], of: :string
       assert_array "#{key}.conflicts", value['conflicts'], of: :string
-      assert_array "#{key}.completions", value['completions'], of: :string
+      assert_completions "#{key}.completions", value['completions']
 
       assert value['long'].match(/^--[a-zA-Z0-9_-]+$/), "#{key}.long must be in the form of '--name'" if value['long']
       assert value['short'].match(/^-[a-zA-Z0-9]$/), "#{key}.short must be in the form of '-n'" if value['short']
+      Array(value['alias']).each_with_index do |flag_alias, index|
+        alias_key = value['alias'].is_a?(Array) ? "#{key}.alias[#{index}]" : "#{key}.alias"
+        assert_flag_alias alias_key, flag_alias
+      end
       refute value['arg'].match(/^-/), "#{key}.arg must not start with '-'" if value['arg']
 
       refute value['required'] && value['default'], "#{key} cannot have both nub`required` and nub`default`"
 
+      if value['negatable']
+        assert value['long'], "#{key}.negatable requires nub`long`"
+        refute value['arg'], "#{key}.negatable does not make sense with nub`arg`"
+        refute value['repeatable'], "#{key}.negatable does not make sense with nub`repeatable`"
+        refute value['required'], "#{key}.negatable does not make sense with nub`required`"
+      end
+
       if value['default']
         assert value['arg'], "#{key}.default does not make sense without nub`arg`"
       end
@@ -165,6 +192,13 @@ module Bashly
       end
     end
 
+    def assert_flag_alias(key, value)
+      assert(
+        value.match(/^--[a-zA-Z0-9_-]+$/) || value.match(/^-[a-zA-Z0-9]$/),
+        "#{key} must be in the form of '--name' or '-n'"
+      )
+    end
+
     def assert_env_var(key, value)
       assert_hash key, value, keys: Script::EnvironmentVariable.option_keys
       assert_string "#{key}.name", value['name']
@@ -216,14 +250,12 @@ module Bashly
       assert_array "#{key}.args", value['args'], of: :arg
       assert_array "#{key}.flags", value['flags'], of: :flag
       assert_array "#{key}.commands", value['commands'], of: :command
-      assert_array "#{key}.completions", value['completions'], of: :string
       assert_array "#{key}.filters", value['filters'], of: :string
       assert_array "#{key}.environment_variables", value['environment_variables'], of: :env_var
       assert_array "#{key}.variables", value['variables'], of: :var
 
       assert_uniq "#{key}.commands", value['commands'], %w[name alias]
-      assert_uniq "#{key}.flags", value['flags'], 'long'
-      assert_uniq "#{key}.flags", value['flags'], 'short'
+      assert_uniq_flags key, value['flags']
       assert_uniq "#{key}.args", value['args'], 'name'
 
       if value['function']
@@ -265,5 +297,23 @@ module Bashly
         refute value['extensible'], "#{key}.extensible makes no sense"
       end
     end
+
+    def assert_uniq_flags(key, flags)
+      return unless flags
+
+      list = flags.flat_map do |flag|
+        [flag['long'], flag['short'], *Array(flag['alias']), negated_flag_name(flag)].compact
+      end
+
+      nonuniqs = list.nonuniq
+      assert nonuniqs.empty?,
+        "#{key}.flags contains non-unique elements (#{nonuniqs.join ', '}) in long or short or alias"
+    end
+
+    def negated_flag_name(flag)
+      return unless flag['negatable'] == true && flag['long']
+
+      "--no-#{flag['long'].delete_prefix '--'}"
+    end
   end
 end

data/lib/bashly/docs/arg.yml

@@ -34,15 +34,21 @@ arg.allowed:
       default: development
 
 arg.completions:
-  help: Specify a list of additional completion suggestions when used in conjunction with `bashly add completions`.
+  help: |-
+    Configure additional runtime completions.
+    `static` contains literal candidates. `dynamic` contains Bash commands that
+    print one candidate per line. `options` accepts `files`, `directories`, and
+    `no-space`.
   url: https://bashly.dev/configuration/argument/#completions
   example: |-
     args:
-    - name: path
-      help: File or directory to process
+    - name: branch
+      help: Branch to process
       completions:
-      - <file>
-      - <directory>
+        static: [main, develop]
+        dynamic:
+        - git branch --format='%(refname:short)'
+        options: [no-space]
 
 arg.default:
   help: Specify the value to apply when not provided by the user.
@@ -102,4 +108,4 @@ arg.validate:
   example: |-
     args:
     - name: path
-      validate: file_exists
+      validate: file_exists

data/lib/bashly/docs/command.yml

@@ -74,18 +74,6 @@ command.commands:
       alias: a
       help: Register a local repository
 
-command.completions:
-  help: Specify a list of additional completion suggestions when used in conjunction with `bashly add completions`.
-  url: https://bashly.dev/configuration/command/#completions
-  example: |-
-    commands:
-    - name: view
-      help: View a directory, system user or a git branch
-      completions:
-      - <directory>
-      - <user>
-      - $(git branch 2> /dev/null)
-
 command.default:
   help: Specify that this sub-command will be executed implicitly.
   url: https://bashly.dev/configuration/command/#default

data/lib/bashly/docs/flag.yml

@@ -13,6 +13,17 @@ flag:
       help: Repository user name
       required: true
 
+flag.alias:
+  help: Specify one or more aliases for this flag. Each alias must include the `--` or `-` prefix.
+  url: https://bashly.dev/configuration/flag/#alias
+  example: |-
+    flags:
+    - long: --container
+      short: -c
+      alias: [--pod, -p]
+      arg: name
+      help: Container name
+
 flag.allowed:
   help: Specify a list of allowed values. Can be used in conjunction with `default` and `required`, and must be accompanied by `arg`.
   url: https://bashly.dev/configuration/flag/#allowed
@@ -47,14 +58,18 @@ flag.arg:
       help: Specify the user name
 
 flag.completions:
-  help: Specify a list of additional completion suggestions when used in conjunction with `bashly add completions`. Must be accompanied by `arg`.
+  help: |-
+    Configure additional runtime completions. Must be accompanied by `arg`.
+    `static` contains literal candidates. `dynamic` contains Bash commands that
+    print one candidate per line. `options` accepts `files`, `directories`, and
+    `no-space`.
   url: https://bashly.dev/configuration/flag/#completions
   example: |-
     flags:
-    - long: --user
-      arg: username
+    - long: --config
+      arg: file
       completions:
-      - <user>
+        options: [files]
     
     # Anything in the 'allowed' option is automatically added as a completion.
     - long: --protocol
@@ -136,6 +151,15 @@ flag.needs:
       help: Where to add the alias
       needs: [--add]
 
+flag.negatable:
+  help: Allow a boolean long flag to also be disabled with its `--no-` form.
+  url: https://bashly.dev/configuration/flag/#negatable
+  example: |-
+    flags:
+    - long: --color
+      help: Enable color output
+      negatable: true
+
 flag.private:
   help: Specify that this flag should not be displayed in the help text.
   url: https://bashly.dev/configuration/flag/#private
@@ -205,4 +229,4 @@ flag.validate:
    - long: --config
      arg: path
      help: Load configuration from a file
-     validate: file_exists
+     validate: file_exists

data/lib/bashly/libraries/libraries.yml

@@ -12,21 +12,6 @@ colors:
 
       m`$ bashly add hooks`
 
-completions: 
-  help: Generate a bash completions function.
-  usage: '[PATH]'
-  handler: Bashly::Libraries::CompletionsFunction
-
-completions_script:
-  help: Generate a standalone bash completions script.
-  usage: '[PATH]'
-  handler: Bashly::Libraries::CompletionsScript
-
-completions_yaml:
-  help: Generate a completions YAML configuration for Completely.
-  usage: '[PATH]'
-  handler: Bashly::Libraries::CompletionsYAML
-
 config:
   help: Add functions for handling INI configuration files to the lib directory.
   files:

data/lib/bashly/libraries/settings/settings.yml

@@ -157,13 +157,21 @@ env: development
 # - always          # render this feature in any environment
 # - never           # do not render this feature
 enable_header_comment: always
-enable_bash3_bouncer: always
+enable_bash_version_bouncer: always
 enable_view_markers: development
 enable_inspect_args: development
 enable_deps_array: always
 enable_env_var_names_array: always
 enable_sourcing: development
 
+# Generate native runtime completions. Supported values:
+# - ~ or false     # disable completions (default)
+# - minimal        # generate the runtime completion engine without shell adapters
+# - bash or zsh    # generate the runtime engine and one shell adapter
+# - bash,zsh       # generate the runtime engine and selected shell adapters
+# - full           # generate the runtime engine and all available shell adapters
+completions: ~
+
 
 #-------------------------------------------------------------------------------
 # DEVELOPER OPTIONS

data/lib/bashly/script/argument.rb

@@ -23,6 +23,18 @@ module Bashly
         end
       end
 
+      def completion_static
+        completions&.fetch('static', []) || []
+      end
+
+      def completion_dynamic
+        completions&.fetch('dynamic', []) || []
+      end
+
+      def completion_options
+        completions&.fetch('options', []) || []
+      end
+
       def label
         repeatable ? "#{name.upcase}..." : name.upcase
       end

data/lib/bashly/script/command.rb

@@ -1,7 +1,6 @@
 module Bashly
   module Script
     class Command < Base
-      include Completions::Command
       include Introspection::Arguments
       include Introspection::Commands
       include Introspection::Dependencies
@@ -14,7 +13,7 @@ module Bashly
       class << self
         def option_keys
           @option_keys ||= %i[
-            alias argfile args catch_all commands completions
+            alias argfile args catch_all commands
             default dependencies environment_variables examples
             extensible expose filename filters flags
             footer function group help help_header_override name

data/lib/bashly/script/flag.rb

@@ -3,27 +3,34 @@ require 'shellwords'
 module Bashly
   module Script
     class Flag < Base
-      include Completions::Flag
       include Introspection::Visibility
       include Introspection::Validate
 
       class << self
         def option_keys
           @option_keys ||= %i[
-            allowed arg completions conflicts default help long needs
-            private repeatable required short unique validate
+            alias allowed arg completions conflicts default help long needs
+            negatable private repeatable required short unique validate
           ]
         end
       end
 
+      def alt
+        return [] unless options['alias']
+
+        options['alias'].is_a?(String) ? [options['alias']] : options['alias']
+      end
+
       def aliases
-        if long && short
-          [long, short]
-        elsif long
-          [long]
-        else
-          [short]
-        end
+        [long, negated_long, short].compact + alt
+      end
+
+      def positive_aliases
+        primary_aliases + alt
+      end
+
+      def negated_long
+        "--no-#{long_without_prefix}" if negatable && long
       end
 
       def default_string
@@ -36,17 +43,47 @@ module Bashly
         end
       end
 
+      def completion_static
+        completions&.fetch('static', []) || []
+      end
+
+      def completion_dynamic
+        completions&.fetch('dynamic', []) || []
+      end
+
+      def completion_options
+        completions&.fetch('options', []) || []
+      end
+
       def name
         long || short
       end
 
       def usage_string(extended: false)
-        result = [aliases.join(', ')]
+        result = [usage_aliases.join(', ')]
         result << arg.upcase if arg
         result << strings[:required] if required && extended
         result << strings[:repeatable] if repeatable && extended
         result.join ' '
       end
+
+    private
+
+      def primary_aliases
+        [long, short].compact
+      end
+
+      def usage_aliases
+        [usage_long, short].compact + alt
+      end
+
+      def usage_long
+        negatable && long ? "--[no-]#{long_without_prefix}" : long
+      end
+
+      def long_without_prefix
+        long.delete_prefix '--'
+      end
     end
   end
 end

data/lib/bashly/script/introspection/commands.rb

@@ -41,6 +41,11 @@ module Bashly
           commands.map(&:name)
         end
 
+        # Returns command names and aliases that can be offered as completions
+        def completion_aliases
+          public_commands.flat_map(&:aliases).reject { |name| name.end_with? '*' }
+        end
+
         # Returns an array of the Commands
         def commands
           return [] unless options['commands']

data/lib/bashly/script/wrapper.rb

@@ -46,7 +46,7 @@ module Bashly
 
       def default_header
         result = render 'header'
-        result += render('bash3_bouncer') unless function_name || !Settings.enabled?(:bash3_bouncer)
+        result += render('bash_version_bouncer') unless function_name || !Settings.enabled?(:bash_version_bouncer)
         result
       end
 

data/lib/bashly/settings.rb

@@ -1,5 +1,7 @@
 module Bashly
   class Settings
+    COMPLETION_SHELLS = %w[bash zsh].freeze
+
     class << self
       include AssetHelper
 
@@ -7,9 +9,10 @@ module Bashly
         :argfile_var,
         :commands_dir,
         :compact_short_flags,
+        :completions,
         :conjoined_flag_args,
         :config_path,
-        :enable_bash3_bouncer,
+        :enable_bash_version_bouncer,
         :enable_deps_array,
         :enable_env_var_names_array,
         :enable_header_comment,
@@ -50,6 +53,28 @@ module Bashly
         @compact_short_flags ||= get :compact_short_flags
       end
 
+      def completions
+        @completions ||= get :completions
+      end
+
+      def completions?
+        completions == 'minimal' || completion_shells.any?
+      end
+
+      def completion_shells
+        value = completions
+        return [] if value.nil? || value == false || value == 'minimal'
+        return COMPLETION_SHELLS if value == 'full'
+
+        shells = value.split(',', -1).map(&:strip) if value.is_a? String
+        valid = shells&.any? && shells.all? { |shell| COMPLETION_SHELLS.include? shell }
+        unique = shells&.uniq == shells
+        return shells if valid && unique
+
+        raise ConfigurationError,
+          "completions must be false, minimal, full, or a comma-separated list of: #{COMPLETION_SHELLS.join ', '}"
+      end
+
       def conjoined_flag_args
         @conjoined_flag_args ||= get :conjoined_flag_args
       end
@@ -64,8 +89,8 @@ module Bashly
           (send(:"enable_#{feature}") == 'development' && !production?)
       end
 
-      def enable_bash3_bouncer
-        @enable_bash3_bouncer ||= get :enable_bash3_bouncer
+      def enable_bash_version_bouncer
+        @enable_bash_version_bouncer ||= get :enable_bash_version_bouncer
       end
 
       def enable_deps_array

data/lib/bashly/version.rb

@@ -1,3 +1,3 @@
 module Bashly
-  VERSION = '1.4.0.rc2'
+  VERSION = '2.0.0.rc1'
 end

data/lib/bashly/views/argument/completion.gtx

@@ -0,0 +1,31 @@
+if allowed
+  > local -a completion_values=(
+  allowed.each do |value|
+    >   "{{ value }}"
+  end
+  > )
+  if unique
+    > local completion_value
+    > for completion_value in "${completion_values[@]}"; do
+    >   if [[ -z "${completion_used_arguments["{{ name }}:$completion_value"]:-}" ]]; then
+    >     completion_candidates "$completion_current" "$completion_value"
+    >   fi
+    > done
+  else
+    > completion_candidates "$completion_current" "${completion_values[@]}"
+  end
+end
+
+if completion_static.any?
+  > completion_candidates "$completion_current" {{ completion_static.map { |value| Shellwords.shellescape value }.join ' ' }}
+end
+
+completion_dynamic.each do |command|
+  > if completion_output="$({ {{ command }}; } 2>/dev/null)"; then
+  >   completion_dynamic_candidates "$completion_current" "$completion_output"
+  > fi
+end
+
+if completion_options.any?
+  > completion_add_options {{ completion_options.join ' ' }}
+end

data/lib/bashly/views/argument/completion_filter.gtx

@@ -0,0 +1 @@
+> completion_used_arguments["{{ name }}:$1"]=1

data/lib/bashly/views/command/completion_argument_candidates.gtx

@@ -0,0 +1,11 @@
+if args.any?
+  > if [[ $completion_current != -* ]]; then
+  >   case "$completion_arg_index" in
+  args.each_with_index do |arg, index|
+    >     {{ index }})
+    = arg.render(:completion).indent 6
+    >       ;;
+  end
+  >   esac
+  > fi
+end

data/lib/bashly/views/command/completion_argument_filter.gtx

@@ -0,0 +1,25 @@
+if args.any?(&:unique)
+  > case "$completion_arg_index" in
+  args.each_with_index do |arg, index|
+    next unless arg.unique
+
+    >   {{ index }})
+    = arg.render(:completion_filter).indent 4
+    >     ;;
+  end
+  > esac
+end
+
+if args.last.repeatable
+  last_arg_index = args.length - 1
+  > if [[ $completion_arg_index -lt {{ last_arg_index }} ]]; then
+  >   completion_arg_index=$((completion_arg_index + 1))
+  > fi
+  > shift
+else
+  > if [[ $completion_arg_index -ge {{ args.length }} ]]; then
+  >   return
+  > fi
+  > completion_arg_index=$((completion_arg_index + 1))
+  > shift
+end

data/lib/bashly/views/command/completion_command_candidates.gtx

@@ -0,0 +1,3 @@
+if completion_aliases.any?
+  > completion_candidates "$completion_current" {{ completion_aliases.join ' ' }}
+end

data/lib/bashly/views/command/completion_flag_candidates.gtx

@@ -0,0 +1,21 @@
+if fixed_flags? || public_flags.any?
+  > if [[ $completion_current == -* ]]; then
+  if fixed_flags?
+    if short_flag_exist? '-h'
+      >   completion_flag_candidates --help "$completion_current" --help
+    else
+      >   completion_flag_candidates --help "$completion_current" --help -h
+    end
+    if root_command?
+      if short_flag_exist? '-v'
+        >   completion_flag_candidates --version "$completion_current" --version
+      else
+        >   completion_flag_candidates --version "$completion_current" --version -v
+      end
+    end
+  end
+  public_flags.each do |flag|
+    = flag.render(:completion).indent 2
+  end
+  > fi
+end

data/lib/bashly/views/command/completion_function.gtx

@@ -0,0 +1,24 @@
+= view_marker
+
+> {{ function_name }}_completion() {
+>   local completion_current="$1"
+if args.any?
+  >   local completion_arg_index=0
+end
+if args.any?(&:unique)
+  >   local -A completion_used_arguments=()
+end
+if flags.any?(&:unique)
+  >   local -A completion_used_flag_values=()
+end
+>   shift
+>
+= render(:completion_word_filter).indent 2
+= render(:completion_command_candidates).indent 2
+if default_command
+  >   {{ default_command.function_name }}_completion "$completion_current"
+end
+= render(:completion_flag_candidates).indent 2
+= render(:completion_argument_candidates).indent 2
+> }
+>