samovar 2.3.0 → 2.4.1

data/lib/samovar/flags.rb

@@ -1,37 +1,61 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2016-2024, by Samuel Williams.
+# Copyright, 2016-2025, by Samuel Williams.
 
 module Samovar
+	# Represents a collection of flag alternatives for an option.
+	# 
+	# Flags parse text like `-f/--flag <value>` into individual flag parsers.
 	class Flags
+		# Initialize a new flags parser.
+		# 
+		# @parameter text [String] The flags specification string (e.g., `-f/--flag <value>`).
 		def initialize(text)
 			@text = text
 			
 			@ordered = text.split(/\s+\|\s+/).map{|part| Flag.parse(part)}
 		end
 		
+		# Iterate over each flag.
+		# 
+		# @yields {|flag| ...} Each flag in the collection.
 		def each(&block)
 			@ordered.each(&block)
 		end
 		
+		# Get the first flag.
+		# 
+		# @returns [Flag] The first flag.
 		def first
 			@ordered.first
 		end
 		
-		# Whether or not this flag should have a true/false value if not specified otherwise.
+		# Whether this flag should have a true/false value if not specified otherwise.
+		# 
+		# @returns [Boolean] True if this is a boolean flag.
 		def boolean?
 			@ordered.count == 1 and @ordered.first.boolean?
 		end
 		
+		# The number of flag alternatives.
+		# 
+		# @returns [Integer] The count of flags.
 		def count
 			return @ordered.count
 		end
 		
+		# Generate a string representation for usage output.
+		# 
+		# @returns [String] The usage string.
 		def to_s
 			"[#{@ordered.join(' | ')}]"
 		end
 		
+		# Parse a flag from the input.
+		# 
+		# @parameter input [Array(String)] The command-line arguments.
+		# @returns [Object | Nil] The parsed value, or nil if no match.
 		def parse(input)
 			@ordered.each do |flag|
 				result = flag.parse(input)
@@ -44,7 +68,14 @@ module Samovar
 		end
 	end
 	
+	# Represents a single command-line flag.
+	# 
+	# A flag can be a simple boolean flag or a flag that accepts a value.
 	class Flag
+		# Parse a flag specification string into a flag instance.
+		# 
+		# @parameter text [String] The flag specification (e.g., `-f <value>` or `--flag`).
+		# @returns [Flag] A flag instance (either {ValueFlag} or {BooleanFlag}).
 		def self.parse(text)
 			if text =~ /(.*?)\s(\<.*?\>)/
 				ValueFlag.new(text, $1, $2)
@@ -55,54 +86,107 @@ module Samovar
 			end
 		end
 		
+		# Initialize a new flag.
+		# 
+		# @parameter text [String] The full flag specification text.
+		# @parameter prefix [String] The primary flag prefix (e.g., `--flag`).
+		# @parameter alternatives [Array(String) | Nil] Alternative flag prefixes.
 		def initialize(text, prefix, alternatives = nil)
 			@text = text
 			@prefix = prefix
 			@alternatives = alternatives
 		end
 		
+		# The full flag specification text.
+		# 
+		# @attribute [String]
 		attr :text
+		
+		# The primary flag prefix.
+		# 
+		# @attribute [String]
 		attr :prefix
+		
+		# Alternative flag prefixes.
+		# 
+		# @attribute [Array(String) | Nil]
 		attr :alternatives
 		
+		# Generate a string representation for usage output.
+		# 
+		# @returns [String] The flag text.
 		def to_s
 			@text
 		end
 		
+		# Generate a key name for this flag.
+		# 
+		# @returns [Symbol] The key name.
 		def key
-			@key ||= @prefix.sub(/^-*/, '').gsub('-', '_').to_sym
+			@key ||= @prefix.sub(/^-*/, "").gsub("-", "_").to_sym
 		end
 		
+		# Whether this is a boolean flag.
+		# 
+		# @returns [Boolean] False by default.
 		def boolean?
 			false
 		end
 	end
 	
+	# Represents a flag that accepts a value or acts as a boolean.
 	class ValueFlag < Flag
