samovar 2.4.1 → 2.5.0

data/lib/samovar/split.rb

@@ -3,6 +3,8 @@
 # Released under the MIT License.
 # Copyright, 2016-2025, by Samuel Williams.
 
+require_relative "completion"
+
 module Samovar
 	# Represents a split point in the command-line arguments.
 	# 
@@ -15,12 +17,14 @@ module Samovar
 		# @parameter marker [String] The marker that indicates the split point.
 		# @parameter default [Object] The default value if no split is present.
 		# @parameter required [Boolean] Whether the split is required.
-		def initialize(key, description, marker: "--", default: nil, required: false)
+		# @parameter completions [Array | Proc | Nil] Completions for split arguments.
+		def initialize(key, description, marker: "--", default: nil, required: false, completions: nil)
 			@key = key
 			@description = description
 			@marker = marker
 			@default = default
 			@required = required
+			@completions = completions
 		end
 		
 		# The name of the attribute to store the values after the split.
@@ -48,6 +52,11 @@ module Samovar
 		# @attribute [Boolean]
 		attr :required
 		
+		# Completions for split arguments.
+		# 
+		# @attribute [Array | Proc | Nil]
+		attr :completions
+		
 		# Generate a string representation for usage output.
 		# 
 		# @returns [String] The usage string.
@@ -85,5 +94,40 @@ module Samovar
 				raise MissingValueError.new(parent, @key)
 			end
 		end
+		
+		# Complete the split marker or arguments after it.
+		# 
+		# @parameter input [Array(String)] Previously completed command-line arguments.
+		# @parameter context [Completion::Context] The completion context.
+		# @parameter collected [Array(Completion::Suggestion)] Suggestions collected so far.
+		# @returns [Completion::Result | Nil] A final completion result, or nil to continue.
+		def complete(input, context, collected)
+			if offset = input.index(@marker)
+				input.shift(offset + 1)
+				
+				if @completions == :executable && input.any?
+					return Completion::Result.new(collected + [
+						Completion::Suggestion.new(
+							input.first,
+							description: "Delegate completion",
+							type: :delegate,
+							index: context.words.index(@marker) + 1,
+						),
+					])
+				end
+				
+				return Completion::Result.new(collected) + Completion::Provider.new(context.with_row(self), @completions).suggestions
+			end
+			
+			return Completion::Result.new(collected) unless input.empty?
+			
+			suggestions = []
+			
+			if @marker.start_with?(context.current)
+				suggestions << Completion::Suggestion.new(@marker, description: @description, type: :split)
+			end
+			
+			return Completion::Result.new(collected + suggestions)
+		end
 	end
 end

data/lib/samovar/version.rb

@@ -6,5 +6,5 @@
 
 # @namespace
 module Samovar
-	VERSION = "2.4.1"
+	VERSION = "2.5.0"
 end

data/license.md

@@ -1,7 +1,8 @@
 # MIT License
 
-Copyright, 2016-2025, by Samuel Williams.  
+Copyright, 2016-2026, by Samuel Williams.  
 Copyright, 2018, by Gabriel Mazetto.  
+Copyright, 2026, by Gerhard Schlager.  
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/readme.md

@@ -18,11 +18,19 @@ Please see the [project documentation](https://ioquatix.github.io/samovar/) for
 
   - [Getting Started](https://ioquatix.github.io/samovar/guides/getting-started/index) - This guide explains how to use `samovar` to build command-line tools and applications.
 
+  - [Completion](https://ioquatix.github.io/samovar/guides/completion/index) - This guide explains how to add shell completion to commands built with `samovar`.
+
 ## Releases
 
 Please see the [project releases](https://ioquatix.github.io/samovar/releases/index) for all releases.
 
-### v2.4.1
+### v2.5.0
+
+  - Introduce `Command#complete` which provides a hook for command completion logic, allowing developers to implement custom tab-completion behavior for their commands.
+
+### v2.4.2
+
+  - Drop dependency on `mapping` gem.
 
 ### v2.4.0
 
@@ -58,6 +66,22 @@ We welcome contributions to this project.
 4.  Push to the branch (`git push origin my-new-feature`).
 5.  Create new Pull Request.
 
+### Running Tests
+
+To run the test suite:
+
+``` shell
+bundle exec sus
+```
+
+### Making Releases
+
+To make a new release:
+
+``` shell
+bundle exec bake gem:release:patch # or minor or major
+```
+
 ### Developer Certificate of Origin
 
 In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.
@@ -66,7 +90,7 @@ In order to protect users of this project, we require all contributors to comply
 
 This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.
 
-### Future Work
+## Future Work
 
 ### Multi-value Options
 
@@ -88,12 +112,6 @@ command list -- --help
 
 In this case, do we show help? Some effort is required to disambiguate this. Initially, it makes sense to keep things as simple as possible. But, it might make sense for some options to be declared in a global scope, which are extracted before parsing begins. I'm not sure if this is really a good idea. It might just be better to give good error output in this case (you specified an option but it was in the wrong place).
 
-### Shell Auto-completion
-
-Because of the structure of the Samovar command parser, it should be possible to generate a list of all possible tokens at each point. Therefore, semantically correct tab completion should be possible.
-
-As a secondary to this, it would be nice if `Samovar::One` and `Samovar::Many` could take a list of potential tokens so that auto-completion could give meaningful suggestions, and possibly improved validation.
-
 ### Short/Long Help
 
 It might be interesting to explore whether it's possible to have `-h` and `--help` do different things. This could include command specific help output, more detailed help output (similar to a man page), and other useful help related tasks.

data/releases.md

@@ -1,6 +1,12 @@
 # Releases
 
-## v2.4.1
+## v2.5.0
+
+  - Introduce `Command#complete` which provides a hook for command completion logic, allowing developers to implement custom tab-completion behavior for their commands.
+
+## v2.4.2
+
+  - Drop dependency on `mapping` gem.
 
 ## v2.4.0
 

metadata

@@ -1,11 +1,12 @@
 --- !ruby/object:Gem::Specification
 name: samovar
 version: !ruby/object:Gem::Version
-  version: 2.4.1
+  version: 2.5.0
 platform: ruby
 authors:
 - Samuel Williams
 - Gabriel Mazetto
+- Gerhard Schlager
 bindir: bin
 cert_chain:
 - |
@@ -53,28 +54,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
-- !ruby/object:Gem::Dependency
-  name: mapping
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- context/completion.md
 - context/getting-started.md
 - context/index.yaml
 - lib/samovar.rb
 - lib/samovar/command.rb
+- lib/samovar/completion.rb
+- lib/samovar/completion/context.rb
+- lib/samovar/completion/provider.rb
+- lib/samovar/completion/result.rb
+- lib/samovar/completion/suggestion.rb
 - lib/samovar/error.rb
 - lib/samovar/failure.rb
 - lib/samovar/flags.rb
@@ -109,14 +102,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Samovar is a flexible option parser excellent support for sub-commands and
   help documentation.