samovar 2.3.0 → 2.4.1

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)
 				

data/lib/samovar/output/usage_formatter.rb

@@ -1,33 +1,45 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2023, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
-require 'mapping/model'
-require 'console/terminal'
+require "mapping/model"
+require "console/terminal"
 
-require_relative '../error'
+require_relative "../error"
 
-require_relative 'header'
+require_relative "header"
 
-require_relative 'row'
-require_relative 'rows'
+require_relative "row"
+require_relative "rows"
 
 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
+			# Print usage information to the output.
+			# 
+			# @parameter rows [Rows] The rows to format and print.
+			# @parameter output [IO] The output stream to print to.
+			# @yields {|formatter| ...} Optional block to customize the formatter.
 			def self.print(rows, output)
-				formatter = self.new(rows, output)
+				formatter = self.new(output)
 				
 				yield formatter if block_given?
 				
-				formatter.print
+				formatter.print(rows)
 			end
 			
-			def initialize(rows, output)
-				@rows = rows
+			# Initialize a new usage formatter.
+			# 
+			# @parameter rows [Rows] The rows to format.
+			# @parameter output [IO] The output stream to print to.
+			def initialize(output)
 				@output = output
 				@width = 80
+				@first = true
 				
 				@terminal = Console::Terminal.for(@output)
 				@terminal[:header] = @terminal.style(nil, nil, :bright)
@@ -45,7 +57,11 @@ module Samovar
 			end
 			
 			map(Header) do |header, rows|
-				@terminal.puts unless header == @rows.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
@@ -64,8 +80,10 @@ module Samovar
 				items.collect{|row, rows| map(row, rows)}
 			end
 			
-			def print
-				map(@rows)
+			# Print the formatted usage output.
+			def print(rows, first: @first)
+				@first = first
+				map(rows)
 			end
 		end
 	end

data/lib/samovar/output.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2016-2023, by Samuel Williams.
+# Copyright, 2016-2025, by Samuel Williams.
 
-require_relative 'output/usage_formatter'
+require_relative "output/usage_formatter"

data/lib/samovar/split.rb

@@ -1,11 +1,21 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2016-2023, by Samuel Williams.
+# Copyright, 2016-2025, by Samuel Williams.
 
 module Samovar
+	# Represents a split point in the command-line arguments.
+	# 
+	# A `Split` parser divides the argument list at a marker (typically `--`), allowing you to separate arguments meant for your command from those passed to another tool.
 	class Split
-		def initialize(key, description, marker: '--', default: nil, required: false)
+		# Initialize a new split parser.
+		# 
+		# @parameter key [Symbol] The name of the attribute to store the values after the split.
+		# @parameter description [String] A description of the split for help output.
+		# @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)
 			@key = key
 			@description = description
 			@marker = marker
@@ -13,16 +23,41 @@ module Samovar
 			@required = required
 		end
 		
+		# The name of the attribute to store the values after the split.
+		# 
+		# @attribute [Symbol]
 		attr :key
+		
+		# A description of the split for help output.
+		# 
+		# @attribute [String]
 		attr :description
+		
+		# The marker that indicates the split point.
+		# 
+		# @attribute [String]
 		attr :marker
+		
+		# The default value if no split is present.
+		# 
+		# @attribute [Object]
 		attr :default
+		
+		# Whether the split is required.
+		# 
+		# @attribute [Boolean]
 		attr :required
 		
+		# Generate a string representation for usage output.
+		# 
+		# @returns [String] The usage string.
 		def to_s
 			"#{@marker} <#{@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 arguments after the split marker.
+		# 
+		# @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 arguments after the split, or the default if no split.
 		def parse(input, parent = nil, default = nil)
 			if offset = input.index(@marker)
 				input.pop(input.size - offset).tap(&:shift)
 			elsif default ||= @default
 				return default
 			elsif @required
-				raise MissingValueError.new(parent, self)
+				raise MissingValueError.new(parent, @key)
 			end
 		end
 	end

data/lib/samovar/table.rb

