completely 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f19143967a28107018c600c7f302bfccd2cf34d70a88be661f68e340e515c07
-  data.tar.gz: 6037bb0f6944627f97abf37c51f76d1db213b42402db092fa6c36fb257892c22
+  metadata.gz: c23c2c1184a5c69443fdd5dad73e60ba0820bf9b5f9f6eac75b111497688e16d
+  data.tar.gz: baa8d260f6837fd8594ab868fe5eadf503df0b8dedc53b29abb6d89bbb09bf4c
 SHA512:
-  metadata.gz: c46ac169ab59595c67d3d8a8c320ea7fb56e78715fbc2dd55e4e20534c8543c66f0b62dda01a6802bbaf9f071a5ebd7ffa55a17c70443e05bba8ab8c3bedce71
-  data.tar.gz: ac9a7a7934e115957271ec1e5cc736c0df29368f18da6f9eb409069f9690cb2594d6b9bdbf6d4fd18388ce79f7285e66a357d4bb241083ca083fd57102c95746
+  metadata.gz: ec8447973b868405cbe625496331664adfd3caf70b64bffb53cc3c6bbfd923081c9a27f561addb6e2260974664e8dfbf01ba1776cc996793933f944a2384867c
+  data.tar.gz: 718ba798f5c82c7c80a69afde32f66f610f45a874fb48ed2614f4672c359a34ba65436a30c8dc32754fa678bf324e9db67f45eac88b9277c70dd6bbe0f15b3af

data/README.md

@@ -27,6 +27,13 @@ then this functionality is already integrated with it.
 $ gem install completely
 ```
 
+or with homebrew:
+
+```bash
+$ brew install brew-gem
+$ brew gem install completely
+````
+
 ## Using the `completely` command line
 
 The `completely` command line works with a simple YAML configuration file as
@@ -47,7 +54,7 @@ for the auto complete process.
 You can save a sample YAML file by running:
 
 ```
-$ completely new
+$ completely init
 ```
 
 This will generate a file named `completely.yaml` with this content:
@@ -159,6 +166,37 @@ mygit:
 The `2> /dev/null` is used so that if the command is executed in a directory
 without a git repository, it will still behave as expected.
 
+### Suggesting flag arguments
+
+Adding a `*` wildcard in the middle of a pattern can be useful for suggesting
+arguments for flags. For example:
+
+```yaml
+mygit checkout:
+- --branch
+- -b
+
+mygit checkout*--branch:
+- $(git branch 2> /dev/null)
+
+mygit checkout*-b:
+- $(git branch 2> /dev/null)
+```
+
+The above will suggest git branches for commands that end with `-b` or `--branch`.
+To avoid code duplication, you may use YAML aliases, so the above can also be
+written like this:
+
+```yaml
+mygit checkout:
+- --branch
+- -b
+
+mygit checkout*--branch: &branches
+- $(git branch 2> /dev/null)
+
+mygit checkout*-b: *branches
+```
 
 ## Using the generated completion scripts
 
@@ -168,8 +206,24 @@ In order to enable the completions, simply source the generated script:
 $ source completely.bash
 ```
 
-You may wish to add this to your `~/.bashrc` file to enable this for future
-sessions (just be sure to use absolute path).
+In order to load these completions on startup, you may want to place them in 
+the completions directory of your operating system, which can be either of
+these (whichever exists):
+
+- `/usr/share/bash-completion/completions`
+- `/usr/local/etc/bash_completion.d`
+
+## Testing and debugging completion scripts
+
+You can use the built in completions script tester by running `completely test`.
+
+This command lets you test any completions script, whether it was generated by
+completely or not.
+
+In addition, you can set the `COMPLETELY_DEBUG` environment variable to any value
+in order to generate scripts with some additional debugging functionality. Run
+`completely generate --help` for additional information.
+
 
 ## Using from within Ruby code
 
@@ -192,6 +246,9 @@ puts completions.script
 # Or, generate a function that echos the script
 puts completions.wrapper_function
 puts completions.wrapper_function "custom_function_name"
+
+# Or, test the completions with the Tester object
+p completions.tester.test "mygit status "
 ```
 
 

data/lib/completely/cli.rb

