samovar 2.2.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5439e3891e6619b96a1c07a1e47da8566e670c21fc5d8cbb083cc256c302cbb3
-  data.tar.gz: e6a3830369c9f274e1e968205e2b172bbfefec4c1c9780637e2bdd9d8e22a252
+  metadata.gz: 85e0df9ca2ed86284ab62c49ef724f93818ecb8571a33cccca98759f0a6b2612
+  data.tar.gz: 833c98f6619c7fb73243f6bbbbbb84e25a8d100c03af55392bd97f20a4246803
 SHA512:
-  metadata.gz: 3555993209a03ec7ed58c015391675a5ba4b04552b2a5e82116590431afffd435f77bf64155cfff5ca5cb177c4f6ea744f85e11a93647fc379cc51b131fbf155
-  data.tar.gz: ca79ebbc4254117b212ff5274a6d5bcd685ee599f4125f031dffdbbec81d5122fe2b1e0b63cb586580d4c429a5c4513104fd55a9ecbdf3ffd2c76165f7bd565c
+  metadata.gz: 0aff1d4bc6f8c2154dcd7e216a8f082fc50b44239321a122b139edff54e0749ab7109a45ab87e2615677e181426717b4912d81118f87f01cd4bf7032653d2041
+  data.tar.gz: d3c94b2986da89eba71d18d06df18dd0541775f2f1c2ba2c327e8407a38e05757e073b5f97c137c8c0241ab29811fd9e0a3fed3c2613034ca7db15ef0e5aff12

data/lib/samovar/command.rb

@@ -1,76 +1,137 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2016-2023, by Samuel Williams.
+# Copyright, 2016-2025, by Samuel Williams.
 
-require_relative 'table'
-require_relative 'options'
-require_relative 'nested'
-require_relative 'one'
-require_relative 'many'
-require_relative 'split'
+require_relative "table"
+require_relative "options"
+require_relative "nested"
+require_relative "one"
+require_relative "many"
+require_relative "split"
 
-require_relative 'output'
 
-require_relative 'error'
+require_relative "output"
+
+require_relative "error"
 
 module Samovar
+	# Represents a command in the command-line interface.
+	# 
+	# Commands are the main building blocks of Samovar applications. Each command is a class that can parse command-line arguments, options, and sub-commands.
 	class Command
-		def self.call(input = ARGV)
-			if command = self.parse(input)
-				command.call
-			end
-		end
-		
-		# The top level entry point for parsing ARGV.
-		def self.parse(input)
-			self.new(input)
+		# 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.
+		# 
+		# @parameter input [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
 		rescue Error => error
-			error.command.print_usage(output: $stderr) do |formatter|
+			error.command.print_usage(output: output) do |formatter|
 				formatter.map(error)
 			end
 			
 			return nil
 		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.
+		# @returns [Command] The parsed command instance.
+		# @raises [Error] If parsing fails.
+		def self.parse(input)
+			self.new(input)
+		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 options [Hash] Additional options to pass to the command.
+		# @returns [Command] The command instance.
 		def self.[](*input, **options)
 			self.new(input, **options)
 		end
 		
 		class << self
+			# A description of the command's purpose.
+			# 
+			# @attribute [String]
 			attr_accessor :description
 		end
 		
+		# The table of rows for parsing command-line arguments.
+		# 
+		# @returns [Table] The table of parsing rows.
 		def self.table
 			@table ||= Table.nested(self)
 		end
 		
+		# Append a row to the parsing table.
+		# 
+		# @parameter row The row to append to the table.
 		def self.append(row)
+			if method_defined?(row.key, false)
+				raise ArgumentError, "Method for key #{row.key} is already defined!"
+			end
+			
 			attr_accessor(row.key) if row.respond_to?(:key)
 			
 			self.table << row
 		end
 		
+		# Define command-line options for this command.
+		# 
+		# @parameter arguments [Array] The arguments for the options.
+		# @parameter options [Hash] Additional options.
+		# @yields {|...| ...} A block that defines the options using {Options}.
 		def self.options(*arguments, **options, &block)
 			append Options.parse(*arguments, **options, &block)
 		end
 		
