samovar 2.4.1 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1051db069257cf9d25e3599a5ddb5c5547a921cb90d04552a777d3af5c335b2
-  data.tar.gz: 632d0819eb51db7f9640feb8491e543706721a4313243527bb5380da576a578b
+  metadata.gz: c9c0de84734b05646d8e1effd9c06339148112dc6202636d436f2909c6bb5835
+  data.tar.gz: 5d2a79b6375044119235462e71af0b9ca63f7c9ab272cd118f125a4967bae3bf
 SHA512:
-  metadata.gz: f5daa04c5dff0500f95c9dec3cabe02bbbb10fd5a9d5a06f89f6d9e6687eb11af89325472df628170ea04d0458d3c8600849c4fab1299c83bf523e58e1e268ed
-  data.tar.gz: 304cc7d54293e3998dae9e3e3247506db3f82d2d0f6d66e988b4ad21cad0150846a1325a039c4dd3f4746fe0903e6e6afd5a6e2f615d724d7e7ee788da49310b
+  metadata.gz: '09729f11890c05e4f15aa07b9af5202f718c5769f1e794fb9a90b8b843b230c98215cfb96d260923d7fad50cf6bb734f71c24f8f871e38e30c39cc9fc8a2242a'
+  data.tar.gz: a8927f7dd61c3423ea892049dcc4d776811601fd6932a3a0ed1834d6e0751deb3c04bffeea434884a2ea3649640e12d3a02048413b3f5392fb3bc94c1ab68932

data/context/completion.md