@@ -1,11 +1,23 @@
 require 'mister_bin'
+require 'completely/commands/init'
+require 'completely/commands/preview'
+require 'completely/commands/generate'
+require 'completely/commands/test'
 require 'completely/version'
-require 'completely/command'
 
 module Completely
   class CLI
     def self.runner
-      MisterBin::Runner.new handler: Command
+      runner = MisterBin::Runner.new version: Completely::VERSION,
+        header: "Completely - Bash Completions Generator",
+        footer: "Run !txtpur!completely COMMAND --help!txtrst! for more information"
+
+      runner.route 'init',      to: Commands::Init
+      runner.route 'preview',   to: Commands::Preview
+      runner.route 'generate',  to: Commands::Generate
+      runner.route 'test',      to: Commands::Test
+
+      runner
     end
   end
 end

data/lib/completely/commands/base.rb

@@ -0,0 +1,53 @@
+require 'mister_bin'
+
+module Completely
+  module Commands
+    class Base < MisterBin::Command
+
+      class << self
+        def param_config_path
+          param "CONFIG_PATH", "Path to the YAML configuration file [default: completely.yaml]\nCan also be set by an environment variable"
+        end
+
+        def option_function
+          option "-f --function NAME", "Modify the name of the function in the generated script"
+        end
+
+        def environment_config_path
+          environment "COMPLETELY_CONFIG_PATH", "Path to a completely configuration file [default: completely.yaml]"
+        end
+
+        def environment_debug
+          environment "COMPLETELY_DEBUG", "It not empty, the generated script will include an additional debugging snippet that outputs the compline and current word to a text file when a completion is requested"
+        end
+      end
+
+    protected
+
+      def script
+        @script ||= completions.script
+      end
+
+      def completions
+        @completions ||= Completions.load(config_path, function_name: args['--function'])
+      end
+
+      def config_path
+        @config_path ||= args['CONFIG_PATH'] || ENV['COMPLETELY_CONFIG_PATH'] || 'completely.yaml'
+      end
+
+      def script_path
+        @script_path ||= args['SCRIPT_PATH'] || ENV['COMPLETELY_SCRIPT_PATH'] || "#{config_basename}.bash"
+      end
+
+      def config_basename
+        File.basename config_path, File.extname(config_path)
+      end
+
+      def syntax_warning
+        say! "\n!txtred!WARNING:\nYour configuration is invalid."
+        say! "!txtred!All patterns must start with the same word."
+      end
+    end
+  end
+end

data/lib/completely/commands/generate.rb

@@ -0,0 +1,37 @@
+require 'completely/commands/base'
+
+module Completely
+  module Commands
+    class Generate < Base
+      help "Generate the bash completion script to a file"
+
+      usage "completely generate [CONFIG_PATH SCRIPT_PATH --function NAME --wrap NAME]"
+      usage "completely generate (-h|--help)"
+
+      option_function
+      option "-w --wrap NAME", "Wrap the completion script inside a function that echos the script. This is useful if you wish to embed it directly in your script"
+
+      param_config_path
+      param "SCRIPT_PATH", "Path to the output bash script. When not provided, the name of the input file will be used with a .bash extension\nCan also be set by an environment variable"
+
+      environment_config_path
+      environment "COMPLETELY_SCRIPT_PATH", "Path to the output bash script"
+      environment_debug
+
+      def run
+        wrap = args['--wrap']
+        output = wrap ? wrapper_function(wrap) : script
+        File.write script_path, output
+        say "Saved !txtpur!#{script_path}"
+        syntax_warning unless completions.valid?
+      end
+
+    private
+
+      def wrapper_function(wrapper_name)
+        completions.wrapper_function wrapper_name
+      end
+
+    end
+  end
+end

data/lib/completely/commands/init.rb

@@ -0,0 +1,35 @@
+require 'completely/commands/base'
+
+module Completely
+  module Commands
+    class Init < Base
+      help "Create a new sample YAML configuration file"
+
+      usage "completely init [CONFIG_PATH]"
+      usage "completely init (-h|--help)"
+
+      param_config_path
+      environment_config_path
+
+      def run
+        if File.exist? config_path
+          raise "File already exists: #{config_path}"
+        else
+          File.write config_path, sample
+          say "Saved !txtpur!#{config_path}"
+        end
+      end
+
+    private
+
+      def sample
+        @sample ||= File.read sample_path
+      end
+
+      def sample_path
+        @sample_path ||= File.expand_path "../templates/sample.yaml", __dir__
+      end
+
+    end
+  end
+end

