completely 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd3ae4ec92d7318bd4ef32fdd465d9bff3341931f5f965d2db8f263c1b95e38b
-  data.tar.gz: 01ccb2fa2e1f050b7a45944b552590fad6aab9bafc90ef4cb98b8d6284200392
+  metadata.gz: 54ee6b84395ab00c6d0fdde61065b9843b178947a7569cea41cead7b149ef55b
+  data.tar.gz: 3dd72641e530c42b0642b5861f1b38c219b5931846ed2da7fb20648563954094
 SHA512:
-  metadata.gz: fd06256b9cb4c42364d118ea1392b180ef662e98b2ea9c6b24ca815f5fa5cf1f16d6c0a6792090c9bc5f376ab7dfb04e9b8c732cb83292140acb59676d6090a9
-  data.tar.gz: b1985849259627803ebe3f7c56b4adc98137456b172fb36cbf1379b4677257dca6cc671d85a12106596fb246de02aad07c5e9d51c5dd0abc7301518d9b7529b2
+  metadata.gz: b8f2ffa6f7f8303e827c8bb894accf1d97ae0e012f46d495dcfab280836ffd5ae8aa0418b95450a41642bb1fcabb9b2ee2d54ef037f88e43f048a6014ae4acff
+  data.tar.gz: 94f01f524b7ffc8bf5ca910594e203f1579bccc0910795ca2a74cf64af5838dab1b023a250f017da9c0c2798c68ac71149657c14a3f587a32a30268843fdd815

data/README.md

@@ -2,41 +2,48 @@
 
 [![Gem Version](https://badge.fury.io/rb/completely.svg)](https://badge.fury.io/rb/completely)
 [![Build Status](https://github.com/DannyBen/completely/workflows/Test/badge.svg)](https://github.com/DannyBen/completely/actions?query=workflow%3ATest)
+[![Maintainability](https://api.codeclimate.com/v1/badges/6c021b8309ac796c3919/maintainability)](https://codeclimate.com/github/DannyBen/completely/maintainability)
 
 ---
 
 Completely is a command line utility and a Ruby library that lets you generate
 bash completion scripts from simple YAML configuration.
 
-This tool is for you it:
+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.
 
 ---
 
 
 ## Install
 
-```
+```bash
 $ gem install completely
 ```
 
-## Usage
+## 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.
 
-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:
 
 ```
@@ -57,6 +64,7 @@ mygit status:
 - --help
 - --verbose
 - --branch
+- $(git branch 2> /dev/null)
 
 mygit init:
 - --bare
@@ -78,7 +86,7 @@ follows it will be suggested as completions.
 
 To generate the bash script, simply run:
 
-```
+```bash
 $ completely generate
 
 # or, to just preview it without saving:
@@ -87,37 +95,105 @@ $ completely preview
 
 For more options (like setting input/output path), run
 
-```
+```bash
 $ 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
+
+## Using the generated completion scripts
 
 In order to enable the completions, simply source the generated script:
 
-```
+```bash
 $ 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).
 
+## Using from within Ruby code
+
+```ruby
+require 'completely'
+
+# Load from file
+completions = Completely::Completions.load "input.yaml"
+
+# Or, from a hash
+input = {
+  "mygit" => %w[--help --version status init commit],
+  "mygit status" => %w[--help --verbose --branch]
+}
+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"
+```
+
 
 ## Contributing / Support
 
@@ -128,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/cli.rb

@@ -1,6 +1,6 @@
 require 'mister_bin'
-require 'completely/command'
 require 'completely/version'
+require 'completely/command'
 
 module Completely
   class CLI

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.0"
+  VERSION = "0.2.0"
 end

data/lib/completely.rb

@@ -1,9 +1,7 @@
-require 'requires'
-
 if ENV['BYEBUG']
   require '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.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Danny Ben Shitrit
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-07-20 00:00:00.000000000 Z
+date: 2021-09-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: colsole
@@ -38,20 +38,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.7'
-- !ruby/object:Gem::Dependency
-  name: requires
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.1'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.1'
 description: Generate bash completion scripts using simple YAML configuration
 email: db@dannyben.com
 executables:
@@ -65,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
@@ -87,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.25
 signing_key: 
 specification_version: 4
 summary: Bash Completions Generator