@@ -0,0 +1,206 @@
+# Completion
+
+This guide explains how to add shell completion to commands built with `samovar`.
+
+Samovar can complete command lines using the same grammar used for parsing. It can complete option flags, boolean flag variants, nested command names, option values, positional arguments, and split arguments.
+
+## Command Entry Point
+
+Commands expose a completion entry point alongside the normal execution entry point:
+
+~~~ ruby
+Application.call(ARGV)     # Parse and execute the command.
+Application.complete       # Print completion candidates.
+~~~
+
+`complete` expects the command-line arguments to be truncated to the cursor. The final argument is the token being completed. When completing after a space, pass an empty string as the final argument:
+
+~~~ ruby
+Application.complete(["serve", "--bind", ""])
+~~~
+
+Completion candidates are printed as tab-separated values:
+
+~~~ text
+type	value	description	key=value
+~~~
+
+The first three fields are always the completion type, value, and description. Additional fields are optional metadata entries encoded as `key=value`.
+
+## Static Completions
+
+Option flags and nested command names are completed automatically. You can add static completions for option values and positional arguments with `completions:`.
+
+~~~ ruby
+require "samovar"
+
+class Serve < Samovar::Command
+	self.description = "Run the server."
+	
+	options do
+		option "--format <name>", "The output format.", default: "text", completions: ["json", "text", "yaml"]
+	end
+end
+
+class Application < Samovar::Command
+	options do
+		option "-h/--help", "Print help."
+	end
+	
+	nested :command, {
+		"serve" => Serve
+	}, default: "serve"
+end
+~~~
+
+Examples:
+
+~~~ ruby
+Application.complete(["ser"])
+# command	serve	Run the server.
+
+Application.complete(["serve", "--format", "j"])
+# value	json
+~~~
+
+If an option has a default value, the default is offered before other value completions.
+
+## Dynamic Completions
+
+Use a callable provider when completions depend on runtime state.
+
+~~~ ruby
+class Serve < Samovar::Command
+	def self.host_completions(context)
+		["localhost", "0.0.0.0"].select do |host|
+			host.start_with?(context.current)
+		end
+	end
+	
+	options do
+		option "--bind <host>", "The bind address.", completions: method(:host_completions)
+	end
+end
+~~~
+
+The provider receives a `Samovar::Completion::Context` with:
+
+- `current`: The token being completed.
+- `arguments`: The full truncated argument list.
+- `environment`: The environment hash passed to `complete`.
+- `row`: The parser row whose value is being completed. This can be an option or a positional argument.
+
+Providers can return strings, hashes, or `Samovar::Completion::Suggestion` instances:
+
+~~~ ruby
+option "--mode <name>", "The mode.",
+	completions: [
+		{value: "development", description: "Local development", type: :value, suffix: " "},
+		{value: "production", description: "Production", type: :value}
+	]
+~~~
+
+## Path Completion
+
+For path-like arguments, let the shell do native path expansion by using one of the native completion providers:
+
+~~~ ruby
+class Process < Samovar::Command
+	options do
+		option "--output <path>", "The output path.", completions: :path
+		option "--root <path>", "The root directory.", completions: :directory
+	end
+	
+	one :input, "The input path.", completions: :file
+end
+~~~
+
+Supported native providers:
+
+- `:path`: Complete files and directories using the shell.
+- `:file`: Alias for `:path`.
+- `:directory`: Complete directories using the shell.
+- `:executable`: Complete executable commands using the shell.
+
+Samovar does not inspect the filesystem for these providers. It emits a typed completion request, and the shell adapter translates it to native shell path completion.
+
+For split arguments, `:executable` completes the command immediately after the split marker. Once a command is present, Samovar emits a `delegate` completion with an `index` metadata field. The index is the zero-based argument index where delegated completion begins.
+
+## Dedicated Completion Executable
+
+Shell adapters call a dedicated completion executable named `completion-<command>`. This avoids running the normal command during completion.
+
+For a command named `falcon`, provide:
+
+~~~ text
+bin/falcon
+bin/completion-falcon
+~~~
+
+The completion executable can be very small:
+
+~~~ ruby
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/my/application"
+
+My::Application.complete
+~~~
+
+When the user completes a command by path, the shell adapter resolves the completion executable next to that command:
+
+~~~ text
+falcon          -> completion-falcon
+bin/falcon      -> bin/completion-falcon
+./bin/falcon    -> ./bin/completion-falcon
+/path/falcon    -> /path/completion-falcon
+~~~
+
+## Installing Shell Adapters
+
+Shell adapter generation and installation is provided by the `completion` gem.
+
+Generate an adapter script:
+
+~~~ bash
+$ completion generate --shell zsh --command falcon
+~~~
+
+Install a generic adapter script into the default directory for the current shell:
+
+~~~ bash
+$ completion install
+~~~
+
+The generic adapter checks whether a matching `completion-<command>` executable exists before handling a command. You can install an adapter for a specific command instead:
+
+~~~ bash
+$ completion install --command falcon
+~~~
+
+You can specify the shell and directory explicitly:
+
+~~~ bash
+$ completion install --shell fish --directory ~/.config/fish/completions --command falcon
+~~~
+
+The installed adapter calls the matching `completion-<command>` executable when completion is requested.
+
+## Testing Completion
+
+You can test completion directly without involving a shell:
+
+~~~ ruby
+output = StringIO.new
+
+Application.complete(["serve", "--format", "j"], output: output)
+
+expect(output.string).to be == "value\tjson\t\n"
+~~~
+
+For a trailing-space completion, pass an empty final token:
+
+~~~ ruby
+Application.complete(["serve", "--format", ""], output: output)
+~~~

data/context/index.yaml

@@ -12,3 +12,7 @@ files:
   title: Getting Started
   description: This guide explains how to use `samovar` to build command-line tools
     and applications.
+- path: completion.md
+  title: Completion
+  description: This guide explains how to add shell completion to commands built with
+    `samovar`.

data/lib/samovar/command.rb

@@ -14,6 +14,7 @@ require_relative "split"
 require_relative "output"
 
 require_relative "error"
+require_relative "completion"
 
 module Samovar
 	# Represents a command in the command-line interface.
@@ -23,12 +24,13 @@ module Samovar
 		# Parse and execute the command with the given input.
 		# 
 		# This is the high-level entry point for CLI applications. It handles errors gracefully by printing usage and returning nil.