data/lib/completely/commands/preview.rb

@@ -0,0 +1,22 @@
+require 'completely/commands/base'
+
+module Completely
+  module Commands
+    class Preview < Base
+      help "Generate the bash completion script to STDOUT"
+
+      usage "completely preview [CONFIG_PATH --function NAME]"
+      usage "completely preview (-h|--help)"
+
+      option_function
+      param_config_path
+      environment_config_path
+      environment_debug
+
+      def run
+        puts script
+        syntax_warning unless completions.valid?
+      end
+    end
+  end
+end

data/lib/completely/commands/test.rb

@@ -0,0 +1,69 @@
+require 'completely/commands/base'
+
+module Completely
+  module Commands
+    class Test < Base
+      summary "Test completions"
+
+      help <<~EOF
+        This command can be used to test that any completion script (either generated by compeltely or not) responds with the right completions.
+
+        In order to test on a completely configuration file other than 'completely.yaml', set the COMPLETELY_CONFIG_PATH environemnt variable.
+
+        In order to test on an arbitrary completions script, set the COMPLETELY_SCRIPT_PATH and optionally the COMPLETELY_SCRIPT_FUNCTION environment variables.
+      EOF
+
+      usage "completely test COMPLINE"
+      usage "completely test (-h|--help)"
+
+      param "COMPLINE", "The command to test completions for. This will be handled as if a TAB was pressed immediately at the end of it, so the last word is considered the active cursor. If you wish to complete for the next word instead, end your command with a space."
+
+      environment_config_path
+      environment "COMPLETELY_SCRIPT_PATH", "Path to a completions script. When set, this script will be tested instead of the completely configuration file"
+      environment "COMPLETELY_SCRIPT_FUNCTION", "The main completion function to call when using a custom script. If not set, the basename of the script path will be used, prefixed by an underscore"
+      environment_debug
+
+      example %q[completely test "mygit pu"]
+      example %q[completely test "mygit pull "]
+      example <<~EOF
+        COMPLETELY_SCRIPT_PATH=/usr/share/bash-completion/completions/chown \\
+          completely test "chown --"
+        EOF
+
+      attr_reader :config, :script_path, :script_function
+
+      def run
+        set_vars
+        puts tester.test(compline).join "\n"
+      end
+
+    private
+
+      def compline
+        args['COMPLINE']
+      end
+
+      def tester
+        if config
+          completions = Completions.load config
+          completions.tester
+        else
+          Tester.new script_path: script_path, function_name: script_function
+        end
+      end
+
+      def set_vars
+        if ENV['COMPLETELY_CONFIG_PATH']
+          @config = ENV['COMPLETELY_CONFIG_PATH']
+        elsif ENV['COMPLETELY_SCRIPT_PATH']
+          @script_path = ENV['COMPLETELY_SCRIPT_PATH']
+          @script_function = ENV['COMPLETELY_SCRIPT_FUNCTION'] || "_#{File.basename(script_path)}"
+        elsif File.exist? 'completely.yaml'
+          @config = 'completely.yaml'
+        else
+          raise "Please set the proper environment variables or run in a folder with completely.yaml"
+        end
+      end
+    end
+  end
+end

data/lib/completely/completions.rb

@@ -10,7 +10,9 @@ module Completely
         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
@@ -44,6 +46,10 @@ module Completely
       "#{name}() {\n#{script_lines}\n}"
     end
 
+    def tester
+      @tester ||= Tester.new script: script, function_name: function_name
+    end
+
   private
 
     def patterns!
@@ -53,7 +59,7 @@ module Completely
     end
 
     def template_path
-      @template_path ||= File.expand_path("template.erb", __dir__)
+      @template_path ||= File.expand_path("templates/template.erb", __dir__)
     end
 
     def template

data/lib/completely/pattern.rb