+		# Initialize a new value flag.
+		# 
+		# @parameter text [String] The full flag specification text.
+		# @parameter prefix [String] The primary flag prefix with alternatives (e.g., `-f/--flag`).
+		# @parameter value [String | Nil] The value placeholder (e.g., `<file>`).
 		def initialize(text, prefix, value)
 			super(text, prefix)
 			
 			@value = value
 			
-			*@alternatives, @prefix = @prefix.split('/')
+			*@alternatives, @prefix = @prefix.split("/")
 		end
 		
+		# Alternative flag prefixes.
+		# 
+		# @attribute [Array(String)]
 		attr :alternatives
+		
+		# The value placeholder.
+		# 
+		# @attribute [String | Nil]
 		attr :value
 		
+		# Whether this is a boolean flag (no value required).
+		# 
+		# @returns [Boolean] True if no value is required.
 		def boolean?
 			@value.nil?
 		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
 		
+		# Parse this flag from the input.
+		# 
+		# @parameter input [Array(String)] The command-line arguments.
+		# @returns [String | Symbol | Nil] The parsed value.
 		def parse(input)
 			if prefix?(input.first)
+				# Whether we are expecting to parse a value from input:
 				if @value
-					return input.shift(2).last
+					# Get the actual value from input:
+					flag, value = input.shift(2)
+					return value
 				else
+					# Otherwise, we are just a boolean flag:
 					input.shift
 					return key
 				end
@@ -110,20 +194,34 @@ module Samovar
 		end
 	end
 	
+	# Represents a boolean flag with `--flag` and `--no-flag` variants.
 	class BooleanFlag < Flag
+		# Initialize a new boolean flag.
+		# 
+		# @parameter text [String] The full flag specification text.
+		# @parameter prefix [String] The primary flag prefix (e.g., `--flag`).
+		# @parameter value [Object | Nil] Reserved for future use.
 		def initialize(text, prefix, value = nil)
 			super(text, prefix)
 			
 			@value = value
 			
-			@negated = @prefix.sub(/^--/, '--no-')
+			@negated = @prefix.sub(/^--/, "--no-")
 			@alternatives = [@negated]
 		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 @negated == token
 		end
 		
+		# Parse this flag from the input.
+		# 
+		# @parameter input [Array(String)] The command-line arguments.
+		# @returns [Boolean | Nil] True, false, or nil.
 		def parse(input)
 			if input.first == @prefix
 				input.shift

data/lib/samovar/many.rb

@@ -4,7 +4,17 @@
 # Copyright, 2016-2023, by Samuel Williams.
 
 module Samovar
+	# Represents multiple positional arguments in a command.
+	# 
+	# A `Many` parser extracts all arguments from the command line until it encounters a stop pattern (typically an option flag).
 	class Many
+		# Initialize a new multi-argument parser.
+		# 
+		# @parameter key [Symbol] The name of the attribute to store the values in.
+		# @parameter description [String | Nil] A description of the arguments for help output.
+		# @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)
 			@key = key
 			@description = description
@@ -13,16 +23,41 @@ module Samovar
 			@required = required
 		end
 		
+		# The name of the attribute to store the values in.
+		# 
+		# @attribute [Symbol]
 		attr :key
+		
+		# A description of the arguments for help output.
+		# 
+		# @attribute [String | Nil]
 		attr :description
+		
+		# A pattern that indicates the end of this argument list.
+		# 
+		# @attribute [Regexp]
 		attr :stop
+		
+		# The default value if no arguments are provided.
+		# 
+		# @attribute [Object]
 		attr :default
+		
+		# Whether at least one argument is required.
+		# 
+		# @attribute [Boolean]
 		attr :required
 		
+		# Generate a string representation for usage output.
+		# 
+		# @returns [String] The usage string.
 		def to_s
 			"<#{key}...>"
 		end
 		
+		# Generate an array representation for usage output.
+		# 
+		# @returns [Array] The usage array.
 		def to_a
 			usage = [to_s, @description]
 			
@@ -35,6 +70,12 @@ module Samovar
 			return usage
 		end
 		
+		# Parse multiple arguments from the input.
+		# 
+		# @parameter input [Array(String)] The command-line arguments.
+		# @parameter parent [Command | Nil] The parent command.
+		# @parameter default [Object | Nil] An override for the default value.
+		# @returns [Array(String) | Object | Nil] The parsed values, or the default if none match.
 		def parse(input, parent = nil, default = nil)
 			if @stop and stop_index = input.index{|item| @stop === item}
 				input.shift(stop_index)
