samovar 2.4.1 → 2.5.0

data/lib/samovar/flags.rb

@@ -8,6 +8,8 @@ module Samovar
 	# 
 	# Flags parse text like `-f/--flag <value>` into individual flag parsers.
 	class Flags
+		include Enumerable
+		
 		# Initialize a new flags parser.
 		# 
 		# @parameter text [String] The flags specification string (e.g., `-f/--flag <value>`).
@@ -24,6 +26,21 @@ module Samovar
 			@ordered.each(&block)
 		end
 		
+		# Find the flag that matches the given token.
+		# 
+		# @parameter token [String] The token to match.
+		# @returns [Flag | Nil] The matching flag.
+		def flag_for(token)
+			@ordered.find{|flag| flag.prefix?(token)}
+		end
+		
+		# The possible flag prefixes for completion.
+		# 
+		# @returns [Array(String)] The flag prefixes and alternatives.
+		def completions
+			@ordered.flat_map(&:completions)
+		end
+		
 		# Get the first flag.
 		# 
 		# @returns [Flag] The first flag.
@@ -132,6 +149,21 @@ module Samovar
 		def boolean?
 			false
 		end
+		
+		# Check if the token matches this flag.
+		# 
+		# @parameter token [String] The token to check.
+		# @returns [Boolean] True if the token matches.
+		def prefix?(token)
+			@prefix == token or @alternatives&.include?(token)
+		end
+		
+		# The possible flag prefixes for completion.
+		# 
+		# @returns [Array(String)] The flag prefix and alternatives.
+		def completions
+			[@prefix, *@alternatives]
+		end
 	end
 	
 	# Represents a flag that accepts a value or acts as a boolean.

data/lib/samovar/many.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2016-2023, by Samuel Williams.
+# Copyright, 2016-2026, by Samuel Williams.
+
+require_relative "completion"
 
 module Samovar
 	# Represents multiple positional arguments in a command.
@@ -15,12 +17,14 @@ module Samovar
 		# @parameter stop [Regexp] A pattern that indicates the end of this argument list.
 		# @parameter default [Object] The default value if no arguments are provided.
 		# @parameter required [Boolean] Whether at least one argument is required.
-		def initialize(key, description = nil, stop: /^-/, default: nil, required: false)
+		# @parameter completions [Array | Proc | Nil] Completions for these arguments.
+		def initialize(key, description = nil, stop: /^-/, default: nil, required: false, completions: nil)
 			@key = key
 			@description = description
 			@stop = stop
 			@default = default
 			@required = required
+			@completions = completions
 		end
 		
 		# The name of the attribute to store the values in.
@@ -48,6 +52,11 @@ module Samovar
 		# @attribute [Boolean]
 		attr :required
 		
+		# Completions for these arguments.
+		# 
+		# @attribute [Array | Proc | Nil]
+		attr :completions
+		
 		# Generate a string representation for usage output.
 		# 
 		# @returns [String] The usage string.
@@ -87,5 +96,27 @@ module Samovar
 				raise MissingValueError.new(parent, @key)
 			end
 		end
+		
+		# Complete this repeating positional argument.
+		# 
+		# @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 @stop
+				input.shift while input.any? && !(@stop === input.first)
+				
+				return nil if @stop === context.current
+			else
+				input.clear
+			end
+			
+			if input.empty?
+				return Completion::Result.new(collected) + Completion::Provider.new(context.with_row(self), @completions).suggestions
+			end
+			
+			return nil
+		end
 	end
 end

data/lib/samovar/nested.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2016-2023, by Samuel Williams.
+# Copyright, 2016-2026, by Samuel Williams.
+
+require_relative "completion"
 
 module Samovar
 	# Represents nested sub-commands in a command.
@@ -85,16 +87,57 @@ module Samovar
 				name = input.shift
 				
 				# puts "Instantiating #{command} with #{input}"
-				command.new(input, name: name, parent: parent)
+				command.new(input, name: name, parent: parent, output: parent&.output)
 			elsif default
 				return default
 			elsif @default
-				@commands[@default].new(input, name: @default, parent: parent)
+				@commands[@default].new(input, name: @default, parent: parent, output: parent&.output)
 			elsif @required
 				raise MissingValueError.new(parent, @key)
 			end
 		end
 		
