completely 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba5123d5b0bf95ed7ea2140188a6079e0510456a754d5fd93830df1382862274
-  data.tar.gz: 0f98b90e1515d753b94817932916aad966b8b3f81ede79f1bbb40a898b82662e
+  metadata.gz: '0949e2f6df08b0582dc2efd748523bf63732f8c59a5ad41bd479e444568304d2'
+  data.tar.gz: fe1bf68cbec745eeed052c218f77e42040ae378c36fa99ad36e5d45c6c64a202
 SHA512:
-  metadata.gz: e3618affd00e4a624b288ae7c37fd0d857fd9cf0672d6bcc8c558eb7870e2e3001e86a1c6997bc177def3b245bdc1142287539d99423dc175f6e208a9bf8a3b9
-  data.tar.gz: a34bc567cbf492e437168afeb0a509f392eb1600a49622136d50728a936c024ad90e757d3a3ede18b0b7204302b09e08567054c73f75ea03fd3cdea9d39074e3
+  metadata.gz: a80c321109ac11ec6cc3be603d713e460fb838818c1fe2c56c2fdde9e903f1677fb0027a4dbfc1f0605123658181aa067b48f167c4061221bd85c754c0006f1b
+  data.tar.gz: a0d7283193046401a94971fcb7cd5f6e58b10087f6fe3b346f5a8d414c0f1252ef59cf9ee6f2ac338618652d54003e6cea9442948806a7b50832fa3c2bccc868

data/README.md

@@ -13,7 +13,10 @@ This tool is for you if:
 
 1. You develop your own command line tools.
 2. Your life feels empty without bash completions.
-3. Bash completion scripts scare you.
+3. Bash completion scripts seem overly complex to you.
+
+Note that if you are building bash command line scripts with [bashly][bashly],
+then this functionality is already integrated with it.
 
 ---
 
@@ -29,15 +32,18 @@ $ gem install completely
 The `completely` command line works with a simple YAML configuration file as
 input, and generates a bash completions script as output.
 
-The configuration file is built like this:
+The configuration file is built of blocks that look like this:
 
 ```yaml
 pattern:
-  - --argument
-  - --param
-  - command
+- --argument
+- --param
+- command
 ```
 
+Each pattern contains an array of words (or functions) that will be suggested
+for the auto complete process.
+
 You can save a sample YAML file by running:
 
 ```
@@ -58,6 +64,7 @@ mygit status:
 - --help
 - --verbose
 - --branch
+- $(git branch 2> /dev/null)
 
 mygit init:
 - --bare
@@ -92,21 +99,66 @@ For more options (like setting input/output path), run
 $ completely --help
 ```
 
-### Suggesting files and directories
+### Suggesting files, directories and other bash built-ins
 
-You may have noticed that the sample file contains two special entries:
+In addition to specifying a simple array of completion words, you may use
+the special syntax `<..>` to suggest more advanced functions.
 
-- `<file>`
-- `<directory>`
+```yaml
+pattern:
+- <file>
+- <directory>
+```
 
-These patterns will add the list of files and directories
-(when `<file>` is used) or just directories (when `<directory` is used) to
+These suggestions will add the list of files and directories
+(when `<file>` is used) or just directories (when `<directory>` is used) to
 the list of suggestions.
 
+You may use any of the below keywords to add additional suggestions:
+
+| Keyword       | Meaning
+|---------------|---------------------
+| `<alias>`     | Alias names
+| `<arrayvar>`  | Array variable names
+| `<binding>`   | Readline key binding names
+| `<builtin>`   | Names of shell builtin commands
+| `<command>`   | Command names
+| `<directory>` | Directory names
+| `<disabled>`  | Names of disabled shell builtins
+| `<enabled>`   | Names of enabled shell builtins
+| `<export>`    | Names of exported shell variables
+| `<file>`      | File names
+| `<function>`  | Names of shell functions
+| `<group>`     | Group names
+| `<helptopic>` | Help topics as accepted by the help builtin
+| `<hostname>`  | Hostnames, as taken from the file specified by the HOSTFILE shell variable
+| `<job>`       | Job names
+| `<keyword>`   | Shell reserved words
+| `<running>`   | Names of running jobs
+| `<service>`   | Service names
+| `<signal>`    | Signal names
+| `<stopped>`   | Names of stopped jobs
+| `<user>`      | User names
+| `<variable>`  | Names of all shell variables
+
 For those interested in the technical details, any word between `<...>` will
 simply be added using the [`compgen -A action`][compgen] function, so you can 
 in fact use any of its supported arguments.
 
+### Suggesting custom dynamic suggestions
+
+You can also use any command that outputs a whitespace-delimited list as a
+suggestions list, by wrapping it in `$(..)`. For example, in order to add git
+branches to your suggestions, use the following:
+
+```yaml
+mygit:
+- $(git branch 2> /dev/null)
+```
+
+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.
+
 
 ## Using the generated completion scripts
 
@@ -136,6 +188,10 @@ completions = Completely::Completions.new input
 
 # Generate the script
 puts completions.script
