samovar 2.3.0 → 2.4.1

data/readme.md

@@ -12,165 +12,41 @@ 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:
-
-``` 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
+Please see the [project documentation](https://ioquatix.github.io/samovar/) for more details.
 
-``` 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']
-```
+  - [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.
 
-### Nested Commands
+## Releases
 
-``` 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
-```
+Please see the [project releases](https://ioquatix.github.io/samovar/releases/index) for all releases.
 
-### ARGV Splits
+### v2.4.1
 
-``` ruby
-require 'samovar'
+### v2.4.0
 
-class Application < Samovar::Command
-	many :packages
-	split :argv
-end
+  - 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.
 
-application = Application.new(['foo', 'bar', 'baz', '--', 'apples', 'oranges', 'feijoas'])
-application.packages # ['foo', 'bar', 'baz']
-application.argv # ['apples', 'oranges', 'feijoas']
-```
+### v2.3.0
 
-### Parsing Tokens
+  - Add support for `--[no]-thing` explicit boolean flags, allowing users to explicitly enable or disable boolean options.
 
-``` 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']
-```
+### v2.2.0
 
-### Explicit Commands
+  - 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`.
 
-Given a custom `Samovar::Command` subclass, you can instantiate it with options:
+### v2.1.4
 
-``` ruby
-application = Application['--root', path]
-```
+  - `Command#to_s` now returns the class name by default, improving debugging and introspection.
 
-You can also duplicate an existing command instance with additions/changes:
+## See Also
 
-``` 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 +60,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
 

data/releases.md

@@ -0,0 +1,21 @@
+# Releases
+
+## v2.4.1
+
+## 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,12 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: samovar
 version: !ruby/object:Gem::Version
-  version: 2.3.0
+  version: 2.4.1
 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,12 +67,12 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
-description:
-email:
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- context/getting-started.md
+- context/index.yaml
 - lib/samovar.rb
 - lib/samovar/command.rb
 - lib/samovar/error.rb
@@ -95,12 +94,14 @@ files:
 - lib/samovar/version.rb
 - license.md
 - readme.md
+- releases.md
 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 +109,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.