samovar 2.3.0 → 2.4.0

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})"]

data/lib/samovar/options.rb

@@ -1,12 +1,21 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2016-2024, by Samuel Williams.
+# Copyright, 2016-2025, by Samuel Williams.
 
-require_relative 'option'
+require_relative "option"
 
 module Samovar
+	# Represents a collection of command-line options.
+	# 
+	# Options provide a DSL for defining multiple option flags in a single block.
 	class Options
+		# Parse and create an options collection from a block.
+		# 
+		# @parameter arguments [Array] The arguments for the options collection.
+		# @parameter options [Hash] Additional options.
+		# @yields {|...| ...} A block that defines options using {#option}.
+		# @returns [Options] The frozen options collection.
 		def self.parse(*arguments, **options, &block)
 			options = self.new(*arguments, **options)
 			
@@ -15,6 +24,10 @@ module Samovar
 			return options.freeze
 		end
 		
+		# Initialize a new options collection.
+		# 
+		# @parameter title [String] The title for this options group in usage output.
+		# @parameter key [Symbol] The key to use for storing parsed options.
 		def initialize(title = "Options", key: :options)
 			@title = title
 			@ordered = []
@@ -27,6 +40,9 @@ module Samovar
 			@defaults = {}
 		end
 		
+		# Initialize a duplicate of this options collection.
+		# 
+		# @parameter source [Options] The source options to duplicate.
 		def initialize_dup(source)
 			super
 			
@@ -35,12 +51,29 @@ module Samovar
 			@defaults = @defaults.dup
 		end
 		
+		# The title for this options group in usage output.
+		# 
+		# @attribute [String]
 		attr :title
+		
+		# The ordered list of options.
+		# 
+		# @attribute [Array(Option)]
 		attr :ordered
 		
+		# The key to use for storing parsed options.
+		# 
+		# @attribute [Symbol]
 		attr :key
+		
+		# The default values for options.
+		# 
+		# @attribute [Hash]
 		attr :defaults
 		
+		# Freeze this options collection.
+		# 
+		# @returns [Options] The frozen options collection.
 		def freeze
 			return self if frozen?
 			
@@ -53,24 +86,41 @@ module Samovar
 			super
 		end
 		
+		# Iterate over each option.
+		# 
+		# @yields {|option| ...} Each option in the collection.
 		def each(&block)
 			@ordered.each(&block)
 		end
 		
+		# Check if this options collection is empty.
+		# 
+		# @returns [Boolean] True if there are no options.
 		def empty?
 			@ordered.empty?
 		end
 		
+		# Define a new option in this collection.
+		# 
+		# @parameter arguments [Array] The arguments for the option.
+		# @parameter options [Hash] Additional options.
+		# @yields {|value| ...} An optional block to transform the parsed value.
 		def option(*arguments, **options, &block)
 			self << Option.new(*arguments, **options, &block)
 		end
 		
+		# Merge another options collection into this one.
+		# 
+		# @parameter options [Options] The options to merge.
 		def merge!(options)
 			options.each do |option|
 				self << option
 			end
 		end
 		
+		# Add an option to this collection.
+		# 
+		# @parameter option [Option] The option to add.
 		def << option
 			@ordered << option
 			option.flags.each do |flag|
@@ -86,24 +136,41 @@ module Samovar
 			end
 		end
 		
+		# Parse options from the input.
+		# 
+		# @parameter input [Array(String)] The command-line arguments.
+		# @parameter parent [Command | Nil] The parent command.
+		# @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
 			
 			while option = @keyed[input.first]
-				prefix = input.first
+				# prefix = input.first
 				result = option.parse(input)
 				if result != nil
 					values[option.key] = result
 				end
 			end
 			
+			# Validate required options
+			@ordered.each do |option|
+				if option.required && !values.key?(option.key)
+					raise MissingValueError.new(parent, option.key)
+				end
+			end
+			
 			return values
-		end
-		
+		end		# Generate a string representation for usage output.
+		# 
+		# @returns [String] The usage string.
 		def to_s
-			@ordered.collect(&:to_s).join(' ')
+			@ordered.collect(&:to_s).join(" ")
 		end
 		
+		# Generate usage information for this options collection.
+		# 
+		# @parameter rows [Output::Rows] The rows to append usage information to.
 		def usage(rows)
 			@ordered.each do |option|
 				rows << option

data/lib/samovar/output/columns.rb

@@ -4,15 +4,34 @@
 # Copyright, 2016-2023, by Samuel Williams.
 
 module Samovar
+	# Namespace for output formatting classes.
 	module Output
+	end
+end
+
+module Samovar
+	module Output
+		# Represents column widths for aligned output formatting.
+		# 
+		# Calculates the maximum width of each column across all rows for proper text alignment.
 		class Columns
