completely 0.6.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b40f2059243b2820d2ce140394be5551e5ddb131351adb35d26343841f8a54c7
-  data.tar.gz: 71e01f5c44395f97023afff5a1822c5fa651efb98155a3b8dd05f750a19a5419
+  metadata.gz: 8afc0f96ec2612d016fd4a9914b7257f18c2b9e8302b7579129dab4fcaa2ebf1
+  data.tar.gz: f94b94f03d432c374f11c006f089f31e78b24aab124f3abf996e4a13f96fdcf5
 SHA512:
-  metadata.gz: 71d90d706eb26933817483395670eb5d5ed516b606b62c1f4b9408afdec92b977142e4b2501ff12b75bb47fa971e558696ef5294a3c569f3856da8cb9904254f
-  data.tar.gz: df1e950e2f839a977181521bb09fb917e6d47046f4f6b80d7a8dfc557b2c5d67ee66f962b7a23fd2456137a283bae6ffc9fe38e9ad97355c53c82a1ec84cff7a
+  metadata.gz: 88f5725ccbd2532d6270e8de9cba476ca14a37917bc87b0dd284928cf27a7c08ca6fcdca54c5fa49d7fb63c74197617f81c641ded2f91fa74d5c6c1ec9bf33bc
+  data.tar.gz: 78ee662b15cc64f7172410c6f28aa2ed55f1224aaa0e66700c51380cc36e6ad6fbc4740d11cf4387e58c683d0050122d47d88b4f93a9031a6065c1e359a36b8d

data/README.md

@@ -40,10 +40,11 @@ or with Docker:
 $ alias completely='docker run --rm -it --user $(id -u):$(id -g) --volume "$PWD:/app" dannyben/completely'
 ```
 
-## Using the `completely` command line
 
-The `completely` command line works with a simple YAML configuration file as
-input, and generates a bash completions script as output.
+## Configuration syntax
+
+Completely works with a simple YAML configuration file as input, and generates
+a bash completions script as output.
 
 The configuration file is built of blocks that look like this:
 
@@ -59,7 +60,7 @@ for the auto complete process.
 
 You can save a sample YAML file by running:
 
-```
+```bash
 $ completely init
 ```
 
@@ -67,37 +68,34 @@ This will generate a file named `completely.yaml` with this content:
 
 ```yaml
 mygit:
+- -h
+- -v
 - --help
 - --version
-- status
 - init
-- commit
+- status
+
+mygit init:
+- --bare
+- <directory>
 
 mygit status:
 - --help
 - --verbose
 - --branch
-- $(git branch 2> /dev/null)
+- -b
 
-mygit init:
-- --bare
-- <directory>
+mygit status*--branch: &branches
+- $(git branch --format='%(refname:short)' 2>/dev/null)
 
-mygit commit:
-- <file>
-- --help
-- --message
-- --all
-- -a
-- --quiet
-- -q
+mygit status*-b: *branches
 ```
 
 Each pattern in this configuration file will be checked against the user's
-input, and if the input **starts with** a matching pattern, the list that 
-follows it will be suggested as completions.
+input, and if the input matches the pattern, the list that follows it will be
+suggested as completions.
 