+		# Define a nested sub-command.
+		# 
+		# @parameter arguments [Array] The arguments for the nested command.
+		# @parameter options [Hash] A hash mapping command names to command classes.
 		def self.nested(*arguments, **options)
 			append Nested.new(*arguments, **options)
 		end
 		
+		# Define a single required positional argument.
+		# 
+		# @parameter arguments [Array] The arguments for the positional parameter.
+		# @parameter options [Hash] Additional options.
 		def self.one(*arguments, **options)
 			append One.new(*arguments, **options)
 		end
 		
+		# Define multiple positional arguments.
+		# 
+		# @parameter arguments [Array] The arguments for the positional parameters.
+		# @parameter options [Hash] Additional options.
 		def self.many(*arguments, **options)
 			append Many.new(*arguments, **options)
 		end
 		
+		# Define a split point in the argument list (typically `--`).
+		# 
+		# @parameter arguments [Array] The arguments for the split.
+		# @parameter options [Hash] Additional options.
 		def self.split(*arguments, **options)
 			append Split.new(*arguments, **options)
 		end
 		
+		# Generate usage information for this command.
+		# 
+		# @parameter rows [Output::Rows] The rows to append usage information to.
+		# @parameter name [String] The name of the command.
 		def self.usage(rows, name)
 			rows.nested(name, self) do |rows|
 				return unless table = self.table.merged
@@ -85,14 +146,22 @@ module Samovar
 			end
 		end
 		
+		# Generate a command-line usage string.
+		# 
+		# @parameter name [String] The name of the command.
+		# @returns [String] The command-line usage string.
 		def self.command_line(name)
-			if table = self.table.merged
-				"#{name} #{table.merged.usage}"
-			else
-				name
-			end
+			table = self.table.merged
+			
+			return "#{name} #{table.usage}"
 		end
 		
+		# Initialize a new command instance.
+		# 
+		# @parameter input [Array(String) | Nil] The command-line arguments to parse.
+		# @parameter name [String] The name of the command (defaults to the script name).
+		# @parameter parent [Command | Nil] The parent command, if this is a nested command.
+		# @parameter output [IO | Nil] The output stream for usage information.
 		def initialize(input = nil, name: File.basename($0), parent: nil, output: nil)
 			@name = name
 			@parent = parent
@@ -101,23 +170,47 @@ module Samovar
 			parse(input) if input
 		end
 		
+		# The output stream for usage information.
+		# 
+		# @attribute [IO]
 		attr :output
 		
+		# The output stream for usage information, defaults to `$stdout`.
+		# 
+		# @returns [IO] The output stream.
 		def output
 			@output || $stdout
 		end
 		
+		# Generate a string representation of the command.
+		# 
+		# @returns [String] The class name.
 		def to_s
 			self.class.name
 		end
 		
+		# The name of the command.
+		# 
+		# @attribute [String]
 		attr :name
+		
+		# The parent command, if this is a nested command.
+		# 
+		# @attribute [Command | Nil]
 		attr :parent
 		
+		# Duplicate the command with additional arguments.
+		# 
+		# @parameter input [Array(String)] The additional command-line arguments to parse.
+		# @returns [Command] The duplicated command instance.
 		def [](*input)
 			self.dup.tap{|command| command.parse(input)}
 		end
 		
+		# Parse the command-line input.
+		# 
+		# @parameter input [Array(String)] The command-line arguments to parse.
+		# @returns [Command] The command instance.
 		def parse(input)
 			self.class.table.merged.parse(input, self)
 			
@@ -128,6 +221,11 @@ module Samovar
 			end
 		end
 		
+		# Print usage information for this command.
+		# 
+		# @parameter output [IO] The output stream to print to.
+		# @parameter formatter [Class] The formatter class to use for output.
+		# @yields {|formatter| ...} A block to customize the output.
 		def print_usage(output: self.output, formatter: Output::UsageFormatter, &block)
 			rows = Output::Rows.new
 			