@@ -1,10 +1,18 @@
 # 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 table of parsing rows for a command.
+	# 
+	# A table manages the collection of options, arguments, and nested commands that define how to parse a command line.
 	class Table
+		# Create a nested table that inherits from the parent class's table.
+		# 
+		# @parameter klass [Class] The command class to create a table for.
+		# @parameter parent [Table | Nil] The parent table to inherit from.
+		# @returns [Table] The new table.
 		def self.nested(klass, parent = nil)
 			if klass.superclass.respond_to?(:table)
 				parent = klass.superclass.table
@@ -13,12 +21,19 @@ module Samovar
 			self.new(parent, name: klass.name)
 		end
 		
+		# Initialize a new table.
+		# 
+		# @parameter parent [Table | Nil] The parent table to inherit from.
+		# @parameter name [String | Nil] The name of the command this table belongs to.
 		def initialize(parent = nil, name: nil)
 			@parent = parent
 			@name = name
 			@rows = {}
 		end
 		
+		# Freeze this table.
+		# 
+		# @returns [Table] The frozen table.
 		def freeze
 			return self if frozen?
 			
@@ -27,14 +42,24 @@ module Samovar
 			super
 		end
 		
+		# Get a row by key.
+		# 
+		# @parameter key [Symbol] The key to look up.
+		# @returns [Object | Nil] The row with the given key.
 		def [] key
 			@rows[key]
 		end
 		
+		# Iterate over each row.
+		# 
+		# @yields {|row| ...} Each row in the table.
 		def each(&block)
 			@rows.each_value(&block)
 		end
 		
+		# Add a row to the table.
+		# 
+		# @parameter row The row to add.
 		def << row
 			if existing_row = @rows[row.key] and existing_row.respond_to?(:merge!)
 				existing_row.merge!(row)
@@ -44,10 +69,17 @@ module Samovar
 			end
 		end
 		
+		# Check if this table is empty.
+		# 
+		# @returns [Boolean] True if this table and its parent are empty.
 		def empty?
 			@rows.empty? && @parent&.empty?
 		end
 		
+		# Merge this table's rows into another table.
+		# 
+		# @parameter table [Table] The table to merge into.
+		# @returns [Table] The merged table.
 		def merge_into(table)
 			@parent&.merge_into(table)
 			
@@ -58,6 +90,9 @@ module Samovar
 			return table
 		end
 		
+		# Get a merged table that includes parent rows.
+		# 
+		# @returns [Table] The merged table.
 		def merged
 			if @parent.nil? or @parent.empty?
 				return self
@@ -66,10 +101,17 @@ module Samovar
 			end
 		end
 		
+		# Generate a usage string from all rows.
+		# 
+		# @returns [String] The usage string.
 		def usage
-			@rows.each_value.collect(&:to_s).reject(&:empty?).join(' ')
+			@rows.each_value.collect(&:to_s).reject(&:empty?).join(" ")
 		end
 		
+		# Parse the input according to the rows in this table.
+		# 
+		# @parameter input [Array(String)] The command-line arguments.
+		# @parameter parent [Command] The parent command to store results in.
 		def parse(input, parent)
 			@rows.each do |key, row|
 				next unless row.respond_to?(:parse)

data/lib/samovar/version.rb

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2016-2023, by Samuel Williams.
+# Copyright, 2016-2025, by Samuel Williams.
 # Copyright, 2018, by Gabriel Mazetto.
 
+# @namespace
 module Samovar
-	VERSION = "2.3.0"
+	VERSION = "2.4.1"
 end

data/lib/samovar.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2016-2023, by Samuel Williams.
+# Copyright, 2016-2025, by Samuel Williams.
 
-require_relative 'samovar/version'
-require_relative 'samovar/command'
+require_relative "samovar/version"
+require_relative "samovar/command"

data/license.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright, 2016-2024, by Samuel Williams.  
+Copyright, 2016-2025, by Samuel Williams.  
 Copyright, 2018, by Gabriel Mazetto.  
 
 Permission is hereby granted, free of charge, to any person obtaining a copy