samovar 2.4.0 → 2.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85e0df9ca2ed86284ab62c49ef724f93818ecb8571a33cccca98759f0a6b2612
-  data.tar.gz: 833c98f6619c7fb73243f6bbbbbb84e25a8d100c03af55392bd97f20a4246803
+  metadata.gz: 467711ed04ecc759513ab6187d17a8c5208fa24869d202fb23a46217d3ceedab
+  data.tar.gz: 293c9e07e9f0ff0b9550b0ad3411b5e10f460a6c72dd8be2bc254d985dec95da
 SHA512:
-  metadata.gz: 0aff1d4bc6f8c2154dcd7e216a8f082fc50b44239321a122b139edff54e0749ab7109a45ab87e2615677e181426717b4912d81118f87f01cd4bf7032653d2041
-  data.tar.gz: d3c94b2986da89eba71d18d06df18dd0541775f2f1c2ba2c327e8407a38e05757e073b5f97c137c8c0241ab29811fd9e0a3fed3c2613034ca7db15ef0e5aff12
+  metadata.gz: bf717af75e91db10dc75008e1421601181168190aa89ea5bd289ca5e832505d1382cee60ac7e1b66d4500673779cc2cc5325dc33110ce4871443fa93c820d817
+  data.tar.gz: c7c0f9b82b3ce5502c29da74b7810f69c63687237b2a7550dde8ff5eda35f3db6739848907d9669a2083df9ec186097c90d44e4e119aa1176ca1c6a52c7f6f07

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/failure.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2023, by Samuel Williams.
+# Copyright, 2017-2026, by Samuel Williams.
 
 module Samovar
 	# Represents a runtime failure in command execution.

data/lib/samovar/many.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2016-2023, by Samuel Williams.
+# Copyright, 2016-2026, by Samuel Williams.
 
 module Samovar
 	# Represents multiple positional arguments in a command.

data/lib/samovar/nested.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2016-2023, by Samuel Williams.
+# Copyright, 2016-2026, by Samuel Williams.
 
 module Samovar
 	# Represents nested sub-commands in a command.

data/lib/samovar/one.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2016-2023, by Samuel Williams.
+# Copyright, 2016-2026, by Samuel Williams.
 
 module Samovar
 	# Represents a single positional argument in a command.

data/lib/samovar/output/columns.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2016-2023, by Samuel Williams.
+# Copyright, 2016-2026, by Samuel Williams.
 
 module Samovar
 	# Namespace for output formatting classes.

data/lib/samovar/output/header.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2023, by Samuel Williams.
+# Copyright, 2019-2026, by Samuel Williams.
 
 module Samovar
 	module Output

data/lib/samovar/output/usage_formatter.rb

@@ -2,8 +2,8 @@
 
 # Released under the MIT License.
 # Copyright, 2019-2025, by Samuel Williams.
+# Copyright, 2026, by Gerhard Schlager.
 
-require "mapping/model"
 require "console/terminal"
 
 require_relative "../error"
@@ -17,8 +17,8 @@ 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
+		# Dispatches on the type of each output object to apply custom formatting rules.
+		class UsageFormatter
 			# Print usage information to the output.
 			# 
 			# @parameter rows [Rows] The rows to format and print.
@@ -39,7 +39,6 @@ module Samovar
 			def initialize(output)
 				@output = output
 				@width = 80
-				@first = true
 				
 				@terminal = Console::Terminal.for(@output)
 				@terminal[:header] = @terminal.style(nil, nil, :bright)
@@ -47,43 +46,50 @@ module Samovar
 				@terminal[:error] = @terminal.style(:red)
 			end
 			
-			map(InvalidInputError) do |error|
-				# This is a little hack which avoids printing out "--help" if it was part of an incomplete parse. In the future I'd prefer if this was handled explicitly.
-				@terminal.puts("#{error.message} in:", style: :error) unless error.help?
-			end
-			
-			map(MissingValueError) do |error|
-				@terminal.puts("#{error.message} in:", style: :error)
-			end
-			
-			map(Header) do |header, rows|
-				if @first
-					@first = false
+			# Format and print the given object according to its type.
+			# 
+			# @parameter object [Object] The object to format (a {Rows}, {Row}, {Header}, or error).
+			# @parameter arguments [Array] Extra context passed through to nested rows (the containing {Rows}).
+			def map(object, *arguments, first: true)
+				case object
+				when InvalidInputError
+					# This is a little hack which avoids printing out "--help" if it was part of an incomplete parse. In the future I'd prefer if this was handled explicitly.
+					@terminal.puts("#{object.message} in:", style: :error) unless object.help?
+				when MissingValueError
+					@terminal.puts("#{object.message} in:", style: :error)
+				when Header
+					header, rows = object, arguments.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
+					
+					if description = header.object.description
+						@terminal.puts "#{rows.indentation}\t#{description}", style: :description
+						@terminal.puts
+					end
+				when Row
+					row, rows = object, arguments.first
+					@terminal.puts "#{rows.indentation}#{row.align(rows.columns)}"
+				when Rows
+					object.each do |row, rows|
+						first = map(row, rows, first: first)
+					end
 				else
-					@terminal.puts
+					raise ArgumentError, "Unable to format #{object.class}!"
 				end
 				