+		# Complete nested command names or continue into a selected command.
+		# 
+		# @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 input.empty?
+				result = suggestions(context)
+				
+				if result.empty? && @default
+					return Completion::Result.new(collected) + context.complete_command(@commands.fetch(@default))
+				end
+				
+				return Completion::Result.new(collected) + result
+			end
+			
+			if command = @commands[input.first]
+				input.shift
+				return context.complete_command(command, input)
+			elsif @default
+				return context.complete_command(@commands.fetch(@default), input)
+			else
+				return Completion::Result.new(collected)
+			end
+		end
+		
+		# Complete nested command names for the current token.
+		# 
+		# @parameter context [Completion::Context] The completion context.
+		# @returns [Completion::Result] The matching nested command suggestions.
+		def suggestions(context)
+			suggestions = @commands.collect do |name, command_class|
+				next unless name.start_with?(context.current)
+				
+				Completion::Suggestion.new(name, description: command_class.description, type: :command)
+			end.compact
+			
+			Completion::Result.new(suggestions)
+		end
+		
 		# Generate usage information for this nested command.
 		# 
 		# @parameter rows [Output::Rows] The rows to append usage information to.

data/lib/samovar/one.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2016-2023, by Samuel Williams.
+# Copyright, 2016-2026, by Samuel Williams.
+
+require_relative "completion"
 
 module Samovar
 	# Represents a single positional argument in a command.
@@ -15,12 +17,14 @@ module Samovar
 		# @parameter pattern [Regexp] A pattern to match valid values.
 		# @parameter default [Object] The default value if no argument is provided.
 		# @parameter required [Boolean] Whether the argument is required.
