samovar 2.4.0 → 2.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85e0df9ca2ed86284ab62c49ef724f93818ecb8571a33cccca98759f0a6b2612
-  data.tar.gz: 833c98f6619c7fb73243f6bbbbbb84e25a8d100c03af55392bd97f20a4246803
+  metadata.gz: e1051db069257cf9d25e3599a5ddb5c5547a921cb90d04552a777d3af5c335b2
+  data.tar.gz: 632d0819eb51db7f9640feb8491e543706721a4313243527bb5380da576a578b
 SHA512:
-  metadata.gz: 0aff1d4bc6f8c2154dcd7e216a8f082fc50b44239321a122b139edff54e0749ab7109a45ab87e2615677e181426717b4912d81118f87f01cd4bf7032653d2041
-  data.tar.gz: d3c94b2986da89eba71d18d06df18dd0541775f2f1c2ba2c327e8407a38e05757e073b5f97c137c8c0241ab29811fd9e0a3fed3c2613034ca7db15ef0e5aff12
+  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/version.rb

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

data/readme.md

@@ -18,6 +18,30 @@ 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.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.
+
 ## See Also
 
   - [Teapot](https://github.com/ioquatix/teapot/blob/master/lib/teapot/command.rb) is a build system and uses multiple top-level commands.

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.

data.tar.gz.sig

@@ -1,4 +1,4 @@
-~�I|!5<�P�*��oA��[L��ʏHT7!5���'��8��H��vBP�����P��
-�mf`T�Q����Dzbz����8
-@m0���%���
-P�2����:!j�Ɨq�k,FLmQ�ER�GEY��T��?,x+����[OG��{<ՀD;K��i�_��8g�t5൮��Ս�`�L��\!�]{��*٦d!/�]B3ί�L�sc���������nN�֢�a�ݙ�1��WZ�.�/S�@����k�ͫ6B�AA�7��İ�OcT�`y��AN����"US�a�#�V�P!R)�RU;)����" �RxA�hP��x�7�J�[_���%
+�@/8
+p���c\ld�?��8�Bdÿ��ɹu�t&+�s�
+���HBT��p���}�•�f;����4�Z)#�xV��af D�SH���k'�c˭z���o���m���8��'ӓ�g��[s���2ԧMB�5U�Ho�Bʉ���S�*ր����,��v�@E�^�u1<[�^&��o
+p�j}�x2mV/2����7��<�2���PE�s�ϙE�H8j��u����֝��_���)�&b���rD���@O�� g����G<��2�S�ehMv�ލ����v/+ƀ�w��,�

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: samovar
 version: !ruby/object:Gem::Version
-  version: 2.4.0
+  version: 2.4.1
 platform: ruby
 authors:
 - Samuel Williams
@@ -71,6 +71,8 @@ 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 +94,7 @@ files:
 - lib/samovar/version.rb
 - license.md
 - readme.md
+- releases.md
 homepage: https://github.com/ioquatix/samovar
 licenses:
 - MIT