-				command_line = header.object.command_line(header.name)
-				@terminal.puts "#{rows.indentation}#{command_line}", style: :header
-				
-				if description = header.object.description
-					@terminal.puts "#{rows.indentation}\t#{description}", style: :description
-					@terminal.puts
-				end
-			end
-			
-			map(Row) do |row, rows|
-				@terminal.puts "#{rows.indentation}#{row.align(rows.columns)}"
-			end
-			
-			map(Rows) do |items|
-				items.collect{|row, rows| map(row, rows)}
+				return first
 			end
 			
 			# Print the formatted usage output.
-			def print(rows, first: @first)
-				@first = first
-				map(rows)
+			def print(rows, first: true)
+				map(rows, first: first)
 			end
 		end
 	end

data/lib/samovar/version.rb

@@ -6,5 +6,5 @@
 
 # @namespace
 module Samovar
-	VERSION = "2.4.0"
+	VERSION = "2.4.2"
 end

data/license.md

@@ -1,7 +1,8 @@
 # MIT License
 
-Copyright, 2016-2025, by Samuel Williams.  
+Copyright, 2016-2026, by Samuel Williams.  
 Copyright, 2018, by Gabriel Mazetto.  
+Copyright, 2026, by Gerhard Schlager.  
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/readme.md

@@ -18,6 +18,32 @@ Please see the [project documentation](https://ioquatix.github.io/samovar/) for
 
   - [Getting Started](https://ioquatix.github.io/samovar/guides/getting-started/index) - This guide explains how to use `samovar` to build command-line tools and applications.
 
+## Releases
+
+Please see the [project releases](https://ioquatix.github.io/samovar/releases/index) for all releases.
+
+### v2.4.2
+
+  - Drop dependency on `mapping` gem.
+
+### v2.4.0
+
+  - Fix option parsing and validation: required options are now detected correctly and raise `Samovar::MissingValueError` when missing.
+  - Fix flag value parsing: flags that expect a value no longer consume a following flag as their value (e.g. `--config <path>` will not consume `--verbose`).
+  - Usage improvements: required options are marked as `(required)` in usage output.
+
+### v2.3.0
+
+  - Add support for `--[no]-thing` explicit boolean flags, allowing users to explicitly enable or disable boolean options.
+
+### v2.2.0
+
+  - Add support for explicit output: commands can now specify an output stream (e.g. `STDOUT`, `STDERR`, or custom IO objects) via the `output:` parameter in `Command.call`.
+
+### v2.1.4
+
+  - `Command#to_s` now returns the class name by default, improving debugging and introspection.
+
 ## See Also
 
   - [Teapot](https://github.com/ioquatix/teapot/blob/master/lib/teapot/command.rb) is a build system and uses multiple top-level commands.
@@ -34,6 +60,22 @@ We welcome contributions to this project.
 4.  Push to the branch (`git push origin my-new-feature`).
 5.  Create new Pull Request.
 
+### Running Tests
+
+To run the test suite:
+
+``` shell
+bundle exec sus
+```
+
+### Making Releases
+
+To make a new release:
+
+``` shell
+bundle exec bake gem:release:patch # or minor or major
+```
+
 ### Developer Certificate of Origin
 
 In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.
@@ -42,7 +84,7 @@ In order to protect users of this project, we require all contributors to comply
 
 This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.
 
-### Future Work
+## Future Work
 
 ### Multi-value Options
 

data/releases.md

@@ -0,0 +1,23 @@
+# Releases
+
+## v2.4.2
+
+  - Drop dependency on `mapping` gem.
+
+## v2.4.0
+
+  - Fix option parsing and validation: required options are now detected correctly and raise `Samovar::MissingValueError` when missing.
+  - Fix flag value parsing: flags that expect a value no longer consume a following flag as their value (e.g. `--config <path>` will not consume `--verbose`).
+  - Usage improvements: required options are marked as `(required)` in usage output.
+
+## v2.3.0
+
+  - Add support for `--[no]-thing` explicit boolean flags, allowing users to explicitly enable or disable boolean options.
+
+## v2.2.0
+
+  - Add support for explicit output: commands can now specify an output stream (e.g. `STDOUT`, `STDERR`, or custom IO objects) via the `output:` parameter in `Command.call`.
+
+## v2.1.4
+
+  - `Command#to_s` now returns the class name by default, improving debugging and introspection.

metadata

@@ -1,11 +1,12 @@
 --- !ruby/object:Gem::Specification
 name: samovar
 version: !ruby/object:Gem::Version
-  version: 2.4.0
+  version: 2.4.2
 platform: ruby
 authors:
 - Samuel Williams
 - Gabriel Mazetto
+- Gerhard Schlager
 bindir: bin
 cert_chain:
 - |
@@ -53,24 +54,12 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
-- !ruby/object:Gem::Dependency
-  name: mapping
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- context/getting-started.md
+- context/index.yaml
 - lib/samovar.rb
 - lib/samovar/command.rb
 - lib/samovar/error.rb
@@ -92,6 +81,7 @@ files:
 - lib/samovar/version.rb
 - license.md
 - readme.md
+- releases.md
 homepage: https://github.com/ioquatix/samovar
 licenses:
 - MIT
@@ -106,14 +96,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Samovar is a flexible option parser excellent support for sub-commands and
   help documentation.