-		def initialize(key, description, pattern: //, default: nil, required: false)
+		# @parameter completions [Array | Proc | Nil] Completions for this argument.
+		def initialize(key, description, pattern: //, default: nil, required: false, completions: nil)
 			@key = key
 			@description = description
 			@pattern = pattern
 			@default = default
 			@required = required
+			@completions = completions
 		end
 		
 		# The name of the attribute to store the value in.
@@ -48,6 +52,11 @@ module Samovar
 		# @attribute [Boolean]
 		attr :required
 		
+		# Completions for this argument.
+		# 
+		# @attribute [Array | Proc | Nil]
+		attr :completions
+		
 		# Generate a string representation for usage output.
 		# 
 		# @returns [String] The usage string.
@@ -85,5 +94,22 @@ module Samovar
 				raise MissingValueError.new(parent, @key)
 			end
 		end
+		
+		# Complete this positional argument.
+		# 
+		# @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 input.empty?
+				return Completion::Result.new(collected) + Completion::Provider.new(context.with_row(self), @completions).suggestions
+			elsif @pattern =~ input.first
+				input.shift
+				return nil
+			else
+				return Completion::Result.new(collected)
+			end
+		end
 	end
 end

data/lib/samovar/option.rb

@@ -5,6 +5,8 @@
 
 require_relative "flags"
 require_relative "error"
+require_relative "completion/provider"
+require_relative "completion/result"
 
 module Samovar
 	# Represents a single command-line option.
@@ -20,8 +22,9 @@ module Samovar
 		# @parameter value [Object | Nil] A fixed value to use regardless of user input.
 		# @parameter type [Class | Proc | Nil] The type to coerce the value to.
 		# @parameter required [Boolean] Whether the option is required.
+		# @parameter completions [Array | Proc | Nil] Completions for option values.
 		# @yields {|value| ...} An optional block to transform the parsed value.
-		def initialize(flags, description, key: nil, default: nil, value: nil, type: nil, required: false, &block)
+		def initialize(flags, description, key: nil, default: nil, value: nil, type: nil, required: false, completions: nil, &block)
 			@flags = Flags.new(flags)
 			@description = description
 			
@@ -39,6 +42,7 @@ module Samovar
 			
 			@type = type
 			@required = required
+			@completions = completions
 			@block = block
 		end
 		
@@ -59,8 +63,21 @@ module Samovar
 		
 		# The default value if the option is not provided.
 		# 
-		# @attribute [Object]
-		attr :default
+		# @returns [Object | Nil] The resolved default value.
+		def default
+			if @default.respond_to?(:call)
+				@default.call
+			else
+				@default
+			end
+		end
+		
+		# Whether this option has a default value.
+		# 
+		# @returns [Boolean] True if the option has a default value.
+		def default?
+			!@default.nil?
+		end
 		
 		# A fixed value to use regardless of user input.
 		# 
@@ -77,11 +94,52 @@ module Samovar
 		# @attribute [Boolean]
 		attr :required
 		
+		# Completions for option values.
+		# 
+		# @attribute [Array | Proc | Nil]
+		attr :completions
+		
 		# An optional block to transform the parsed value.
 		# 
 		# @attribute [Proc | Nil]
 		attr :block
 		
+		# Find the flag that matches the given token.
+		# 
+		# @parameter token [String] The token to match.
+		# @returns [Flag | Nil] The matching flag.
+		def flag_for(token)
+			@flags.flag_for(token)
+		end
+		
+		# Whether this option consumes a value after the flag.
+		# 
+		# @returns [Boolean] True if any flag for this option consumes a value.
+		def value?
+			@flags.any?{|flag| !flag.boolean?}
+		end
+		
+		# Complete values for this option.
+		# 
+		# @parameter context [Completion::Context] The completion context.
+		# @returns [Completion::Result] The matching option value completions.
+		def suggestions(context)
+			suggestions = []
+			context = context.with_row(self)
+			
+			if default?
+				suggestion = Completion::Provider.new(context, [default]).suggestions.first
+				
+				suggestions << suggestion if suggestion
+			end
+			
+			Completion::Provider.new(context, @completions).suggestions.each do |suggestion|
+				suggestions << suggestion unless suggestions.any?{|existing| existing.value == suggestion.value}
+			end
+			
+			Completion::Result.new(suggestions)
+		end
+		
 		# Coerce the result to the specified type.
 		# 
 		# @parameter result [Object] The value to coerce.
@@ -141,8 +199,8 @@ module Samovar
 		# 
 		# @returns [Array] The usage array.
 		def to_a
-			if @default
-				[@flags, @description, "(default: #{@default})"]
+			if default?
+				[@flags, @description, "(default: #{default})"]
 			elsif @required
 				[@flags, @description, "(required)"]
 			else

data/lib/samovar/options.rb

@@ -4,12 +4,15 @@
 # Copyright, 2016-2025, by Samuel Williams.
 
 require_relative "option"
+require_relative "completion"
 
 module Samovar
 	# Represents a collection of command-line options.
 	# 
 	# Options provide a DSL for defining multiple option flags in a single block.
 	class Options
+		include Enumerable
+		
 		# Parse and create an options collection from a block.
 		# 
 		# @parameter arguments [Array] The arguments for the options collection.
@@ -68,8 +71,10 @@ module Samovar
 		
 		# The default values for options.
 		# 
-		# @attribute [Hash]
-		attr :defaults
+		# @returns [Hash] The resolved default values.
+		def defaults
+			@defaults.transform_values(&:default)
+		end
 		
 		# Freeze this options collection.
 		# 
@@ -93,6 +98,21 @@ module Samovar
 			@ordered.each(&block)
 		end
 		
+		# Find the option that matches the given flag token.
+		# 
+		# @parameter token [String] The flag token to match.
+		# @returns [Option | Nil] The matching option.
+		def option_for(token)
+			@keyed[token]
+		end
+		
+		# The possible flag prefixes for completion.
+		# 
+		# @returns [Array(String)] The option flag prefixes and alternatives.
+		def completions
+			@ordered.flat_map{|option| option.flags.completions}
+		end
+		
 		# Check if this options collection is empty.
 		# 
 		# @returns [Boolean] True if there are no options.
@@ -131,8 +151,8 @@ module Samovar
 				end
 			end
 			
-			if default = option.default
-				@defaults[option.key] = option.default
+			if option.default?
+				@defaults[option.key] = option
 			end
 		end
 		
@@ -143,7 +163,7 @@ module Samovar
 		# @parameter default [Hash | Nil] Default values to use.
 		# @returns [Hash] The parsed option values.
 		def parse(input, parent = nil, default = nil)
-			values = (default || @defaults).dup
+			values = (default || defaults).dup
 			
 			while option = @keyed[input.first]
 				# prefix = input.first
@@ -161,7 +181,71 @@ module Samovar
 			end
 			
 			return values
-		end		# Generate a string representation for usage output.
+		end
+		
+		# Complete option flags or option values.
+		# 
+		# @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)
+			result = consume(input, context)
+			return result if result
+			
+			return nil unless input.empty?
+			
+			flags = suggestions(context.current)
+			
+			if context.current.start_with?("-") && flags.any?
+				return Completion::Result.new(flags)
+			elsif context.current.empty?
+				collected.concat(flags)
+				return nil
+			end
+			
+			return nil
+		end
+		
+		# Consume option tokens before the current completion position.
+		# 
+		# @parameter input [Array(String)] Previously completed command-line arguments.
+		# @parameter context [Completion::Context] The completion context.
+		# @returns [Completion::Result | Nil] A completion result for an option value, or nil to continue.
+		def consume(input, context)
+			while token = input.first
+				break unless option = option_for(token)
+				
+				flag = option.flag_for(token)
+				input.shift
+				
+				if flag && !flag.boolean?
+					if input.any?
+						input.shift
+					else
+						return option.suggestions(context)
+					end
+				end
+			end
+			
+			return nil
+		end
+		
+		# Complete option flags for the given prefix.
+		# 
+		# @parameter prefix [String] The option prefix being completed.
+		# @returns [Array(Completion::Suggestion)] The matching option flag suggestions.
+		def suggestions(prefix)
+			flat_map do |option|
+				option.flags.completions.collect do |value|
+					next unless value.start_with?(prefix)
+					
+					Completion::Suggestion.new(value, description: option.description, type: :option)
+				end
+			end.compact
+		end
+		
+		# Generate a string representation for usage output.
 		# 
 		# @returns [String] The usage string.
 		def to_s

data/lib/samovar/output/columns.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2016-2023, by Samuel Williams.
+# Copyright, 2016-2026, by Samuel Williams.
 
 module Samovar
 	# Namespace for output formatting classes.

data/lib/samovar/output/header.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2023, by Samuel Williams.
+# Copyright, 2019-2026, by Samuel Williams.
 
 module Samovar
 	module Output

data/lib/samovar/output/usage_formatter.rb

@@ -2,8 +2,8 @@
 
 # Released under the MIT License.
 # Copyright, 2019-2025, by Samuel Williams.
+# Copyright, 2026, by Gerhard Schlager.
 
-require "mapping/model"
 require "console/terminal"
 
 require_relative "../error"
@@ -17,8 +17,8 @@ module Samovar
 	module Output
 		# Formats and prints usage information to a terminal.
 		# 
-		# Uses the `mapping` gem to handle different output object types with custom formatting rules.
-		class UsageFormatter < Mapping::Model
+		# Dispatches on the type of each output object to apply custom formatting rules.
+		class UsageFormatter
 			# Print usage information to the output.
 			# 
 			# @parameter rows [Rows] The rows to format and print.
@@ -39,7 +39,6 @@ module Samovar
 			def initialize(output)
 				@output = output
 				@width = 80
-				@first = true
 				
 				@terminal = Console::Terminal.for(@output)
 				@terminal[:header] = @terminal.style(nil, nil, :bright)
@@ -47,43 +46,50 @@ module Samovar
 				@terminal[:error] = @terminal.style(:red)
 			end
 			
-			map(InvalidInputError) do |error|
-				# This is a little hack which avoids printing out "--help" if it was part of an incomplete parse. In the future I'd prefer if this was handled explicitly.
-				@terminal.puts("#{error.message} in:", style: :error) unless error.help?
-			end
-			
-			map(MissingValueError) do |error|
-				@terminal.puts("#{error.message} in:", style: :error)
-			end
-			
-			map(Header) do |header, rows|
-				if @first
-					@first = false
+			# Format and print the given object according to its type.
+			# 
+			# @parameter object [Object] The object to format (a {Rows}, {Row}, {Header}, or error).
+			# @parameter arguments [Array] Extra context passed through to nested rows (the containing {Rows}).
+			def map(object, *arguments, first: true)
+				case object
+				when InvalidInputError
+					# This is a little hack which avoids printing out "--help" if it was part of an incomplete parse. In the future I'd prefer if this was handled explicitly.
+					@terminal.puts("#{object.message} in:", style: :error) unless object.help?
+				when MissingValueError
+					@terminal.puts("#{object.message} in:", style: :error)
+				when Header
+					header, rows = object, arguments.first
+					
+					if first
+						first = false
+					else
+						@terminal.puts
+					end
+					
+					command_line = header.object.command_line(header.name)
+					@terminal.puts "#{rows.indentation}#{command_line}", style: :header
+					
+					if description = header.object.description
+						@terminal.puts "#{rows.indentation}\t#{description}", style: :description
+						@terminal.puts
+					end
+				when Row
+					row, rows = object, arguments.first
+					@terminal.puts "#{rows.indentation}#{row.align(rows.columns)}"
+				when Rows
+					object.each do |row, rows|
+						first = map(row, rows, first: first)
+					end
 				else
-					@terminal.puts
+					raise ArgumentError, "Unable to format #{object.class}!"
 				end
 				
-				command_line = header.object.command_line(header.name)
-				@terminal.puts "#{rows.indentation}#{command_line}", style: :header
-				
-				if description = header.object.description
-					@terminal.puts "#{rows.indentation}\t#{description}", style: :description
-					@terminal.puts
-				end
-			end
-			
-			map(Row) do |row, rows|
-				@terminal.puts "#{rows.indentation}#{row.align(rows.columns)}"
-			end
-			
-			map(Rows) do |items|
-				items.collect{|row, rows| map(row, rows)}
+				return first
 			end
 			
 			# Print the formatted usage output.
-			def print(rows, first: @first)
-				@first = first
-				map(rows)
+			def print(rows, first: true)
+				map(rows, first: first)
 			end
 		end
 	end