Merge pull request #76 from DannyBen/add/nested-config-support

Add support for nested configuration

Author: DannyBen

README.md

@@ -40,10 +40,10 @@ or with Docker:
 $ alias completely='docker run --rm -it --user $(id -u):$(id -g) --volume "$PWD:/app" dannyben/completely'
 ```
 
-## Using the `completely` command line
+## Configuration syntax
 
-The `completely` command line works with a simple YAML configuration file as
-input, and generates a bash completions script as output.
+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,45 +59,42 @@ for the auto complete process.
 
 You can save a sample YAML file by running:
 
-```
+```bash
 $ completely init
 ```
 
 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 --format='%(refname:short)' 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:
@@ -207,6 +204,48 @@ mygit checkout*--branch: &branches
 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:

completely.gemspec

@@ -16,8 +16,8 @@ Gem::Specification.new do |s|
 
   s.required_ruby_version = '>= 3.0'
 
-  s.add_runtime_dependency 'colsole', '>= 0.8.1', '< 2'
-  s.add_runtime_dependency 'mister_bin', '~> 0.7'
+  s.add_dependency 'colsole', '>= 0.8.1', '< 2'
+  s.add_dependency 'mister_bin', '~> 0.7'
 
   s.metadata = {
     'bug_tracker_uri'       => 'https://github.com/DannyBen/completely/issues',

lib/completely.rb

@@ -1,4 +1,5 @@
 require 'completely/exceptions'
+require 'completely/config'
 require 'completely/pattern'
 require 'completely/completions'
 require 'completely/tester'

lib/completely/commands/init.rb

@@ -5,9 +5,11 @@ module Commands
     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 @@ def sample
         @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

lib/completely/completions.rb

@@ -7,23 +7,20 @@ class Completions
 
     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 @@ def tester
   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 @@ def template
     end
 
     def command
-      @command ||= config.keys.first.split.first
+      @command ||= flat_config.keys.first.split.first
     end
 
     def function_name

lib/completely/config.rb

@@ -0,0 +1,69 @@
+module Completely
+  class Config
+    attr_reader :config
+
+    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)
+      @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

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

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 --format='%(refname:short)' 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

spec/approvals/cli/generated-script

@@ -28,20 +28,24 @@ _mygit_completions() {
   local compline="${compwords[*]}"
 
   case "$compline" in
-    'status'*)
-      while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen -W "$(_mygit_completions_filter "--help --verbose --branch $(git branch --format='%(refname:short)' 2>/dev/null)")" -- "$cur")
+    'status'*'--branch')
+      while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen -W "$(_mygit_completions_filter "$(git branch --format='%(refname:short)' 2>/dev/null)")" -- "$cur")
+      ;;
+
+    'status'*'-b')
+      while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen -W "$(_mygit_completions_filter "$(git branch --format='%(refname:short)' 2>/dev/null)")" -- "$cur")
       ;;
 
-    'commit'*)
-      while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen -A file -W "$(_mygit_completions_filter "--help --message --all -a --quiet -q")" -- "$cur")
+    'status'*)
+      while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen -W "$(_mygit_completions_filter "--help --verbose --branch -b")" -- "$cur")
       ;;
 
     'init'*)
       while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen -A directory -W "$(_mygit_completions_filter "--bare")" -- "$cur")
       ;;
 
     *)
-      while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen -W "$(_mygit_completions_filter "--help --version status init commit")" -- "$cur")
+      while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen -W "$(_mygit_completions_filter "-h -v --help --version init status")" -- "$cur")
       ;;
 
   esac