samovar 2.3.0 → 2.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e30e7064ff47b5ddb9d3461d291513e310fe7000d96abf00c473447d76c4f17
-  data.tar.gz: 3ec1e17b743863c3df573f959450922c9aec4fcedbf4fe8a690657effcc643f6
+  metadata.gz: e1051db069257cf9d25e3599a5ddb5c5547a921cb90d04552a777d3af5c335b2
+  data.tar.gz: 632d0819eb51db7f9640feb8491e543706721a4313243527bb5380da576a578b
 SHA512:
-  metadata.gz: 16adeb378b0451726310d57f76b7223c37a51a43fbf21d1348c3d309b94ae1b99fb943736362c3c66f0b1c651630982f9a5eba5b32bfb8202c0704370e67a6cc
-  data.tar.gz: b9bbcfbdc77d330992c47eebfdb10c612d57f140ef0b6e8f97204e3d67d2ccf2f020313cdf54c816122cebb279c82a315db40820d60ef74f41de118c7f5d4873
+  metadata.gz: f5daa04c5dff0500f95c9dec3cabe02bbbb10fd5a9d5a06f89f6d9e6687eb11af89325472df628170ea04d0458d3c8600849c4fab1299c83bf523e58e1e268ed
+  data.tar.gz: 304cc7d54293e3998dae9e3e3247506db3f82d2d0f6d66e988b4ad21cad0150846a1325a039c4dd3f4746fe0903e6e6afd5a6e2f615d724d7e7ee788da49310b

data/context/getting-started.md

