completely 0.7.6 → 0.8.0.rc3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b709faa1af61168b7ead8e09a70dc68a2c38fe20e0ba976b0fb9243e0f69b210
-  data.tar.gz: af78d6cac9356d1fa5fb54b73e73967b7026a392b682f2f3cb3dc915356323a8
+  metadata.gz: c08af2e45d441174aa7ba877f55ce3ab49ed37c066abba5b522f404226c4fb09
+  data.tar.gz: 4096cfb3dd365eece6ad5801cde77ca2127fe0500404839949d8e4b6a3c0ec85
 SHA512:
-  metadata.gz: fddaadff6dd7131f0eea16e68f73a1d410c3dc9f1303b6298107a537f4a5c7daa854a7552cf07f0ab322d90661760cd36783f233bb6ed0d0614cf63fb28a551d
-  data.tar.gz: 128153a3250521b993fe197d65cee5c5a0d260ccd073ff0d4539209d2ddc58f51b7e8b81ee5974365f1036943cacd244992cefadcef054d86026d3daff15cfd3
+  metadata.gz: b8d65f92118b3700b77803005d936a3b1ddee313936207387496d7685bd6361ffcb3fbe6c28bd8c3b5b7fb7d4d1bd1b259e1e898da1b9739df07b99e17e89c1f
+  data.tar.gz: 398311bc0f57a4722a10d37776aad1a4e0651986a35832fc54a087618fcc3995543a21e35880deaa8ada9b88bfbc91183201c0a8bdf174ebb69ccd34e6233006

data/README.md

@@ -39,20 +39,15 @@ $ alias completely='docker run --rm -it --user $(id -u):$(id -g) --volume "$PWD:
 
 ## Configuration syntax
 
-Completely works with a simple YAML configuration file as input, and generates
-a bash completions script as output.
+Completely works with a YAML configuration file as input, and generates a bash
+completions script as output.
 
-The configuration file is built of blocks that look like this:
+There are three configuration formats:
 
-```yaml
-pattern:
-- --argument
-- --param
-- command
-```
-
-Each pattern contains an array of words (or functions) that will be suggested
-for the auto complete process.
+- **Pattern config**: Recommended for new projects. It describes command shapes,
+  option groups, and value sources explicitly.
+- **Flat config**: The original simple pattern-to-suggestions format.
+- **Nested config**: A nested spelling of the flat config format.
 
 You can save a sample YAML file by running:
 
@@ -60,165 +55,162 @@ You can save a sample YAML file by running:
 $ completely init
 ```
 
-This will generate a file named `completely.yaml` with this content:
-
-```yaml
-mygit:
-- -h
-- -v
-- --help
-- --version
-- init
-- status
-
-mygit init:
-- --bare
-- <directory>
-
-mygit status:
-- --help
-- --verbose
-- --branch
-- -b
-
-mygit status*--branch: &branches
-- $(git branch --format='%(refname:short)' 2>/dev/null)
+This creates a `completely.yaml` file using the recommended pattern config
+format. You can also choose a format explicitly:
 
-mygit status*-b: *branches
+```bash
+$ completely init --format pattern
+$ completely init --format flat
+$ completely init --format nested
 ```
 
-Each pattern in this configuration file will be checked against the user's
-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 (strings that start with 
-a hyphen `-`) unless the input ends with a hyphen.
-
-To generate the bash script, simply run:
+To generate the bash script, run:
 
 ```bash
 $ completely generate
 
-# or, to just preview it without saving:
+# or, to preview it without saving:
 $ completely preview
 ```
 
-For more options (like setting input/output path), run:
+For more options, run:
 
 ```bash
 $ completely --help
 ```
 
-### Suggesting files, directories and other bash built-ins
+### Pattern config
 