+		# The given arguments are passed to the parser, which consumes them as mutable input.
 		# 
-		# @parameter input [Array(String)] The command-line arguments to parse.
+		# @parameter arguments [Array(String)] The command-line arguments to parse.
 		# @parameter output [IO] The output stream for error messages.
 		# @returns [Object | Nil] The result of the command's call method, or nil if parsing/execution failed.
-		def self.call(input = ARGV, output: $stderr)
-			self.parse(input).call
+		def self.call(arguments = ARGV, output: $stderr)
+			self.parse(arguments).call
 		rescue Error => error
 			error.command.print_usage(output: output) do |formatter|
 				formatter.map(error)
@@ -37,27 +39,40 @@ module Samovar
 			return nil
 		end
 		
+		# Complete the command-line input without executing the command.
+		# The given arguments are treated as the stable command-line boundary; completion internals consume derived input arrays.
+		# 
+		# @parameter arguments [Array(String)] The command-line arguments to complete.
+		# @parameter environment [Hash] The environment for completion callbacks.
+		# @parameter output [IO] The output stream for printing completion results.
+		# @returns [Completion::Result] The completion result.
+		def self.complete(arguments = ARGV, environment: ENV, output: $stdout)
+			Completion.complete(self, arguments, environment: environment).tap do |result|
+				result.print(output)
+			end
+		end
+		
 		# Parse the command-line input and create a command instance.
 		# 
 		# This is the low-level parsing primitive. It raises {Error} exceptions on parsing failures.
 		# For CLI applications, use {call} instead which handles errors gracefully.
 		# 
-		# @parameter input [Array(String)] The command-line arguments to parse.
+		# @parameter arguments [Array(String)] The command-line arguments to parse.
 		# @returns [Command] The parsed command instance.
 		# @raises [Error] If parsing fails.
-		def self.parse(input)
-			self.new(input)
+		def self.parse(arguments)
+			self.new(arguments)
 		end
 		
 		# Create a new command instance with the given arguments.
 		# 
 		# This is a convenience method for creating command instances with explicit arguments.
 		# 
-		# @parameter input [Array(String)] The command-line arguments to parse.
+		# @parameter arguments [Array(String)] The command-line arguments to parse.
 		# @parameter options [Hash] Additional options to pass to the command.
 		# @returns [Command] The command instance.
-		def self.[](*input, **options)
-			self.new(input, **options)
+		def self.[](*arguments, **options)
+			self.new(arguments, **options)
 		end
 		
 		class << self