@@ -0,0 +1,215 @@
+# Getting Started
+
+This guide explains how to use `samovar` to build command-line tools and applications.
+
+## Installation
+
+Add the gem to your project:
+
+~~~ bash
+$ bundle add samovar
+~~~
+
+Or install it yourself as:
+
+~~~ bash
+$ gem install samovar
+~~~
+
+## Core Concepts
+
+Samovar provides a declarative class-based DSL for building command-line parsers. The main concepts include:
+
+- **Commands**: Classes that represent specific functions in your program, inheriting from {ruby Samovar::Command}.
+- **Options**: Command-line flags and arguments that can be parsed using the `options` block.
+- **Nested Commands**: Sub-commands that can be composed using the `nested` method.
+- **Tokens**: Positional arguments parsed using `one` and `many` methods.
+- **Splits**: Separating arguments at a specific delimiter (e.g., `--`) using the `split` method.
+
+## Usage
+
+Create `Command` classes that represent specific functions in your program. The top level command might look something like this:
+
+~~~ ruby
+require "samovar"
+
+class List < Samovar::Command
+	self.description = "List the current directory"
+	
+	def call
+		system("ls -lah")
+	end
+end
+
+class Application < Samovar::Command
+	options do
+		option "--help", "Do you need help?"
+	end
+	
+	nested :command, {
+		"list" => List
+	}, default: "list"
+	
+	def call
+		if @options[:help]
+			self.print_usage
+		else
+			@command.call
+		end
+	end
+end
+
+Application.call # Defaults to ARGV.
+~~~
+
+### Basic Options
+
+Options allow you to parse command-line flags and arguments:
+
+~~~ ruby
+require "samovar"
+
+class Application < Samovar::Command
+	options do
+		option "-f/--frobulate <text>", "Frobulate the text"
+		option "-x | -y", "Specify either x or y axis.", key: :axis
+		option "-F/--yeah/--flag", "A boolean flag with several forms."
+		option "--things <a,b,c>", "A list of things" do |value|
+			value.split(/\s*,\s*/)
+		end
+	end
+end
+
+application = Application.new(["-f", "Algebraic!"])
+application.options[:frobulate] # 'Algebraic!'
+
+application = Application.new(["-x", "-y"])
+application.options[:axis] # :y
+
+application = Application.new(["-F"])
+application.options[:flag] # true
+
+application = Application.new(["--things", "x,y,z"])
+application.options[:things] # ['x', 'y', 'z']
+~~~
+
+### Nested Commands
+
+You can create sub-commands that are nested within your main application:
+
+~~~ ruby
+require "samovar"
+
+class Create < Samovar::Command
+	def invoke(parent)
+		puts "Creating"
+	end
+end
+
+class Application < Samovar::Command
+	nested "<command>",
+		"create" => Create
+	
+	def invoke(program_name: File.basename($0))
+		if @command
+			@command.invoke
+		else
+			print_usage(program_name)
+		end
+	end
+end
+
+Application.new(["create"]).invoke
+~~~
+
+### ARGV Splits
+
+You can split arguments at a delimiter (typically `--`):
+
+~~~ ruby
+require "samovar"
+
+class Application < Samovar::Command
+	many :packages
+	split :argv
+end
+
+application = Application.new(["foo", "bar", "baz", "--", "apples", "oranges", "feijoas"])
+application.packages # ['foo', 'bar', 'baz']
+application.argv # ['apples', 'oranges', 'feijoas']
+~~~
+
+### Parsing Tokens
+
+You can parse positional arguments using `one` and `many`:
+
+~~~ ruby
+require "samovar"
+
+class Application < Samovar::Command
+	self.description = "Mix together your favorite things."
+	
+	one :fruit, "Name one fruit"
+	many :cakes, "Any cakes you like"
+end
+
+application = Application.new(["apple", "chocolate cake", "fruit cake"])
+application.fruit # 'apple'
+application.cakes # ['chocolate cake', 'fruit cake']
+~~~
+
+### Explicit Commands
+
+Given a custom `Samovar::Command` subclass, you can instantiate it with options:
+
+~~~ ruby
+application = Application["--root", path]
+~~~
+
+You can also duplicate an existing command instance with additions/changes:
+
+~~~ ruby
+concurrent_application = application["--threads", 12]
+~~~
+
+These forms can be useful when invoking one command from another, or in unit tests.
+
+## Error Handling
+
+Samovar provides two entry points with different error handling behaviors:
+
+### `call()` - High-Level Entry Point
+
+Use `call()` for CLI applications. It handles parsing errors gracefully by printing usage information:
+
+~~~ ruby
+# Automatically handles errors and prints usage
+Application.call(ARGV)
+~~~
+
+If parsing fails or the command raises a {ruby Samovar::Error}, it will:
+- Print the usage information with the error highlighted
+- Return `nil` instead of raising an exception
+
+### `parse()` - Low-Level Parsing
+
+Use `parse()` when you need explicit error handling or for testing:
+
+~~~ ruby
+begin
+  app = Application.parse(["--unknown-flag"])
+rescue Samovar::InvalidInputError => error
+  # Handle the error yourself
+  puts "Invalid input: #{error.message}"
+end
+~~~
+
+The `parse()` method raises exceptions on parsing errors, giving you full control over error handling.
+
+### Error Types
+
+Samovar defines several error types:
+
+- {ruby Samovar::InvalidInputError}: Raised when unexpected command-line input is encountered
+- {ruby Samovar::MissingValueError}: Raised when required arguments or options are missing
+

data/context/index.yaml

@@ -0,0 +1,14 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: Samovar is a flexible option parser excellent support for sub-commands
+  and help documentation.
+metadata:
+  documentation_uri: https://ioquatix.github.io/samovar/
+  funding_uri: https://github.com/sponsors/ioquatix/
+  source_code_uri: https://github.com/ioquatix/samovar.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to use `samovar` to build command-line tools
+    and applications.

data/lib/samovar/command.rb

@@ -1,54 +1,85 @@
 # 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)
-				warning "Method for key #{row.key} is already defined!", caller
-				# raise ArgumentError, "Method for key #{row.key} is already defined!"
+				raise ArgumentError, "Method for key #{row.key} is already defined!"
 			end
 			
 			attr_accessor(row.key) if row.respond_to?(:key)
@@ -56,26 +87,51 @@ module Samovar
 			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
@@ -90,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
@@ -106,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)
 			
@@ -133,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