data/lib/samovar/error.rb

@@ -1,13 +1,19 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2023, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
 module Samovar
+	# The base class for all Samovar errors.
 	class Error < StandardError
 	end
-		
+	
+	# Raised when invalid input is provided on the command line.
 	class InvalidInputError < Error
+		# Initialize a new invalid input error.
+		# 
+		# @parameter command [Command] The command that encountered the error.
+		# @parameter input [Array(String)] The remaining input that could not be parsed.
 		def initialize(command, input)
 			@command = command
 			@input = input
@@ -15,19 +21,37 @@ module Samovar
 			super "Could not parse token #{input.first.inspect}"
 		end
 		
+		# The token that could not be parsed.
+		# 
+		# @returns [String] The first unparsed token.
 		def token
 			@input.first
 		end
 		
+		# Check if the error was caused by a help request.
+		# 
+		# @returns [Boolean] True if the token is `--help`.
 		def help?
 			self.token == "--help"
 		end
 		
+		# The command that encountered the error.
+		# 
+		# @attribute [Command]
 		attr :command
+		
+		# The remaining input that could not be parsed.
+		# 
+		# @attribute [Array(String)]
 		attr :input
 	end
 	
+	# Raised when a required value is missing.
 	class MissingValueError < Error
+		# Initialize a new missing value error.
+		# 
+		# @parameter command [Command] The command that encountered the error.
+		# @parameter field [Symbol] The name of the missing field.
 		def initialize(command, field)
 			@command = command
 			@field = field
@@ -35,7 +59,14 @@ module Samovar
 			super "#{field} is required"
 		end
 		
+		# The command that encountered the error.
+		# 
+		# @attribute [Command]
 		attr :command
+		
+		# The name of the missing field.
+		# 
+		# @attribute [Symbol]
 		attr :field
 	end
 end

data/lib/samovar/failure.rb

@@ -4,6 +4,7 @@
 # Copyright, 2017-2023, by Samuel Williams.
 
 module Samovar
+	# Represents a runtime failure in command execution.
 	class Failure < RuntimeError
 	end
 end

data/lib/samovar/flags.rb

@@ -1,40 +1,65 @@
 # 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 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.new(part)}
+			@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.value.nil?
+			@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(' | ') + ']'
+			"[#{@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|
-				if result = flag.parse(input)
+				result = flag.parse(input)
+				if result != nil
 					return result
 				end
 			end
@@ -43,46 +68,168 @@ 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
-		def initialize(text)
-			@text = text
-			
+		# 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(\<.*?\>)/
-				@prefix = $1
-				@value = $2
+				ValueFlag.new(text, $1, $2)
+			elsif text =~ /--\[no\]-(.*?)$/
+				BooleanFlag.new(text, "--#{$1}")
 			else
-				@prefix = @text
-				@value = nil
+				ValueFlag.new(text, text, nil)
 			end
-			
-			*@alternatives, @prefix = @prefix.split('/')
 		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
-		attr :value
 		
+		# Generate a string representation for usage output.
+		# 
+		# @returns [String] The flag text.
 		def to_s
 			@text
 		end
 		
-		def prefix?(token)
-			@prefix == token or @alternatives.include?(token)
+		# Generate a key name for this flag.
+		# 
+		# @returns [Symbol] The key name.
+		def key
+			@key ||= @prefix.sub(/^-*/, "").gsub("-", "_").to_sym
 		end
 		
-		def key
-			@key ||= @prefix.sub(/^-*/, '').gsub('-', '_').to_sym
+		# 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("/")
+		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
-					input.shift(2).last
+					# Get the actual value from input:
+					flag, value = input.shift(2)
+					return value
 				else
-					input.shift; key
+					# Otherwise, we are just a boolean flag:
+					input.shift
+					return key
 				end
 			end
 		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-")
+			@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
+				return true
+			elsif input.first == @negated
+				input.shift
+				return false
+			end
+		end
+	end
 end

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