data/lib/samovar/completion/context.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "result"
+
+module Samovar
+	module Completion
+		# The context provided to dynamic completion callbacks.
+		class Context
+			# Build a context for a command class and argument list.
+			#
+			# @parameter command_class [Class] The command class to complete.
+			# @parameter arguments [Array(String)] The truncated command-line arguments.
+			# @parameter environment [Hash] The environment for completion callbacks.
+			# @returns [Context] The completion context.
+			def self.for(command_class, arguments, environment: ENV)
+				return self.new(
+					command_class.table.merged,
+					arguments,
+					arguments.last || "",
+					environment: environment,
+				)
+			end
+			
+			# Initialize a new completion context.
+			#
+			# @parameter table [Table] The command table to complete.
+			# @parameter arguments [Array(String)] The truncated command-line arguments.
+			# @parameter current [String] The token being completed.
+			# @parameter row [Object | Nil] The parser row whose value is being completed.
+			# @parameter environment [Hash] The environment for completion callbacks.
+			def initialize(table, arguments, current, row = nil, environment: ENV)
+				@table = table
+				@arguments = arguments
+				@current = current
+				@row = row
+				@environment = environment
+			end
+			
+			# @attribute [Table] The command table to complete.
+			attr :table
+			
+			# @attribute [Array(String)] The truncated command-line arguments.
+			attr :arguments
+			
+			# @attribute [String] The token being completed.
+			attr :current
+			
+			# @attribute [Object | Nil] The parser row whose value is being completed.
+			attr :row
+			
+			# @attribute [Hash] The environment for completion callbacks.
+			attr :environment
+			
+			# Create a context for completing the given parser row.
+			#
+			# @parameter row [Object] The parser row whose value is being completed.
+			# @returns [Context] The specialized completion context.
+			def with_row(row)
+				return self.class.new(
+					@table,
+					@arguments,
+					@current,
+					row,
+					environment: @environment,
+				)
+			end
+			
+			# The completed words before the current token.
+			#
+			# @returns [Array(String)] The arguments before the token being completed.
+			def words
+				@arguments.take(@arguments.size - 1)
+			end
+			
+			# Complete the current command class.
+			#
+			# @returns [Result] The completion result.
+			def complete
+				complete_rows(@table, words)
+			end
+			
+			# Complete the given command class with completed words.
+			#
+			# @parameter command_class [Class] The command class to complete.
+			# @parameter words [Array(String)] The completed words before the current token.
+			# @returns [Result] The completion result.
+			def complete_command(command_class, words = [])
+				complete_rows(command_class.table.merged, words)
+			end
+			
+			# Complete the rows in a command table.
+			# The input array is mutable and may be consumed by parser rows.
+			#
+			# @parameter table [Table] The command table to complete.
+			# @parameter input [Array(String)] The mutable completed words to consume.
+			# @returns [Result] The completion result.
+			def complete_rows(table, input)
+				collected = []
+				
+				table.each do |row|
+					if row.respond_to?(:complete)
+						if result = row.complete(input, self, collected)
+							return result
+						end
+					end
+				end
+				
+				return Result.new(collected)
+			end
+		end
+	end
+end

data/lib/samovar/completion/provider.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "result"
+require_relative "suggestion"
+
+module Samovar
+	module Completion
+		# Expands static, dynamic, and native completion providers.
+		class Provider
+			# Initialize a new completion provider.
+			# 
+			# @parameter context [Context] The completion context.
+			# @parameter completions [Array | Proc | Symbol | Nil] The static, dynamic, or native completions.
+			def initialize(context, completions)
+				@context = context
+				@completions = completions
+			end
+			
+			# Generate suggestions from the provider.
+			# 
+			# @returns [Result] The matching completion suggestions.
+			def suggestions
+				case @completions
+				when nil
+					Result.new
+				when Symbol
+					native_suggestions
+				else
+					matching_suggestions
+				end
+			end
+			
+			protected
+			
+			# Generate matching suggestions from static or dynamic completions.
+			#
+			# @returns [Result] The matching completion suggestions.
+			def matching_suggestions
+				values = @completions
+				
+				if values.respond_to?(:call)
+					values = values.call(@context)
+				end
+				
+				values = Array(values).filter_map do |value|
+					suggestion = Suggestion.wrap(value)
+					
+					suggestion if suggestion.start_with?(@context.current)
+				end
+				
+				return Result.new(values)
+			end
+			
+			# Generate native shell completion requests.
+			# 
+			# @returns [Result] The native completion request suggestions.
+			def native_suggestions
+				case @completions
+				when :path, :file
+					Result.new([Suggestion.new(@context.current, description: "Path", type: :path)])
+				when :directory
+					Result.new([Suggestion.new(@context.current, description: "Directory", type: :directory)])
+				when :executable
+					Result.new([Suggestion.new(@context.current, description: "Executable", type: :executable)])
+				else
+					Result.new
+				end
+			end
+			
+		end
+	end
+end