-In addition to specifying a simple array of completion words, you may use
-the special syntax `<..>` to suggest more advanced functions.
+Pattern config is the recommended format for new completion files.
 
 ```yaml
-pattern:
-- <file>
-- <directory>
+patterns:
+  - mygit [root options]
+  - mygit init [init options] <directory>
+  - mygit status [status options]
+
+options:
+  root:
+    - -h|--help
+    - -v|--version
+  init:
+    - --bare
+  status:
+    - --help
+    - --branch|-b <branch>
+    - --format <format>
+    - --verbose (repeatable)
+
+tokens:
+  directory: +directory
+  branch: $(git branch --format='%(refname:short)' 2>/dev/null)
+  format: [short, long]
 ```
 
-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.
+The `patterns` section describes valid command shapes:
 
-You may use any of the below keywords to add additional suggestions:
+- Plain words are command words, for example `mygit`, `init`, and `status`.
+- Command aliases can be written with `|`, for example `status|st`.
+- `[name options]` references `options.name`. `[name]` is also accepted.
+- `<token>` references `tokens.token`.
+- `<token>...` marks the final positional as repeatable.
 
-| 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:
+The `options` section defines option groups:
 
 ```yaml
-mygit:
-- $(git branch --format='%(refname:short)' 2>/dev/null)
+options:
+  status:
+    - --help
+    - --branch|-b <branch>
+    - --verbose (repeatable)
 ```
 
-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.
+An option can be a plain flag, aliases separated with `|`, or a flag that
+expects a value token.
 
-### Completion scope and limitations
+Options are unique by default. If an option should be suggested again after it
+was already used, add `(repeatable)`:
 
-- Completion words are treated as whitespace-delimited tokens.
-- Literal completion phrases that contain spaces are not supported as a single completion item.
-- Quotes and other special shell characters in literal completion words are not escaped automatically.
-- Dynamic `$(...)` completion commands should output plain whitespace-delimited words.
-
-### Suggesting flag arguments
+```yaml
+options:
+  status:
+    - --tag <tag> (repeatable)
+```
 
-Adding a `*` wildcard in the middle of a pattern can be useful for suggesting
-arguments for flags. For example:
+The final positional in a pattern can be repeatable:
 
 ```yaml
-mygit checkout:
-- --branch
-- -b
+patterns:
+  - mygit upload <file>...
+```
 
-mygit checkout*--branch:
-- $(git branch --format='%(refname:short)' 2>/dev/null)
+Only the final positional may be repeatable.
 
-mygit checkout*-b:
-- $(git branch --format='%(refname:short)' 2>/dev/null)
+The `tokens` section defines completion sources. Each token value can be one of
+these forms:
+
+```yaml
+tokens:
+  source: ~
+  directory: +directory
+  branch: $(git branch --format='%(refname:short)' 2>/dev/null)
+  format: [short, long]
+  target: [+file, +directory, README.md, $(git branch --format='%(refname:short)' 2>/dev/null)]
+  literal: ++file
 ```
 
-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:
+- A null value such as `~` defines a token without completion suggestions.
+- A value starting with `+`, such as `+directory`, uses a bash built-in completion action.
+- A value starting with `++`, such as `++file`, provides the literal completion word `+file`.
+- Plain strings, including `$(...)` command substitutions, are added to the completion word list.
+- An array combines multiple source items.
+
+Every `[name]` option group and every `<token>` used by patterns or options must
+be defined. This keeps typos from generating broken completion scripts.
+
+### Flat config
+
+Flat config is the original Completely format. It is simpler, and remains
+supported.
 
 ```yaml
-mygit checkout:
+mygit:
+- -h
+- -v
+- --help
+- --version
+- init
+- status
+
+mygit init:
+- --bare
+- <directory>
+
+mygit status:
+- --help
+- --verbose
 - --branch
 - -b
 
-mygit checkout*--branch: &branches
+mygit status*--branch: &branches
 - $(git branch --format='%(refname:short)' 2>/dev/null)
 
-mygit checkout*-b: *branches
+mygit status*-b: *branches
 ```
 
-### Alternative nested syntax
+Each pattern is checked against the user's input. If the input matches the
+pattern, the list that follows it is suggested as completions.
 
-Completely also supports an alternative nested syntax. You can generate this
-example by running:
+Suggested completions do not show flags (strings that start with a hyphen `-`)
+unless the input ends with a hyphen.
 