-Note that the suggested completions will not show flags (string that start with 
+Note that the suggested completions will not show flags (strings that start with 
 a hyphen `-`) unless the input ends with a hyphen.
 
 To generate the bash script, simply run:
@@ -169,7 +167,7 @@ branches to your suggestions, use the following:
 
 ```yaml
 mygit:
-- $(git branch 2> /dev/null)
+- $(git branch --format='%(refname:short)' 2>/dev/null)
 ```
 
 The `2> /dev/null` is used so that if the command is executed in a directory
@@ -186,10 +184,10 @@ mygit checkout:
 - -b
 
 mygit checkout*--branch:
-- $(git branch 2> /dev/null)
+- $(git branch --format='%(refname:short)' 2>/dev/null)
 
 mygit checkout*-b:
-- $(git branch 2> /dev/null)
+- $(git branch --format='%(refname:short)' 2>/dev/null)
 ```
 
 The above will suggest git branches for commands that end with `-b` or `--branch`.
@@ -202,11 +200,54 @@ mygit checkout:
 - -b
 
 mygit checkout*--branch: &branches
-- $(git branch 2> /dev/null)
+- $(git branch --format='%(refname:short)' 2>/dev/null)
 
 mygit checkout*-b: *branches
 ```
 
+### Alternative nested syntax
+
+Completely also supports an alternative nested syntax. You can generate this
+example by running:
+
+```bash
+$ completely init --nested
+```
+
+The example configuration below will generate the exact same script as the one
+shown at the beginning of this document.
+
+```yaml
+mygit:
+- -h
+- -v
+- --help
+- --version
+- init:
+  - --bare
+  - <directory>
+- status:
+  - --help
+  - --verbose
+  - +--branch: &branches
+    - $(git branch --format='%(refname:short)' 2>/dev/null)
+  - +-b: *branches
+```
+
+The rules here are as follows:
+
+- Each pattern (e.g., `mygit`) can have a mixed array of strings and hashes.
+- Strings and hash keys (e.e., `--help` and `init` respectively) will be used
+  as completion strings for that pattern.
+- Hashes may contain a nested mixed array of the same structure.
+- When a hash is provided, the hash key will be appended to the parent prefix.
+  In the example above, the `init` hash will create the pattern `mygit init`.
+- In order to provide a wildcard (like `mygit status*--branch` in the standard
+  configuration syntax), you can provide either a `*` or a `+` prefix to the
+  hash key (e.g., `+--branch` or `"*--branch"`). Note that when using a `*`, 
+  the hash key must be quoted since asterisks have special meaning in YAML.
+
+
 ## Using the generated completion scripts
 
 In order to enable the completions, simply source the generated script:
@@ -227,6 +268,8 @@ Alternatively, you can copy the script manually to one of these directories
 
 - `/usr/share/bash-completion/completions`
 - `/usr/local/etc/bash_completion.d`
+- `~/.local/share/bash-completion/completions`
+
 
 ## Testing and debugging completion scripts
 
@@ -265,6 +308,7 @@ puts completions.wrapper_function "custom_function_name"
 p completions.tester.test "mygit status "
 ```
 
+
 ## Completions in ZSH
 
 If you are using Oh-My-Zsh, bash completions should already be enabled,
@@ -277,6 +321,17 @@ autoload -Uz +X compinit && compinit
 autoload -Uz +X bashcompinit && bashcompinit
 ```
 
+## Customizing the `complete` command
+
+In case you wish to customize the `complete` command call in the generated
+script, you can do so by adding any additional flags to the `completely.yaml`
+configuration file using the special `completely_options` key. For example:
+
+```yaml
+completely_options:
+  complete_options: -o nosort
+```
+
 ## Contributing / Support
 
 If you experience any issue, have a question or a suggestion, or if you wish

data/lib/completely/cli.rb

@@ -1,10 +1,11 @@
 require 'mister_bin'
-require 'completely/version'
 require 'completely/commands/generate'
 require 'completely/commands/init'
 require 'completely/commands/install'
 require 'completely/commands/preview'
 require 'completely/commands/test'
+require 'completely/commands/uninstall'
+require 'completely/version'
 
 module Completely
   class CLI
@@ -18,6 +19,7 @@ module Completely
       runner.route 'generate',  to: Commands::Generate
       runner.route 'test',      to: Commands::Test
       runner.route 'install',   to: Commands::Install
+      runner.route 'uninstall', to: Commands::Uninstall
 
       runner
     end

data/lib/completely/commands/init.rb

@@ -5,9 +5,11 @@ module Completely
     class Init < Base
       help 'Create a new sample YAML configuration file'
 
-      usage 'completely init [CONFIG_PATH]'
+      usage 'completely init [--nested] [CONFIG_PATH]'
       usage 'completely init (-h|--help)'
 
+      option '-n --nested', 'Generate a nested configuration'
+
       param_config_path
       environment_config_path
 
@@ -24,8 +26,15 @@ module Completely
         @sample ||= File.read sample_path
       end
 
+      def nested?
+        args['--nested']
+      end
+
       def sample_path
-        @sample_path ||= File.expand_path '../templates/sample.yaml', __dir__
+        @sample_path ||= begin
+          sample_name = nested? ? 'sample-nested' : 'sample'
+          File.expand_path "../templates/#{sample_name}.yaml", __dir__
+        end
       end
     end
   end

data/lib/completely/commands/install.rb

@@ -21,12 +21,12 @@ module Completely
 
       def run
         if args['--dry']
-          puts installer.command_string
+          puts installer.install_command_string
           return
         end
 
         success = installer.install force: args['--force']
-        raise InstallError, "Failed running command:\nnb`#{installer.command_string}`" unless success
+        raise InstallError, "Failed running command:\nnb`#{installer.install_command_string}`" unless success
 
         say "Saved m`#{installer.target_path}`"
         say 'You may need to restart your session to test it'

data/lib/completely/commands/uninstall.rb

@@ -0,0 +1,39 @@
+require 'completely/commands/base'
+
+module Completely
+  module Commands
+    class Uninstall < Base
+      summary 'Uninstall a bash completion script'
+
+      help <<~HELP
+        This command will remove the completion script for the specified program from all the bash completion directories.
+      HELP
+
+      usage 'completely uninstall PROGRAM [--dry]'
+      usage 'completely uninstall (-h|--help)'
+
+      option '-d --dry', 'Show the uninstallation command but do not run it'
+
+      param 'PROGRAM', 'Name of the program the completions are for.'
+
+      def run
+        if args['--dry']
+          puts installer.uninstall_command_string
+          return
+        end
+
+        success = installer.uninstall
+        raise InstallError, "Failed running command:\nnb`#{installer.uninstall_command_string}`" unless success
+
+        say 'Done'
+        say 'You may need to restart your session to test it'
+      end
+
+    private
+
+      def installer
+        Installer.new program: args['PROGRAM']
+      end
+    end
+  end
+end

data/lib/completely/completions.rb

@@ -7,23 +7,20 @@ module Completely
 
     class << self
       def load(config_path, function_name: nil)
-        begin
-          data = YAML.load_file config_path, aliases: true
-        rescue ArgumentError
-          # :nocov:
-          data = YAML.load_file config_path
-          # :nocov:
-        end
-
-        new data, function_name: function_name
+        config = Config.load config_path
+        new config, function_name: function_name
       end
     end
 
     def initialize(config, function_name: nil)
-      @config = config
+      @config = config.is_a?(Config) ? config : Config.new(config)
       @function_name = function_name
     end
 
+    def flat_config
+      @flat_config ||= config.flat_config
+    end
+
     def patterns
       @patterns ||= patterns!
     end
@@ -54,7 +51,7 @@ module Completely
   private
 
     def patterns!
-      result = config.map do |text, completions|
+      result = flat_config.map do |text, completions|
         Pattern.new text, completions, pattern_function_name
       end
 
@@ -70,7 +67,7 @@ module Completely
     end
 
     def command
-      @command ||= config.keys.first.split.first
+      @command ||= flat_config.keys.first.split.first
     end
 
     def function_name
@@ -84,5 +81,12 @@ module Completely
     def pattern_prefixes
       patterns.map(&:prefix)
     end
+
+    def complete_options_line
+      options = config.options[:complete_options]
+      return nil if options.nil? || options.strip.empty?
+
+      "#{options} "
+    end
   end
 end

data/lib/completely/config.rb

@@ -0,0 +1,70 @@
+module Completely
+  class Config
+    attr_reader :config, :options
+
+    class << self
+      def load(config_path)
+        begin
+          config = YAML.load_file config_path, aliases: true
+        rescue ArgumentError
+          # :nocov:
+          config = YAML.load_file config_path
+          # :nocov:
+        end
+
+        new config
+      end
+    end
+
+    def initialize(config)
+      @options = config.delete('completely_options')&.transform_keys(&:to_sym) || {}
+      @config = config
+    end
+
+    def flat_config
+      result = {}
+
+      config.each do |root_key, root_list|
+        result.merge! process_key(root_key, root_list)
+      end
+
+      result
+    end
+
+  private
+
+    def process_key(prefix, list)
+      result = {}
+      result[prefix] = collect_immediate_children list
+      result.merge! process_nested_items(prefix, list)
+      result
+    end
+
+    def collect_immediate_children(list)
+      list.map do |item|
+        x = item.is_a?(Hash) ? item.keys.first : item
+        x.gsub(/^[*+]/, '')
+      end
+    end
+
+    def process_nested_items(prefix, list)
+      result = {}
+
+      list.each do |item|
+        next unless item.is_a? Hash
+
+        nested_prefix = generate_nested_prefix(prefix, item)
+        nested_list = item.values.first
+        result.merge!(process_key(nested_prefix, nested_list))
+      end
+
+      result
+    end
+
+    def generate_nested_prefix(prefix, item)
+      appended_prefix = item.keys.first.gsub(/^\+/, '*')
+      appended_prefix = " #{appended_prefix}" unless appended_prefix.start_with? '*'
+      "#{prefix}#{appended_prefix}"
+    end
+  end
+end

data/lib/completely/installer.rb

@@ -11,17 +11,27 @@ module Completely
       @target_directories ||= %W[
         /usr/share/bash-completion/completions
         /usr/local/etc/bash_completion.d
+        #{Dir.home}/.local/share/bash-completion/completions
         #{Dir.home}/.bash_completion.d
       ]
     end
 
-    def command
+    def install_command
       result = root_user? ? [] : %w[sudo]
       result + %W[cp #{script_path} #{target_path}]
     end
 
-    def command_string
-      command.join ' '
+    def install_command_string
+      install_command.join ' '
+    end
+
+    def uninstall_command
+      result = root_user? ? [] : %w[sudo]
+      result + %w[rm -f] + target_directories.map { |dir| "#{dir}/#{program}" }
+    end
+
+    def uninstall_command_string
+      uninstall_command.join ' '
     end
 
     def target_path
@@ -41,7 +51,11 @@ module Completely
         raise InstallError, "File exists: m`#{target_path}`"
       end
 
-      system(*command)
+      system(*install_command)
+    end
+
+    def uninstall
+      system(*uninstall_command)
     end
 
   private

data/lib/completely/templates/sample-nested.yaml

@@ -0,0 +1,14 @@
+mygit:
+- -h
+- -v
+- --help
+- --version
+- init:
+  - --bare
+  - <directory>
+- status:
+  - --help
+  - --verbose
+  - +--branch: &branches
+    - $(git branch --format='%(refname:short)' 2>/dev/null)
+  - +-b: *branches

data/lib/completely/templates/sample.yaml

@@ -1,25 +1,22 @@
 mygit:
+- -h
+- -v
 - --help
 - --version
-- status
 - init
-- commit
+- status
+
+mygit init:
+- --bare
+- <directory>
 
 mygit status:
 - --help
 - --verbose
 - --branch
-- $(git branch 2> /dev/null)
+- -b
 
-mygit init:
-- --bare
-- <directory>
+mygit status*--branch: &branches
+- $(git branch --format='%(refname:short)' 2>/dev/null)
 
-mygit commit:
-- <file>
-- --help
-- --message
-- --all
-- -a
-- --quiet
-- -q
+mygit status*-b: *branches

data/lib/completely/templates/template.erb

@@ -11,7 +11,7 @@
 
   if [[ "${cur:0:1}" == "-" ]]; then
     echo "$words"
-  
+
   else
     for word in $words; do
       [[ "${word:0:1}" != "-" ]] && result+=("$word")
@@ -38,12 +38,12 @@
 % patterns.each do |pattern|
 % next if pattern.empty?
     <%= pattern.case_string %>)
-      while read -r; do COMPREPLY+=( "$REPLY" ); done < <( compgen <%= pattern.compgen %> -- "$cur" )
+      while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen <%= pattern.compgen %> -- "$cur")
       ;;
 
 % end
   esac
 } &&