@@ -30,8 +30,18 @@ module Completely
       text.split(' ')[0]
     end
 
+    def case_string
+      if text_without_prefix.empty?
+        "*"
+      elsif text_without_prefix.include? "*" 
+        %Q['#{text_without_prefix.gsub "*", "'*'"}']
+      else
+        %Q['#{text_without_prefix}'*]
+      end
+    end
+
     def text_without_prefix
-      text.split(' ')[1..-1].join ' '
+      @text_without_prefix ||= text.split(' ')[1..-1].join ' '
     end
 
     def compgen

data/lib/completely/templates/template.erb

@@ -0,0 +1,33 @@
+# <%= "#{command} completion".ljust 56 %> -*- shell-script -*-
+
+# This bash completions script was generated by
+# completely (https://github.com/dannyben/completely)
+# Modifying it manually is not recommended
+
+<%= function_name %>() {
+  local cur compline
+  _init_completion -s || return
+
+  cur=${COMP_WORDS[COMP_CWORD]}
+  compline="${COMP_WORDS[@]:1:$COMP_CWORD-1}"
+
+% if ENV['COMPLETELY_DEBUG']
+  if [[ -n "$COMPLETELY_DEBUG" ]]; then
+    echo "compline: '$compline'" > 'completely-debug.txt'
+    echo "cur:      '$cur'" >> 'completely-debug.txt'
+  fi
+
+%end
+  case "$compline" in
+% patterns.each do |pattern|
+% next if pattern.empty?
+    <%= pattern.case_string %>)
+      COMPREPLY=($(compgen <%= pattern.compgen %> -- "$cur"))
+      ;;
+
+% end
+  esac
+} &&
+complete -F <%= function_name %> <%= command %>
+
+# ex: filetype=sh