-```bash
-$ completely init --nested
-```
+Adding a `*` wildcard in the middle of a pattern can be used for suggesting flag
+arguments. In the example above, branches are suggested after `--branch` or `-b`.
+
+### Nested config
 
-The example configuration below will generate the exact same script as the one
-shown at the beginning of this document.
+Nested config is an alternate spelling of flat config. It generates the same
+completion behavior as the flat example above.
 
 ```yaml
 mygit:
@@ -237,18 +229,74 @@ mygit:
   - +-b: *branches
 ```
 
-The rules here are as follows:
+The rules are:
+
+- Each pattern can have a mixed array of strings and hashes.
+- Strings and hash keys are used as completion strings for that pattern.
+- Hashes can contain a nested mixed array of the same structure.
+- Hash keys are appended to the parent prefix. In the example above, the `init`
+  hash creates the pattern `mygit init`.
+- To provide a wildcard such as `mygit status*--branch`, prefix the hash key with
+  `+` or `*`, for example `+--branch` or `"*--branch"`. When using `*`, quote the
+  key because asterisks have special meaning in YAML.
+
+### Completion sources
+
+Pattern config and the original flat/nested formats use the same underlying bash
+completion sources, but they spell built-ins differently.
+
+Pattern config uses named tokens:
+
+```yaml
+tokens:
+  file: +file
+  directory: +directory
+  branch: $(git branch --format='%(refname:short)' 2>/dev/null)
+  format: [short, long]
+```
+
+Flat and nested configs use completion words directly:
 
-- 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.
+```yaml
+mygit init:
+- <file>
+- <directory>
+- $(git branch --format='%(refname:short)' 2>/dev/null)
+```
+
+The built-in names map to `compgen -A` actions:
+
+| Built-in      | 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
+
+### Completion scope and limitations
+
+- Completion words are treated as whitespace-delimited tokens.
+- Literal completion phrases that contain spaces are not supported as a single completion item.
+- Quotes and other special shell characters in literal completion words are not escaped automatically.
+- Dynamic `$(...)` completion commands should output plain whitespace-delimited words.
 
 
 ## Using the generated completion scripts
@@ -293,9 +341,26 @@ require 'completely'
 # Load from file
 completions = Completely::Completions.load "input.yaml"
 
-# Or, from a hash
+# Or, from a pattern config hash
+input = {
+  "patterns" => [
+    "mygit init [init options] <directory>",
+    "mygit status|st [status options]"
+  ],
+  "options" => {
+    "init" => ["--bare"],
+    "status" => ["--verbose|-v", "--branch|-b <branch>"]
+  },
+  "tokens" => {
+    "directory" => "directory",
+    "branch" => "$(git branch --format='%(refname:short)' 2>/dev/null)"
+  }
+}
+completions = Completely::Completions.new input
+
+# Flat and nested config hashes are also supported by the same API.
 input = {
-  "mygit" => %w[--help --version status init commit],
+  "mygit" => %w[--help --version status init],
   "mygit status" => %w[--help --verbose --branch]
 }
 completions = Completely::Completions.new input