@@ -43,7 +84,7 @@ module Samovar
 			elsif default ||= @default
 				return default
 			elsif @required
-				raise MissingValueError.new(parent, self)
+				raise MissingValueError.new(parent, @key)
 			end
 		end
 	end

data/lib/samovar/nested.rb

@@ -4,7 +4,16 @@
 # Copyright, 2016-2023, by Samuel Williams.
 
 module Samovar
+	# Represents nested sub-commands in a command.
+	# 
+	# A `Nested` parser allows you to define multiple sub-commands that can be invoked from the parent command.
 	class Nested
+		# Initialize a new nested command parser.
+		# 
+		# @parameter key [Symbol] The name of the attribute to store the selected command in.
+		# @parameter commands [Hash] A mapping of command names to command classes.
+		# @parameter default [String | Nil] The default command name if none is provided.
+		# @parameter required [Boolean] Whether a command is required.
 		def initialize(key, commands, default: nil, required: false)
 			@key = key
 			@commands = commands
@@ -15,15 +24,36 @@ module Samovar
 			@required = required
 		end
 		
+		# The name of the attribute to store the selected command in.
+		# 
+		# @attribute [Symbol]
 		attr :key
+		
+		# A mapping of command names to command classes.
+		# 
+		# @attribute [Hash]
 		attr :commands
+		
+		# The default command name if none is provided.
+		# 
+		# @attribute [String | Nil]
 		attr :default
+		
+		# Whether a command is required.
+		# 
+		# @attribute [Boolean]
 		attr :required
 		
+		# Generate a string representation for usage output.
+		# 
+		# @returns [String] The usage string.
 		def to_s
 			"<#{@key}>"
 		end
 		
+		# Generate an array representation for usage output.
+		# 
+		# @returns [Array] The usage array.
 		def to_a
 			usage = [self.to_s]
 			
@@ -44,7 +74,12 @@ module Samovar
 			return usage
 		end
 		
-		# @param default [Command] the default command if any.
+		# Parse a nested command from the input.
+		# 
+		# @parameter input [Array(String)] The command-line arguments.
+		# @parameter parent [Command | Nil] The parent command.
+		# @parameter default [Command | Nil] The default command instance.
+		# @returns [Command | Object | Nil] The parsed command instance, or the default if no match.
 		def parse(input, parent = nil, default = nil)
 			if command = @commands[input.first]
 				name = input.shift
@@ -56,10 +91,13 @@ module Samovar
 			elsif @default
 				@commands[@default].new(input, name: @default, parent: parent)
 			elsif @required
-				raise MissingValueError.new(parent, self)
+				raise MissingValueError.new(parent, @key)
 			end
 		end
 		
+		# Generate usage information for this nested command.
+		# 
+		# @parameter rows [Output::Rows] The rows to append usage information to.
 		def usage(rows)
 			rows << self
 			

data/lib/samovar/one.rb

@@ -4,7 +4,17 @@
 # Copyright, 2016-2023, by Samuel Williams.
 
 module Samovar
+	# Represents a single positional argument in a command.
+	# 
+	# A `One` parser extracts exactly one argument from the command line that matches the specified pattern.
 	class One
+		# Initialize a new positional argument parser.
+		# 
+		# @parameter key [Symbol] The name of the attribute to store the value in.
+		# @parameter description [String] A description of the argument for help output.
+		# @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)
 			@key = key
 			@description = description
@@ -13,16 +23,41 @@ module Samovar
 			@required = required
 		end
 		
+		# The name of the attribute to store the value in.
+		# 
+		# @attribute [Symbol]
 		attr :key
+		
+		# A description of the argument for help output.
+		# 
+		# @attribute [String]
 		attr :description
+		
+		# A pattern to match valid values.
+		# 
+		# @attribute [Regexp]
 		attr :pattern
+		
+		# The default value if no argument is provided.
+		# 
+		# @attribute [Object]
 		attr :default
+		
+		# Whether the argument is required.
+		# 
+		# @attribute [Boolean]
 		attr :required
 		
