samovar 2.3.0 → 2.4.0

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.0"
 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

data/readme.md

@@ -12,165 +12,17 @@ I've been using [Optimist](https://github.com/ManageIQ/optimist) and while it's
 
 One of the other issues I had with existing frameworks is testability. Most frameworks expect to have some pretty heavy logic directly in the binary executable, or at least don't structure your code in a way which makes testing easy. Samovar structures your command processing logic into classes which can be easily tested in isolation, which means that you can mock up and [spec your command-line executables easily](https://github.com/ioquatix/teapot/blob/master/spec/teapot/command_spec.rb).
 
-## Examples
-
-  - [Teapot](https://github.com/ioquatix/teapot/blob/master/lib/teapot/command.rb) is a build system and uses multiple top-level commands.
-  - [Utopia](https://github.com/ioquatix/utopia/blob/master/lib/utopia/command.rb) is a web application platform and uses nested commands.
-  - [Synco](https://github.com/ioquatix/synco/blob/master/lib/synco/command.rb) is a backup tool and sends commands across the network and has lots of options with default values.
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-    gem 'samovar'
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install samovar
-
 ## Usage
 
-Generally speaking, you should create `Command` classes that represent specific functions in your program. The top level command might look something like this:
+Please see the [project documentation](https://ioquatix.github.io/samovar/) for more details.
 
-``` 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
-
-``` 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
-
-``` 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
-```
+  - [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.
 
-### ARGV Splits
+## See Also
 
-``` 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
-
-``` 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.
+  - [Teapot](https://github.com/ioquatix/teapot/blob/master/lib/teapot/command.rb) is a build system and uses multiple top-level commands.
+  - [Synco](https://github.com/ioquatix/synco/blob/master/lib/synco/command.rb) is a backup tool and sends commands across the network and has lots of options with default values.
+  - [Bake](https://github.com/ioquatix/bake) is an alternative task runner that makes it easy to expose Ruby methods as command-line tasks.
 
 ## Contributing
 
@@ -184,13 +36,13 @@ We welcome contributions to this project.
 
 ### Developer Certificate of Origin
 
-This project uses the [Developer Certificate of Origin](https://developercertificate.org/). All contributors to this project must agree to this document to have their contributions accepted.
+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.
 
-### Contributor Covenant
+### Community Guidelines
 
-This project is governed by the [Contributor Covenant](https://www.contributor-covenant.org/). All contributors and participants agree to abide by its terms.
+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
 

metadata

@@ -1,12 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: samovar
 version: !ruby/object:Gem::Version
-  version: 2.3.0
+  version: 2.4.0
 platform: ruby
 authors:
 - Samuel Williams
 - Gabriel Mazetto
-autorequire:
 bindir: bin
 cert_chain:
 - |
@@ -38,7 +37,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2024-03-28 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: console
@@ -68,8 +67,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
-description:
-email:
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -99,8 +96,9 @@ homepage: https://github.com/ioquatix/samovar
 licenses:
 - MIT
 metadata:
+  documentation_uri: https://ioquatix.github.io/samovar/
   funding_uri: https://github.com/sponsors/ioquatix/
-post_install_message:
+  source_code_uri: https://github.com/ioquatix/samovar.git
 rdoc_options: []
 require_paths:
 - lib
@@ -108,15 +106,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Samovar is a flexible option parser excellent support for sub-commands and
   help documentation.