@@ -327,8 +392,10 @@ 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:
+script, you can do so by adding any additional flags to the
+`completely.yaml` configuration file using the special `completely_options`
+key. Completely passes these options to Bash's `complete` command as is. For
+example:
 
 ```yaml
 completely_options:

data/lib/completely/commands/base.rb

@@ -6,7 +6,7 @@ module Completely
       class << self
         def param_config_path
           param 'CONFIG_PATH', <<~USAGE
-            Path to the YAML configuration file [default: completely.yaml].
+            Path to the Completely YAML configuration file (pattern, flat, or nested) [default: completely.yaml].
             Can also be set by an environment variable.
           USAGE
         end
@@ -18,7 +18,7 @@ module Completely
 
         def environment_config_path
           environment 'COMPLETELY_CONFIG_PATH',
-            'Path to a completely configuration file [default: completely.yaml].'
+            'Path to a Completely YAML configuration file [default: completely.yaml].'
         end
 
         def environment_debug
@@ -62,7 +62,7 @@ module Completely
 
       def syntax_warning
         say! "\nr`WARNING:`\nr`Your configuration is invalid.`"
-        say! 'r`All patterns must start with the same word.`'
+        say! 'r`All completion patterns must use the same command name.`'
       end
     end
   end

data/lib/completely/commands/generate.rb

@@ -16,7 +16,7 @@ module Completely
       option '-i --install PROGRAM', 'Install the generated script as completions for PROGRAM.'
 
       param 'CONFIG_PATH', <<~USAGE
-        Path to the YAML configuration file [default: completely.yaml].
+        Path to the Completely YAML configuration file (pattern, flat, or nested) [default: completely.yaml].
         Use '-' to read from stdin.
 
         Can also be set by an environment variable.

data/lib/completely/commands/init.rb

@@ -3,12 +3,12 @@ require 'completely/commands/base'
 module Completely
   module Commands
     class Init < Base
-      help 'Create a new sample YAML configuration file'
+      help 'Create a new sample Completely YAML configuration file'
 
-      usage 'completely init [--nested] [CONFIG_PATH]'
+      usage 'completely init [--format FORMAT] [CONFIG_PATH]'
       usage 'completely init (-h|--help)'
 
-      option '-n --nested', 'Generate a nested configuration'
+      option '-f --format FORMAT', 'Sample format: pattern, flat, or nested [default: pattern]'
 
       param_config_path
       environment_config_path
@@ -26,16 +26,29 @@ module Completely
         @sample ||= File.read sample_path
       end
 
-      def nested?
-        args['--nested']
+      def format
+        @format ||= args['--format'] || 'pattern'
       end
 
       def sample_path
         @sample_path ||= begin
-          sample_name = nested? ? 'sample-nested' : 'sample'
-          File.expand_path "../templates/#{sample_name}.yaml", __dir__
+          raise Error, "Invalid format: #{format}" unless sample_filenames.key? format
+
+          File.expand_path "../templates/#{sample_filename}", __dir__
         end
       end
+
+      def sample_filename
+        sample_filenames.fetch format
+      end
+
+      def sample_filenames
+        @sample_filenames ||= {
+          'flat'    => 'flat-config/sample.yaml',
+          'nested'  => 'flat-config/sample-nested.yaml',
+          'pattern' => 'pattern-config/sample.yaml',
+        }
+      end
     end
   end
 end

data/lib/completely/commands/test.rb

@@ -6,8 +6,8 @@ module Completely
       summary 'Test completions'
 
       help 'This command can be used to test that your completions script responds with ' \
-        'the right completions. It works by reading your completely.yaml file, generating ' \
-        'a completions script, and generating a temporary testing script.'
+        'the right completions. It works by reading a Completely YAML configuration file, ' \
+        'generating a completions script, and generating a temporary testing script.'
 
       usage 'completely test [--keep] COMPLINE...'
       usage 'completely test (-h|--help)'

data/lib/completely/completions.rb

@@ -16,7 +16,7 @@ module Completely
     end
 
     def initialize(config, function_name: nil)
-      @config = config.is_a?(Config) ? config : Config.new(config)
+      @config = normalize_config config
       @function_name = function_name
     end
 
@@ -29,6 +29,8 @@ module Completely
     end
 
     def valid?
+      return pattern_programs.uniq.one? if pattern_config?
+
       pattern_prefixes.uniq.one?
     end
 
@@ -62,7 +64,10 @@ module Completely
     end
 
     def template_path
-      @template_path ||= File.expand_path('templates/template.erb', __dir__)
+      @template_path ||= begin
+        template = pattern_config? ? 'pattern-config/template.erb' : 'flat-config/template.erb'
+        File.expand_path("templates/#{template}", __dir__)
+      end
     end
 
     def template
@@ -70,7 +75,7 @@ module Completely
     end
 
     def command
-      @command ||= flat_config.keys.first.split.first
+      @command ||= pattern_config? ? config.model[:program] : flat_config.keys.first.split.first
     end
 
     def function_name
@@ -91,5 +96,86 @@ module Completely
 
       "#{options} "
     end
+
+    def pattern_config?
+      config.is_a? PatternConfig
+    end
+
+    def pattern_routes
+      config.model[:routes]
+    end
+
+    def pattern_programs
+      pattern_routes.map { |route| route.dig(:words, 0, :name) }
+    end
+
+    def pattern_root_words
+      pattern_routes.flat_map do |route|
+        word = route[:words][1]
+        word ? [word[:name], *word[:aliases]] : []
+      end.uniq
+    end
+
+    def pattern_route_id(route)
+      pattern_routes.index route
+    end
+
+    def pattern_route_conditions(route)
+      route[:words][1..].map.with_index do |word, index|
+        names = [word[:name], *word[:aliases]]
+        names.map { |name| %["${non_options[#{index}]}" == "#{bash_escape name}"] }.join(' || ')
+      end
+    end
+
+    def pattern_route_word_count(route)
+      route[:words].size - 1
+    end
+
+    def pattern_route_options(route)
+      route[:option_groups].flat_map do |name|
+        config.model[:options][name] || []
+      end
+    end
+
+    def pattern_options_with_values
+      config.model[:options].values.flatten.select { |option| option[:value] }
+    end
+
+    def pattern_source_empty?(source)
+      source[:items].empty?
+    end
+
+    def pattern_source_compgen(source)
+      wordlist = source[:items]
+        .select { |item| item[:type] == :value }
+        .map { |item| item[:value] }
+        .join(' ')
+
+      builtins = source[:items]
+        .select { |item| item[:type] == :builtin }
+        .map { |item| "-A #{bash_escape item[:value]}" }
+
+      parts = []
+      parts << %[-W "#{bash_double_quote_escape wordlist}"] unless wordlist.empty?
+      parts.concat builtins
+      parts.join(' ')
+    end
+
+    def bash_escape(value)
+      value.to_s.gsub('\\', '\\\\\\').gsub('"', '\\"')
+    end
+
+    def bash_double_quote_escape(value)
+      value.to_s.gsub('\\', '\\\\\\').gsub('"', '\\"')
+    end
+
+    def normalize_config(config)
+      case config
+      when FlatConfig, PatternConfig
+        config
+      else
+        Config.build config
+      end
+    end
   end
 end

data/lib/completely/config.rb

@@ -1,67 +1,26 @@
 module Completely
   class Config
-    attr_reader :config, :options
-
     class << self
       def parse(str)
-        new YAML.load(str, aliases: true)
+        build YAML.load(str, aliases: true)
       rescue Psych::Exception => e
         raise ParseError, "Invalid YAML: #{e.message}"
       end
 
       def load(path) = parse(File.read(path))
       def read(io) = parse(io.read)
-    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(/^[*+]/, '')
+      def build(config)
+        if pattern_config? config
+          PatternConfig.new config
+        else
+          FlatConfig.new config
+        end
       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))
+      def pattern_config?(config)
+        config.is_a?(Hash) && config.has_key?('patterns')
       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/flat_config.rb

@@ -0,0 +1,56 @@
+module Completely
+  class FlatConfig
+    attr_reader :config, :options
+
+    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/pattern_config.rb

@@ -0,0 +1,201 @@
+module Completely
+  class PatternConfig
+    attr_reader :config, :options
+
+    def initialize(config)
+      @options = config.delete('completely_options')&.transform_keys(&:to_sym) || {}
+      @config = config
+    end
+
+    def model
+      validate!
+
+      @model ||= {
+        program: program,
+        routes:  routes,
+        options: parsed_options,
+        tokens:  tokens,
+      }
+    end
+
+    def flat_config
+      raise Error, 'Pattern config cannot be converted to flat config'
+    end
+
+  private
+
+    def patterns
+      @patterns ||= Array config['patterns']
+    end
+
+    def option_groups
+      @option_groups ||= config['options'] || {}
+    end
+
+    def token_sources
+      @token_sources ||= config['tokens'] || {}
+    end
+
+    def program
+      routes.first.dig(:words, 0, :name)
+    end
+
+    def routes
+      @routes ||= patterns.map { |pattern| parse_pattern pattern }
+    end
+
+    def parsed_options
+      @parsed_options ||= option_groups.to_h do |name, entries|
+        [name, Array(entries).map { |entry| parse_option entry }]
+      end
+    end
+
+    def tokens
+      @tokens ||= token_sources.to_h do |name, source|
+        [name, parse_source(name, source)]
+      end
+    end
+
+    def validate!
+      missing_options = referenced_options - option_groups.keys
+      missing_tokens = referenced_tokens - token_sources.keys
+
+      errors = []
+      errors << "Unknown option group: #{missing_options.join ', '}" if missing_options.any?
+      errors << "Unknown token: #{missing_tokens.join ', '}" if missing_tokens.any?
+      errors.concat repeatable_positional_errors
+      raise ParseError, errors.join("\n") if errors.any?
+    end
+
+    def repeatable_positional_errors
+      patterns.filter_map do |pattern|
+        positionals = pattern_parts(pattern).select { |part| token? part }
+        next unless positionals[0...-1].any? { |part| repeatable_token? part }
+
+        "Repeatable positional must be the last positional in pattern: #{pattern}"
+      end
+    end
+
+    def referenced_options
+      patterns.flat_map do |pattern|
+        pattern_parts(pattern).filter_map { |part| option_group_name(part) if option_group?(part) }
+      end.uniq
+    end
+
+    def referenced_tokens
+      pattern_tokens + option_tokens
+    end
+
+    def pattern_tokens
+      patterns.flat_map do |pattern|
+        pattern_parts(pattern).filter_map { |part| token_name(part) if token?(part) }
+      end
+    end
+
+    def option_tokens
+      option_groups.values.flatten.filter_map do |entry|
+        value_part = option_parts(entry).find { |part| token? part }
+        token_name(value_part) if value_part
+      end
+    end
+
+    def parse_pattern(pattern)
+      result = { words: [], option_groups: [], positionals: [] }
+
+      pattern_parts(pattern).each do |part|
+        if option_group?(part)
+          result[:option_groups] << option_group_name(part)
+        elsif token?(part)
+          result[:positionals] << parse_token(part)
+        else
+          result[:words] << parse_word(part)
+        end
+      end
+
+      result
+    end
+
+    def parse_word(part)
+      names = part.split('|')
+      { name: names.first, aliases: names[1..] || [] }
+    end
+
+    def pattern_parts(pattern)
+      pattern.scan(/\[[^\]]+\]|<[^>]+>\.\.\.|<[^>]+>|\S+/)
+    end
+
+    def parse_option(entry)
+      flag_part, *parts = option_parts entry
+      value_part = parts.find { |part| token? part }
+      metadata_parts = parts.select { |part| metadata? part }
+      unknown_parts = parts - [value_part] - metadata_parts
+      raise ParseError, "Invalid option syntax: #{entry}" if unknown_parts.any?
+
+      names = flag_part.split('|')
+
+      result = { names: names, repeatable: false }
+      result[:value] = parse_token(value_part) if value_part
+      metadata_parts.each { |part| apply_option_metadata result, part }
+      result
+    end
+
+    def option_parts(entry)
+      entry.scan(/<[^>]+>|\([^)]+\)|\S+/)
+    end
+
+    def apply_option_metadata(result, part)
+      case part
+      when '(repeatable)'
+        result[:repeatable] = true
+      else
+        raise ParseError, "Unknown option metadata: #{part}"
+      end
+    end
+
+    def metadata?(part)
+      part.start_with?('(') && part.end_with?(')')
+    end
+
+    def parse_token(part)
+      repeatable = repeatable_token? part
+      token_part = repeatable ? part.delete_suffix('...') : part
+      name = token_name token_part
+      result = { name: name, source: parse_source(name, token_sources[name]) }
+      result[:repeatable] = true if repeatable
+      result
+    end
+
+    def parse_source(_name, source)
+      source_items = source.is_a?(Array) ? source : [source]
+      items = source_items.compact.map { |item| parse_source_item item }
+      { items: items }
+    end
+
+    def parse_source_item(item)
+      return { type: :value, value: item.to_s[1..] } if item.to_s.start_with? '++'
+      return { type: :builtin, value: item.to_s[1..] } if item.to_s.start_with? '+'
+
+      { type: :value, value: item.to_s }
+    end
+
+    def option_group?(part)
+      part.start_with?('[') && part.end_with?(']')
+    end
+
+    def option_group_name(part)
+      part[1..-2].sub(/\s+options\z/, '')
+    end
+
+    def token?(part)
+      part.match?(/\A<[^>]+>(?:\.\.\.)?\z/)
+    end
+
+    def repeatable_token?(part)
+      part.end_with? '...'
+    end
+
+    def token_name(part)
+      part.delete_suffix('...')[/\A<(.+)>\z/, 1]
+    end
+  end
+end

data/lib/completely/templates/pattern-config/sample.yaml

@@ -0,0 +1,21 @@
+patterns:
+  - mygit [root options]
+  - mygit init [init options] <directory>
+  - mygit status [status options]
+
+options:
+  root:
+    - -h|--help
+    - -v|--version
+  init:
+    - --bare
+  status:
+    - --help
+    - --branch|-b <branch>
+    - --format <format>
+    - --verbose (repeatable)
+
+tokens:
+  directory: +directory
+  branch: $(git branch --format='%(refname:short)' 2>/dev/null)
+  format: [short, long]

data/lib/completely/templates/pattern-config/template.erb

@@ -0,0 +1,149 @@
+# <%= "#{command} completion".ljust 56 %> -*- shell-script -*-
+
+# This bash completions script was generated by
+# completely (https://github.com/bashly-framework/completely)
+# Modifying it manually is not recommended
+
+<%= function_name %>_flag_expects_value() {
+  case "$1" in
+% pattern_options_with_values.each do |option|
+    <%= option[:names].map { |name| bash_escape name }.join('|') %>) return 0 ;;
+% end
+  esac
+
+  return 1
+}
+
+<%= function_name %>() {
+  local cur=${COMP_WORDS[COMP_CWORD]}
+  local prev=
+  if ((COMP_CWORD > 0)); then
+    prev=${COMP_WORDS[$((COMP_CWORD - 1))]}
+  fi
+
+  local completed=()
+  if ((COMP_CWORD > 1)); then
+    completed=("${COMP_WORDS[@]:1:$((COMP_CWORD - 1))}")
+  fi
+
+  local non_options=()
+  local completed_options=()
+  local skip_next=0
+  for word in "${completed[@]}"; do
+    if ((skip_next)); then
+      skip_next=0
+      continue
+    fi
+
+    if [[ "${word:0:1}" == "-" ]]; then
+      completed_options+=("$word")
+      if <%= function_name %>_flag_expects_value "$word"; then
+        skip_next=1
+      fi
+      continue
+    fi
+
+    non_options+=("$word")
+  done
+
+  local route_id=
+  local route_word_count=-1
+  local route_has_positionals=0
+  local positional_index=0
+% pattern_routes.each do |route|
+% conditions = pattern_route_conditions(route)
+  if (( ${#non_options[@]} >= <%= pattern_route_word_count route %> )) &&
+    (( <%= pattern_route_word_count route %> > route_word_count ))<%= conditions.empty? ? '' : ' &&' %>
+% conditions.each_with_index do |condition, index|
+    [[ <%= condition %> ]]<%= index == conditions.size - 1 ? '' : ' &&' %>
+% end
+  then
+    route_id=<%= pattern_route_id route %>
+    route_word_count=<%= pattern_route_word_count route %>
+    route_has_positionals=<%= route[:positionals].empty? ? 0 : 1 %>
+    positional_index=$((${#non_options[@]} - <%= pattern_route_word_count route %>))
+  fi
+
+% end
+  COMPREPLY=()
+
+  if [[ -z "$route_id" ]] || { (( route_word_count == 0 )) && (( !route_has_positionals )) && [[ "${cur:0:1}" != "-" ]]; }; then
+    while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen -W "<%= bash_double_quote_escape pattern_root_words.join(' ') %>" -- "$cur")
+    return
+  fi
+
+  case "$route_id:$prev" in
+% pattern_routes.each do |route|
+% pattern_route_options(route).select { |option| option[:value] }.each do |option|
+    <%= pattern_route_id route %>:<%= option[:names].map { |name| bash_escape name }.join("|#{pattern_route_id route}:") %>)
+% if pattern_source_empty? option[:value][:source]
+      return
+% else
+      while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen <%= pattern_source_compgen option[:value][:source] %> -- "$cur")
+      return
+% end
+      ;;
+% end
+% end
+  esac
+
+  if [[ "${cur:0:1}" == "-" ]]; then
+    case "$route_id" in
+% pattern_routes.each do |route|
+      <%= pattern_route_id route %>)
+        local words=()
+% pattern_route_options(route).each do |option|
+% if option[:repeatable]
+        words+=(<%= option[:names].map { |name| %["#{bash_escape name}"] }.join(' ') %>)
+% else
+        local option_seen=0
+        for completed_option in "${completed_options[@]}"; do
+          case "$completed_option" in
+            <%= option[:names].map { |name| bash_escape name }.join('|') %>) option_seen=1 ;;
+          esac
+        done
+        if ((!option_seen)); then
+          words+=(<%= option[:names].map { |name| %["#{bash_escape name}"] }.join(' ') %>)
+        fi
+% end
+% end
+        while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen -W "${words[*]}" -- "$cur")
+        return
+        ;;
+% end
+    esac
+  fi
+
+% pattern_routes.each do |route|
+% route[:positionals].each_with_index do |positional, index|
+% next unless positional[:repeatable]
+  if [[ "$route_id" == "<%= pattern_route_id route %>" ]] && (( positional_index >= <%= index %> )); then
+% if pattern_source_empty? positional[:source]
+    return
+% else
+    while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen <%= pattern_source_compgen positional[:source] %> -- "$cur")
+    return
+% end
+  fi
+
+% end
+% end
+  case "$route_id:$positional_index" in
+% pattern_routes.each do |route|
+% route[:positionals].each_with_index do |positional, index|
+% next if positional[:repeatable]
+    <%= pattern_route_id route %>:<%= index %>)
+% if pattern_source_empty? positional[:source]
+      return
+% else
+      while read -r; do COMPREPLY+=("$REPLY"); done < <(compgen <%= pattern_source_compgen positional[:source] %> -- "$cur")
+      return
+% end
+      ;;
+% end
+% end
+  esac
+} &&
+  complete <%= complete_options_line %>-F <%= function_name %> <%= command %>
+
+# ex: filetype=sh

data/lib/completely/tester.rb

@@ -37,7 +37,7 @@ module Completely
     end
 
     def template_path
-      @template_path ||= File.expand_path 'templates/tester-template.erb', __dir__
+      @template_path ||= File.expand_path 'templates/tester.bash.erb', __dir__
     end
 
     def template

data/lib/completely/version.rb

@@ -1,3 +1,3 @@
 module Completely
-  VERSION = '0.7.6'
+  VERSION = '0.8.0.rc3'
 end

data/lib/completely.rb

@@ -1,4 +1,6 @@
 require 'completely/exceptions'
+require 'completely/flat_config'
+require 'completely/pattern_config'
 require 'completely/config'
 require 'completely/pattern'
 require 'completely/completions'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: completely
 version: !ruby/object:Gem::Version
-  version: 0.7.6
+  version: 0.8.0.rc3
 platform: ruby
 authors:
 - Danny Ben Shitrit
@@ -72,12 +72,16 @@ files:
 - lib/completely/completions.rb
 - lib/completely/config.rb
 - lib/completely/exceptions.rb
+- lib/completely/flat_config.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
+- lib/completely/pattern_config.rb
+- lib/completely/templates/flat-config/sample-nested.yaml
+- lib/completely/templates/flat-config/sample.yaml
+- lib/completely/templates/flat-config/template.erb
+- lib/completely/templates/pattern-config/sample.yaml
+- lib/completely/templates/pattern-config/template.erb
+- lib/completely/templates/tester.bash.erb
 - lib/completely/tester.rb
 - lib/completely/version.rb
 homepage: https://github.com/bashly-framework/completely