data/lib/samovar/completion/result.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Samovar
+	module Completion
+		# A collection of completion suggestions.
+		class Result
+			include Enumerable
+			
+			# Initialize a new completion result.
+			# 
+			# @parameter suggestions [Array(Suggestion)] The suggestions in this result.
+			def initialize(suggestions = [])
+				@suggestions = suggestions
+			end
+			
+			# @attribute [Array(Suggestion)] The suggestions in this result.
+			attr :suggestions
+			
+			# Iterate over each suggestion.
+			# 
+			# @yields {|suggestion| ...} The block to call for each suggestion.
+			def each(&block)
+				@suggestions.each(&block)
+			end
+			
+			# Whether this result contains no suggestions.
+			# 
+			# @returns [Boolean] True if there are no suggestions.
+			def empty?
+				@suggestions.empty?
+			end
+			
+			# Combine this result with another result.
+			# 
+			# @parameter other [Result] The other result to append.
+			# @returns [Result] The combined result.
+			def +(other)
+				self.class.new(@suggestions + other.suggestions)
+			end
+			
+			# Print suggestions as tab-separated completion records.
+			# 
+			# @parameter output [IO] The output stream to write to.
+			def print(output = $stdout)
+				each do |suggestion|
+					output.puts suggestion.to_record
+				end
+			end
+		end
+	end
+end

data/lib/samovar/completion/suggestion.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Samovar
+	module Completion
+		# A single completion suggestion.
+		class Suggestion
+			# Wrap a raw completion value in a suggestion.
+			#
+			# @parameter value [Suggestion | Hash | Object] The value to wrap.
+			# @returns [Suggestion] The normalized suggestion.
+			def self.wrap(value)
+				case value
+				when self
+					return value
+				when Hash
+					value = value.dup
+					suggestion = value.fetch(:value)
+					value.delete(:value)
+					
+					return self.new(suggestion, **value)
+				else
+					return self.new(value)
+				end
+			end
+			
+			# Initialize a new completion suggestion.
+			#
+			# @parameter value [Object] The completion value.
+			# @parameter type [Symbol | String | Nil] The completion type.
+			# @parameter description [String | Nil] The completion description.
+			# @parameter options [Hash] Additional completion metadata.
+			def initialize(value, type: nil, description: nil, **options)
+				@type = type
+				@value = value
+				@description = description
+				@options = options
+			end
+			
+			# @attribute [Symbol | String | Nil] The completion type.
+			attr :type
+			
+			# @attribute [Object] The completion value.
+			attr :value
+			
+			# @attribute [String | Nil] The completion description.
+			attr :description
+			
+			# @attribute [Hash] Additional completion metadata.
+			attr :options
+			
+			# Whether this suggestion starts with the given prefix.
+			#
+			# @parameter prefix [String] The prefix to check.
+			# @returns [Boolean] True if the suggestion starts with the given prefix.
+			def start_with?(prefix)
+				to_s.start_with?(prefix)
+			end
+			
+			# Convert the suggestion to a tab-separated completion record.
+			#
+			# @returns [String] The escaped completion record.
+			def to_record
+				fields = [
+					escape(@type),
+					escape(@value),
+					escape(@description),
+				]
+				@options.each do |key, value|
+					next if value.nil?
+					
+					fields << "#{escape(key)}=#{escape(value)}"
+				end
+				
+				return fields.join("\t")
+			end
+			
+			# Convert the suggestion to its value.
+			#
+			# @returns [String] The suggestion value.
+			def to_s
+				@value.to_s
+			end
+			
+			private
+			
+			def escape(value)
+				value.to_s.gsub(/[\t\r\n]/, " ")
+			end
+		end
+	end
+end

data/lib/samovar/completion.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "completion/context"
+require_relative "completion/provider"
+require_relative "completion/result"
+require_relative "completion/suggestion"
+
+module Samovar
+	# Shell completion support for Samovar commands.
+	module Completion
+		# Complete the command line for the given command class.
+		# 
+		# @parameter command_class [Class] The command class to complete.
+		# @parameter arguments [Array(String)] The application arguments.
+		# @parameter environment [Hash] The environment for completion callbacks.
+		# @returns [Result] The completion result.
+		def self.complete(command_class, arguments, environment: ENV)
+			Context.for(command_class, arguments, environment: environment).complete
+		end
+	end
+end

data/lib/samovar/failure.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2023, by Samuel Williams.
+# Copyright, 2017-2026, by Samuel Williams.
 
 module Samovar
 	# Represents a runtime failure in command execution.