samovar 2.0.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58236fabb652bc2a55a95575f77222e1bc99ea0f18c545383c14fe4cf996db83
-  data.tar.gz: 843270eb1bd1e2f310c7653314cd3964d539e610627509c032d8926e94249806
+  metadata.gz: dee6078a981a3ddc9c9511c8a5411159bd94c9c422000f28babc461d44f40fb5
+  data.tar.gz: 7478ed72f2668fe912cde8701d4ecc2ab497ebeb36f76484160a495622b4842c
 SHA512:
-  metadata.gz: 574add44e120a76c74e54632e47df879f2555043b04520b8f1db0770b187b1ddef62fdc93801b2de7383ae3bc5148494f4207e284dc29fd0795d26be6390d947
-  data.tar.gz: 149ba4f3864badc05ccd337b8a1b5dab140e6696c372cffc6b9f448f7f7998c3880164c04d029df628989480fed7d81a8cac1981778c786871511e20002e53ba
+  metadata.gz: 3a24806b771f6d3e32f841462ec585ba22e0778d840dd51345b452914fac06f31882c007db8740daf1a01e0d3076119bcecd926bd7e6b57847289d006ede52b4
+  data.tar.gz: ea01b240a4b01caac62d950abd4785c2f77efa5fd9cc9cc1fa4fd6f06ea08303842481c27c8ac276142ee1dc3aeab71cd60b4a3c0420817628cdcff4a7c4961a

data/README.md

@@ -36,95 +36,141 @@ Or install it yourself as:
 
 ## Usage
 
-### Basic Options
+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'
 
-	require 'samovar'
+class List < Samovar::Command
+	self.description = "List the current directory"
 	
-	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
+	def call
+		system("ls -lah")
+	end
+end
+
+class Application < Samovar::Command
+	options do
+		option '--help', "Do you need help?"
 	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
+	nested :command, {
+		'list' => List
+	}, default: 'list'
 	
-	application = Application.new(['--things', 'x,y,z'])
-	application.options[:things] # ['x', 'y', 'z']
+	def call
+		if @options[:help]
+			self.print_usage
+		else
+			@command.call
+		end
+	end
+end
 
-### Nested Commands
+Application.call # Defaults to ARGV.
+```
 
-	require 'samovar'
-	
-	class Create < Samovar::Command
-		def invoke(parent)
-			puts "Creating"
+### 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
 	
-	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
+	def invoke(program_name: File.basename($0))
+		if @command
+			@command.invoke
+		else
+			print_usage(program_name)
 		end
 	end
+end
 
-	Application.new(['create']).invoke
+Application.new(['create']).invoke
+```
 
 ### ARGV Splits
 
-	require 'samovar'
+```ruby
+require 'samovar'
 
-	class Application < Samovar::Command
-		many :packages
-		split :argv
-	end
+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']
+application = Application.new(['foo', 'bar', 'baz', '--', 'apples', 'oranges', 'feijoas'])
+application.packages # ['foo', 'bar', 'baz']
+application.argv # ['apples', 'oranges', 'feijoas']
+```
 
 ### Parsing Tokens
 
-	require 'samovar'
+```ruby
+require 'samovar'
+
+class Application < Samovar::Command
+	self.description = "Mix together your favorite things."
 	
-	class Application < Samovar::Command
-		self.description = "Mix together your favorite things."
-		
-		one :fruit, "Name one fruit"
-		many :cakes, "Any cakes you like"
-	end
+	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']
+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:
 
-	application = Application['--root', path]
+```ruby
+application = Application['--root', path]
+```
 
 You can also duplicate an existing command instance with additions/changes:
 
-	concurrent_application = application['--threads', 12]
+```ruby
+concurrent_application = application['--threads', 12]
+```
 
 These forms can be useful when invoking one command from another, or in unit tests.
 
@@ -138,14 +184,6 @@ These forms can be useful when invoking one command from another, or in unit tes
 
 ### Future Work
 
-#### Line Wrapping
-
-Line wrapping is done by the terminal which is a bit ugly in some cases. There is a [half-implemented elegant solution](lib/samovar/output/line_wrapper.rb).
-
-#### Type Coercion
-
-It might make sense to enforce constraints at parse time.. or not. For example, if an option is given like `--count <int>` we should probably parse an integer?
-
 #### Multi-value Options
 
 Right now, options can take a single argument, e.g. `--count <int>`. Ideally, we support a specific sub-parser defined by the option, e.g. `--count <int...>` or `--tag <section> <tags...>`. These would map to specific parsers using `Samovar::One` and `Samovar::Many` internally.
@@ -154,11 +192,15 @@ Right now, options can take a single argument, e.g. `--count <int>`. Ideally, we
 
 Options can only be parsed at the place they are explicitly mentioned, e.g. a command with sub-commands won't parse an option added to the end of the command:
 
-	command list --help
+```ruby
+command list --help
+```
 
 One might reasonably expect this to parse but it isn't so easy to generalize this:
 
-	command list -- --help
+```ruby
+command list -- --help
+```
 
 In this case, do we show help? Some effort is required to disambiguate this. Initially, it makes sense to keep things as simple as possible. But, it might make sense for some options to be declared in a global scope, which are extracted before parsing begins. I'm not sure if this is really a good idea. It might just be better to give good error output in this case (you specified an option but it was in the wrong place).
 

data/lib/samovar/command.rb

@@ -31,8 +31,14 @@ require_relative 'error'
 
 module Samovar
 	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 = ARGV)
+		def self.parse(input)
 			self.new(input)
 		rescue Error => error
 			error.command.print_usage(output: $stderr) do |formatter|

data/lib/samovar/version.rb

@@ -19,5 +19,5 @@
 # THE SOFTWARE.
 
 module Samovar
-	VERSION = "2.0.1"
+	VERSION = "2.1.0"
 end

data/spec/samovar/command_spec.rb

@@ -46,6 +46,16 @@ module Samovar::CommandSpec
 	end
 
 	RSpec.describe Samovar::Command do
+		it "should invoke call" do
+			expect(Top).to receive(:new).and_wrap_original do |original_method, *args, &block|
+				original_method.call(*args, &block).tap do |instance|
+					expect(instance).to receive(:call)
+				end
+			end
+			
+			Top.call([])
+		end
+		
 		it "should use default value" do
 			top = Top[]
 			expect(top.options[:configuration]).to be == 'TEAPOT_CONFIGURATION'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: samovar
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.1.0
 platform: ruby
 authors:
 - Samuel Williams