+		# Generate a string representation for usage output.
+		# 
+		# @returns [String] The usage string.
 		def to_s
 			"<#{@key}>"
 		end
 		
+		# Generate an array representation for usage output.
+		# 
+		# @returns [Array] The usage array.
 		def to_a
 			usage = [to_s, @description]
 			
@@ -35,13 +70,19 @@ module Samovar
 			return usage
 		end
 		
+		# Parse a single argument from the input.
+		# 
+		# @parameter input [Array(String)] The command-line arguments.
+		# @parameter parent [Command | Nil] The parent command.
+		# @parameter default [Object | Nil] An override for the default value.
+		# @returns [String | Object | Nil] The parsed value, or the default if no match.
 		def parse(input, parent = nil, default = nil)
 			if input.first =~ @pattern
 				input.shift
 			elsif default ||= @default
 				return default
 			elsif @required
-				raise MissingValueError.new(parent, self)
+				raise MissingValueError.new(parent, @key)
 			end
 		end
 	end

data/lib/samovar/option.rb

@@ -1,12 +1,26 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
-require_relative 'flags'
+require_relative "flags"
+require_relative "error"
 
 module Samovar
+	# Represents a single command-line option.
+	# 
+	# An option is a flag-based argument that can have various forms (short, long, with or without values).
 	class Option
+		# Initialize a new option.
+		# 
+		# @parameter flags [String] The flags specification (e.g., `-f/--flag <value>`).
+		# @parameter description [String] A description of the option for help output.
+		# @parameter key [Symbol | Nil] The key to use for storing the value (defaults to derived from flag).
+		# @parameter default [Object] The default value if the option is not provided.
+		# @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.
+		# @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)
 			@flags = Flags.new(flags)
 			@description = description
@@ -28,17 +42,50 @@ module Samovar
 			@block = block
 		end
 		
+		# The flags for this option.
+		# 
+		# @attribute [Flags]
 		attr :flags
+		
+		# A description of the option for help output.
+		# 
+		# @attribute [String]
 		attr :description
+		
+		# The key to use for storing the value.
+		# 
+		# @attribute [Symbol]
 		attr :key
+		
+		# The default value if the option is not provided.
+		# 
+		# @attribute [Object]
 		attr :default
 		
+		# A fixed value to use regardless of user input.
+		# 
+		# @attribute [Object | Nil]
 		attr :value
 		
+		# The type to coerce the value to.
+		# 
+		# @attribute [Class | Proc | Nil]
 		attr :type
+		
+		# Whether the option is required.
+		# 
+		# @attribute [Boolean]
 		attr :required
+		
+		# An optional block to transform the parsed value.
+		# 
+		# @attribute [Proc | Nil]
 		attr :block
 		
+		# Coerce the result to the specified type.
+		# 
+		# @parameter result [Object] The value to coerce.
+		# @returns [Object] The coerced value.
 		def coerce_type(result)
 			if @type == Integer
 				Integer(result)
@@ -53,6 +100,10 @@ module Samovar
 			end
 		end
 		
+		# Coerce and transform the result.
+		# 
+		# @parameter result [Object] The value to coerce and transform.
+		# @returns [Object] The coerced and transformed value.
 		def coerce(result)
 			if @type
 				result = coerce_type(result)
@@ -65,21 +116,30 @@ module Samovar
 			return result
 		end
 		
+		# Parse this option from the input.
+		# 
+		# @parameter input [Array(String)] The command-line arguments.
+		# @parameter parent [Command | Nil] The parent command (unused, kept for compatibility).
+		# @parameter default [Object | Nil] An override for the default value (unused, kept for compatibility).
+		# @returns [Object | Nil] The parsed value.
 		def parse(input, parent = nil, default = nil)
 			result = @flags.parse(input)
+			
 			if result != nil
 				@value.nil? ? coerce(result) : @value
-			elsif default ||= @default
-				return default
-			elsif @required
-				raise MissingValueError.new(parent, self)
 			end
 		end
 		
+		# Generate a string representation for usage output.
+		# 
+		# @returns [String] The usage string.
 		def to_s
 			@flags
 		end
 		
+		# Generate an array representation for usage output.
+		# 
+		# @returns [Array] The usage array.
 		def to_a
 			if @default
 				[@flags, @description, "(default: #{@default})"]