-complete -F <%= function_name %> <%= command %>
+  complete <%= complete_options_line %>-F <%= function_name %> <%= command %>
 
 # ex: filetype=sh

data/lib/completely/version.rb

@@ -1,3 +1,3 @@
 module Completely
-  VERSION = '0.6.0'
+  VERSION = '0.7.1'
 end

data/lib/completely.rb

@@ -1,9 +1,5 @@
-if ENV['BYEBUG']
-  require 'byebug'
-  require 'lp'
-end
-
 require 'completely/exceptions'
+require 'completely/config'
 require 'completely/pattern'
 require 'completely/completions'
 require 'completely/tester'

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: completely
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.1
 platform: ruby
 authors:
 - Danny Ben Shitrit
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-06-23 00:00:00.000000000 Z
+date: 2025-04-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: colsole
@@ -61,10 +60,13 @@ files:
 - lib/completely/commands/install.rb
 - lib/completely/commands/preview.rb
 - lib/completely/commands/test.rb
+- lib/completely/commands/uninstall.rb
 - lib/completely/completions.rb
+- lib/completely/config.rb
 - lib/completely/exceptions.rb
 - lib/completely/installer.rb
 - lib/completely/pattern.rb
+- lib/completely/templates/sample-nested.yaml
 - lib/completely/templates/sample.yaml
 - lib/completely/templates/template.erb
 - lib/completely/templates/tester-template.erb
@@ -78,7 +80,6 @@ metadata:
   changelog_uri: https://github.com/DannyBen/completely/blob/master/CHANGELOG.md
   source_code_uri: https://github.com/DannyBen/completely
   rubygems_mfa_required: 'true'
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -93,8 +94,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.14
-signing_key: 
+rubygems_version: 3.6.3
 specification_version: 4
 summary: Bash Completions Generator
 test_files: []