+
+# Or, generate a function that echos the script
+puts completions.wrapper_function
+puts completions.wrapper_function "custom_function_name"
 ```
 
 
@@ -148,3 +204,4 @@ to contribute, feel free to [open an issue][issues].
 
 [issues]: https://github.com/DannyBen/completely/issues
 [compgen]: https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion-Builtins.html
+[bashly]: https://bashly.dannyb.co/

data/lib/completely/command.rb

@@ -5,7 +5,7 @@ module Completely
 
     usage "completely new [CONFIG_PATH]"
     usage "completely preview [CONFIG_PATH --function NAME]"
-    usage "completely generate [CONFIG_PATH OUTPUT_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"
@@ -13,16 +13,18 @@ module Completely
     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 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 input.yaml output.sh -f _my_completions"
+    example "completely generate -w give_comps -f my_completions"
 
     def new_command
       if File.exist? config_path
@@ -35,11 +37,15 @@ module Completely
 
     def preview_command
       puts script
+      syntax_warning unless completions.valid?
     end
     
     def generate_command
-      File.write output_path, script
+      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
@@ -64,9 +70,18 @@ module Completely
       @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/completions.rb

@@ -15,12 +15,37 @@ module Completely
       @config, @function_name = config, function_name
     end
 
+    def patterns
+      @patterns ||= patterns!
+    end
+
+    def valid?
+      pattern_prefixes.uniq.count == 1
+    end
+
     def script
       ERB.new(template, trim_mode: '%-').result(binding)
     end
 
+    def wrapper_function(name = nil)
+      name ||= "send_completions"
+
+      script_lines = script.split("\n").map do |line|
+        clean_line = line.gsub("'") { "\\'" }
+        %Q[  echo $'#{clean_line}']
+      end.join("\n")
+
+      "#{name}() {\n#{script_lines}\n}"
+    end
+
   private
 
+    def patterns!
+      config.map do |text, completions|
+        Pattern.new text, completions
+      end.sort_by { |pattern| -pattern.length }
+    end
+
     def template_path
       @template_path ||= File.expand_path("template.erb", __dir__)
     end
@@ -30,16 +55,16 @@ module Completely
     end
 
     def command
-      @command ||= config.keys.first
-    end
-
-    def patterns
-      @patterns ||= config.to_a.sort_by { |k, v| -k.size }.to_h
+      @command ||= config.keys.first.split(' ').first
     end
 
     def function_name
       @function_name ||= "_#{command}_completions"
     end
 
+    def pattern_prefixes
+      patterns.map &:prefix
+    end
+
   end
 end

data/lib/completely/pattern.rb

@@ -0,0 +1,50 @@
+module Completely
+  class Pattern
+    attr_reader :text, :completions
+
+    def initialize(text, completions)
+      @text = text
+      @completions = completions || []
+    end
+
+    def length
+      @length ||= text.size
+    end
+
+    def empty?
+      completions.empty?
+    end
+
+    def words
+      @words ||= completions.reject { |w| w =~ /^<.*>$/ }
+    end
+
+    def actions
+      @actions ||= completions.filter_map do |word|
+        action = word[/^<(.+)>$/, 1]
+        "-A #{action}" if action
+      end
+    end
+
+    def prefix
+      text.split(' ')[0]
+    end
+
+    def text_without_prefix
+      text.split(' ')[1..-1].join ' '
+    end
+
+    def compgen
+      @compgen ||= compgen!
+    end
+
+  private
+
+    def compgen!
+      result = []
+      result << %Q[#{actions.join ' '}] if actions.any?
+      result << %Q[-W "#{words.join ' '}"] if words.any?
+      result.any? ? result.join(' ') : nil
+    end
+  end
+end

data/lib/completely/sample.yaml

@@ -9,6 +9,7 @@ mygit status:
 - --help
 - --verbose
 - --branch
+- $(git branch 2> /dev/null)
 
 mygit init:
 - --bare

data/lib/completely/template.erb

@@ -5,14 +5,12 @@
 # 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, words|
-% next unless words
-% clean_words = words.reject { |w| w =~ /^<.*>$/ }.join " "
-% functions = words.filter_map { |w| func = w[/^<(.+)>$/, 1] ; "-A #{func}" if func }
-% flags = functions.any? ? "#{functions.join ' '} -W" : "-W"
-    '<%= pattern %>'*) COMPREPLY=($(compgen <%= flags %> "<%= clean_words %>" -- "$cur")) ;;
+  case "$comp_line" in
+% patterns.each do |pattern|
+% next if pattern.empty?
+    '<%= pattern.text_without_prefix %>'*) COMPREPLY=($(compgen <%= pattern.compgen %> -- "$cur")) ;;
 % end
   esac
 }

data/lib/completely/version.rb

@@ -1,3 +1,3 @@
 module Completely
-  VERSION = "0.1.1"
+  VERSION = "0.3.0"
 end

data/lib/completely.rb

@@ -3,5 +3,5 @@ if ENV['BYEBUG']
   require 'lp'
 end
 
-# requires 'completely'
+require 'completely/pattern'
 require 'completely/completions'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: completely
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Danny Ben Shitrit
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-07-20 00:00:00.000000000 Z
+date: 2022-01-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: colsole
@@ -51,6 +51,7 @@ files:
 - lib/completely/cli.rb
 - lib/completely/command.rb
 - lib/completely/completions.rb
+- lib/completely/pattern.rb
 - lib/completely/sample.yaml
 - lib/completely/template.erb
 - lib/completely/version.rb
@@ -73,7 +74,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.16
+rubygems_version: 3.2.15
 signing_key: 
 specification_version: 4
 summary: Bash Completions Generator