data/lib/completely/templates/tester-template.erb

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+<%= script || %Q[source "#{absolute_script_path}"] %>
+
+# END OF COMPLETION SCRIPT
+
+source /usr/share/bash-completion/bash_completion
+COMP_WORDS=( <%= compline %> )
+COMP_LINE="<%= compline %>"
+COMP_POINT=${#COMP_LINE}
+COMP_CWORD=<%= cword %>
+
+<%= function_name %>
+echo "${COMPREPLY[*]}"

data/lib/completely/tester.rb

@@ -0,0 +1,48 @@
+require 'erb'
+require 'tempfile'
+
+module Completely
+  class Tester
+    attr_reader :script, :script_path, :function_name, :cword, :compline
+
+    def initialize(script: nil, script_path: nil, function_name: )
+      @script, @script_path, @function_name = script, script_path, function_name
+    end
+
+    def test(compline)
+      Tempfile.create "completely-tester" do |f|
+        f << tester_script(compline)
+        f.flush
+        `bash #{f.path}`
+      end.split " "
+    end
+
+    def tester_script(compline)
+      set_compline_vars compline
+      ERB.new(template, trim_mode: '%-').result(binding)
+    end
+
+  protected
+
+    def set_compline_vars(compline)
+      @compline = compline
+      @cword = compline.split(' ').size - 1
+      @cword += 1 if compline.end_with? ' '
+    end
+
+    def absolute_script_path
+      @absolute_script_path ||= begin
+        script_path ? File.expand_path(script_path) : nil
+      end
+    end
+
+    def template_path
+      @template_path ||= File.expand_path "templates/tester-template.erb", __dir__
+    end
+
+    def template
+      @template ||= File.read template_path
+    end
+
+  end
+end

data/lib/completely/version.rb

@@ -1,3 +1,3 @@
 module Completely
-  VERSION = "0.3.1"
+  VERSION = "0.4.0"
 end

data/lib/completely.rb

@@ -5,3 +5,4 @@ end
 
 require 'completely/pattern'
 require 'completely/completions'
+require 'completely/tester'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: completely
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Danny Ben Shitrit
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-02-20 00:00:00.000000000 Z
+date: 2022-05-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: colsole
@@ -49,11 +49,17 @@ files:
 - bin/completely
 - lib/completely.rb
 - lib/completely/cli.rb
-- lib/completely/command.rb
+- lib/completely/commands/base.rb
+- lib/completely/commands/generate.rb
+- lib/completely/commands/init.rb
+- lib/completely/commands/preview.rb
+- lib/completely/commands/test.rb
 - lib/completely/completions.rb
 - lib/completely/pattern.rb
-- lib/completely/sample.yaml
-- lib/completely/template.erb
+- lib/completely/templates/sample.yaml
+- lib/completely/templates/template.erb
+- lib/completely/templates/tester-template.erb
+- lib/completely/tester.rb
 - lib/completely/version.rb
 homepage: https://github.com/dannyben/completely
 licenses:
@@ -74,7 +80,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.15
+rubygems_version: 3.3.3
 signing_key: 
 specification_version: 4
 summary: Bash Completions Generator

data/lib/completely/command.rb

@@ -1,87 +0,0 @@
-module Completely
-  class Command < MisterBin::Command
-    help "Bash completion script generator"
-    version Completely::VERSION
-
-    usage "completely new [CONFIG_PATH]"
-    usage "completely preview [CONFIG_PATH --function NAME]"
-    usage "completely generate [CONFIG_PATH OUTPUT_PATH --function NAME --wrap NAME]"
-    usage "completely (-h|--help|--version)"
-
-    command "new", "Create a new sample YAML configuration file"
-    command "preview", "Generate the bash completion script to STDOUT"
-    command "generate", "Generate the bash completion script to a file"
-
-    option "-f --function NAME", "Modify the name of the function in the generated script"
-    option "-w --wrap NAME", "Wrap the completion script inside a function that echos the script. This is useful if you wish to embed it directly in your script"
-
-    param "CONFIG_PATH", "Path to the YAML configuration file"
-    param "OUTPUT_PATH", "Path to the output bash script"
-
-    example "completely new"
-    example "completely new input.yaml"
-    example "completely preview --function _my_completions"
-    example "completely generate"
-    example "completely generate input.yaml"
-    example "completely generate input.yaml output.sh -f _my_completions"
-    example "completely generate -w give_comps -f my_completions"
-
-    def new_command
-      if File.exist? config_path
-        raise "File already exists: #{config_path}"
-      else
-        File.write config_path, sample
-        say "Saved !txtpur!#{config_path}"
-      end
-    end
-
-    def preview_command
-      puts script
-      syntax_warning unless completions.valid?
-    end
-    
-    def generate_command
-      wrap = args['--wrap']
-      output = wrap ? wrapper_function(wrap) : script
-      File.write output_path, output
-      say "Saved !txtpur!#{output_path}"
-      syntax_warning unless completions.valid?
-    end
-
-  private
-
-    def config_path
-      @config_path ||= args['CONFIG_PATH'] || "completely.yaml"
-    end
-
-    def output_path
-      @output_path ||= args['OUTPUT_PATH'] || "completely.bash"
-    end
-
-    def sample
-      @sample ||= File.read(sample_path)
-    end
-
-    def sample_path
-      @sample_path ||= File.expand_path("sample.yaml", __dir__)
-    end
-
-    def script
-      @script ||= completions.script
-    end
-
-    def wrapper_function(wrapper_name)
-      completions.wrapper_function wrapper_name
-    end
-
-    def completions
-      @completions ||= Completions.load(config_path, function_name: args['--function'])
-    end
-
-    def syntax_warning
-      say! "\n!txtred!WARNING:\nYour configuration is invalid."
-      say! "!txtred!All patterns must start with the same word."
-    end
-
-  end
-end

data/lib/completely/template.erb

@@ -1,18 +0,0 @@
-#!/usr/bin/env bash
-
-# This bash completions script was generated by
-# completely (https://github.com/dannyben/completely)
-# Modifying it manually is not recommended
-<%= function_name %>() {
-  local cur=${COMP_WORDS[COMP_CWORD]}
-  local comp_line="${COMP_WORDS[@]:1}"
-
-  case "$comp_line" in
-% patterns.each do |pattern|
-% next if pattern.empty?
-    '<%= pattern.text_without_prefix %>'*) COMPREPLY=($(compgen <%= pattern.compgen %> -- "$cur")) ;;
-% end
-  esac
-}
-
-complete -F <%= function_name %> <%= command %>