+			# Initialize column width calculator.
+			# 
+			# @parameter rows [Array(Array)] The rows to calculate column widths from.
 			def initialize(rows)
 				@rows = rows
 				@widths = calculate_widths(rows)
 			end
 			
+			# The calculated column widths.
+			# 
+			# @attribute [Array(Integer)]
 			attr :widths
 			
+			# Calculate the maximum width for each column.
+			# 
+			# @parameter rows [Array(Array)] The rows to analyze.
+			# @returns [Array(Integer)] The maximum width of each column.
 			def calculate_widths(rows)
 				widths = []
 				

data/lib/samovar/output/header.rb

@@ -5,15 +5,33 @@
 
 module Samovar
 	module Output
+		# Represents a header row in usage output.
+		# 
+		# Headers display command names and their descriptions.
 		class Header
+			# Initialize a new header.
+			# 
+			# @parameter name [String] The command name.
+			# @parameter object [Command] The command class.
 			def initialize(name, object)
 				@name = name
 				@object = object
 			end
 			
+			# The command name.
+			# 
+			# @attribute [String]
 			attr :name
+			
+			# The command class.
+			# 
+			# @attribute [Command]
 			attr :object
 			
+			# Generate an aligned header string.
+			# 
+			# @parameter columns [Columns] The columns for alignment (unused for headers).
+			# @returns [String] The command line usage string.
 			def align(columns)
 				@object.command_line(@name)
 			end

data/lib/samovar/output/row.rb

@@ -1,22 +1,35 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2023, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
 module Samovar
 	module Output
+		# Represents a row in usage output.
+		# 
+		# Rows display formatted option or argument information with proper column alignment.
 		class Row < Array
+			# Initialize a new row.
+			# 
+			# @parameter object [Object] The object to convert to a row (must respond to `to_a`).
 			def initialize(object)
 				@object = object
 				super object.to_a.collect(&:to_s)
 			end
 			
+			# The source object for this row.
+			# 
+			# @attribute [Object]
 			attr :object
 			
+			# Generate an aligned row string.
+			# 
+			# @parameter columns [Columns] The columns for alignment.
+			# @returns [String] The aligned row string.
 			def align(columns)
 				self.collect.with_index do |value, index|
 					value.ljust(columns.widths[index])
-				end.join('  ')
+				end.join("  ")
 			end
 		end
 	end

data/lib/samovar/output/rows.rb

@@ -1,40 +1,65 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2023, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
-require_relative 'header'
-require_relative 'columns'
-require_relative 'row'
+require_relative "header"
+require_relative "columns"
+require_relative "row"
 
 module Samovar
 	module Output
+		# Represents a collection of rows for usage output.
+		# 
+		# Manages hierarchical usage information with support for nesting and formatting.
 		class Rows
 			include Enumerable
 			
+			# Initialize a new rows collection.
+			# 
+			# @parameter level [Integer] The indentation level for this collection.
 			def initialize(level = 0)
 				@level = level
 				@rows = []
 			end
 			
+			# The indentation level.
+			# 
+			# @attribute [Integer]
 			attr :level
 			
+			# Check if this collection is empty.
+			# 
+			# @returns [Boolean] True if there are no rows.
 			def empty?
 				@rows.empty?
 			end
 			
+			# Get the first row.
+			# 
+			# @returns [Object | Nil] The first row.
 			def first
 				@rows.first
 			end
 			
+			# Get the last row.
+			# 
+			# @returns [Object | Nil] The last row.
 			def last
 				@rows.last
 			end
 			
+			# Get the indentation string for this level.
+			# 
+			# @returns [String] The indentation string.
 			def indentation
 				@indentation ||= "\t" * @level
 			end
 			
+			# Iterate over each row.
+			# 
+			# @parameter ignore_nested [Boolean] Whether to skip nested rows.
+			# @yields {|row, rows| ...} Each row with its parent collection.
 			def each(ignore_nested: false, &block)
 				return to_enum(:each, ignore_nested: ignore_nested) unless block_given?
 				
@@ -47,16 +72,27 @@ module Samovar
 				end
 			end
 			
+			# Add a row to this collection.
+			# 
+			# @parameter object [Object] The object to add as a row.
+			# @returns [Rows] Self.
 			def << object
 				@rows << Row.new(object)
 				
 				return self
 			end
 			
+			# Get the columns for alignment.
+			# 
+			# @returns [Columns] The columns calculator.
 			def columns
 				@columns ||= Columns.new(@rows.select{|row| row.is_a? Array})
 			end
 			
+			# Create a nested section in the output.
+			# 
+			# @parameter arguments [Array] Arguments for the header.
+			# @yields {|rows| ...} A block that populates the nested rows.
 			def nested(*arguments)
 				@rows << Header.new(*arguments)