samovar 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 245b832e19301eafe975c8bc751f3d8f7c5f5fab
-  data.tar.gz: 8db97750516f551f87c9d614958e53e191a0d665
+  metadata.gz: df07fe3139c96d3f34b9e4d1ae5416e1f311eb2f
+  data.tar.gz: e2ef640c6126fa551258c29bafca19bdeb92ff0c
 SHA512:
-  metadata.gz: 0a57f9f297cf8c2b77e7d49185991dc154bb7dc0968a0c220ea666d84306bb10a6fc07f8ece5593b3776deae3f356ed857475ac314dfc1fa5b5aea616e7c64ee
-  data.tar.gz: a76705582cda894101104c34d73ab0c7dcec1b15557302c5ed753fce3746ccacc27de7151a29855351abcb0411406f841c84244fd53ad322320e532e6f446a31
+  metadata.gz: fbb6dea46c1245ae3e471f67ae62b75d5ce20937dba2c06fd82671e6ebad78f8fbe136816bbc7afc902f18d9aedbb98a9547a13792e167d5e791b6bfd36c12e9
+  data.tar.gz: 4ff9e33ab4b1cdc1969c547e8ba56733e9b406876409568d1ced9ee8b54d70ade58e456e66064f6055a8f6b0b818157308924de9060d83b1a807ed7d6d126f0e

data/README.md

@@ -2,7 +2,7 @@
 
 ![Teapot](teapot.png)
 
-Samovar is a modern framework for building command-line tools and applications. It provides a declarative class-based DSL for building command-line parsers that include automatic documentation generation `--help`. It helps you keep your functionality clean and isolated where possible.
+Samovar is a modern framework for building command-line tools and applications. It provides a declarative class-based DSL for building command-line parsers that include automatic documentation generation. It helps you keep your functionality clean and isolated where possible.
 
 [![Build Status](https://secure.travis-ci.org/ioquatix/samovar.svg)](http://travis-ci.org/ioquatix/samovar)
 [![Code Climate](https://codeclimate.com/github/ioquatix/samovar.svg)](https://codeclimate.com/github/ioquatix/samovar)
@@ -14,6 +14,12 @@ I've been using [Trollop](https://github.com/ManageIQ/trollop) and while it's no
 
 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.
+- [LSync](https://github.com/ioquatix/lsync/blob/master/lib/lsync/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:
@@ -30,11 +36,79 @@ Or install it yourself as:
 
 ## Usage
 
-The best example of a working Samovar command line is probably [Teapot](https://github.com/ioquatix/teapot/blob/master/lib/teapot/command.rb).
-
-[Utopia](https://github.com/ioquatix/utopia/blob/master/lib/utopia/command.rb) shows how to use multiple levels of nested commands.
-
-Please feel free to submit other examples and I will link to them here.
+### Basic Options
+
+	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."
+		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
+
+### Nested Commands
+
+	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
+
+	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
+
+	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']
 
 ## Contributing
 
@@ -46,7 +120,39 @@ Please feel free to submit other examples and I will link to them here.
 
 ### Future Work
 
-One area that I'd like to work on is line-wrapping. Right now, 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).
+#### 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.
+
+#### Global Options
+
+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
+
+One might reasonably expect this to parse but it isn't so easy to generalize this:
+
+	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).
+
+#### Shell Auto-completion
+
+Because of the structure of the Samovar command parser, it should be possible to generate a list of all possible tokens at each point. Therefore, semantically correct tab completion should be possible.
+
+As a secondary to this, it would be nice if `Samovar::One` and `Samovar::Many` could take a list of potential tokens so that auto-completion could give meaningful suggestions, and possibly improved validation.
+
+#### Short/Long Help
+
+It might be interesting to explore whether it's possible to have `-h` and `--help` do different things. This could include command specific help output, more detailed help output (similar to a man page), and other useful help related tasks.
 
 ## License
 

data/lib/samovar/options.rb

@@ -42,6 +42,8 @@ module Samovar
 		attr :description
 		attr :type
 		
+		attr :default
+		
 		attr :key
 		
 		def parse(input)
@@ -77,11 +79,17 @@ module Samovar
 		def initialize(title = "Options", key: :options)
 			@title = title
 			@ordered = []
+			
+			# We use this flag to option cache to improve parsing performance:
 			@keyed = {}
+			
 			@key = key
+			
+			@defaults = {}
 		end
 		
 		attr :key
+		attr :defaults
 		
 		def option(*args, **options)
 			self << Option.new(*args, **options)
@@ -96,10 +104,14 @@ module Samovar
 					@keyed[alternative] = option
 				end
 			end
+			
+			if default = option.default
+				@defaults[option.key] = option.default
+			end
 		end
 		
 		def parse(input)
-			values = Hash.new
+			values = @defaults.dup
 			
 			while option = @keyed[input.first]
 				if result = option.parse(input)

data/lib/samovar/version.rb

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

data/spec/samovar/command_spec.rb

@@ -15,7 +15,7 @@ module Command
 		self.description = "A decentralised package manager and build tool."
 		
 		options do
-			option '-c/--configuration <name>', "Specify a specific build configuration.", default: ENV['TEAPOT_CONFIGURATION']
+			option '-c/--configuration <name>', "Specify a specific build configuration.", default: 'TEAPOT_CONFIGURATION'
 			option '-i/--in/--root <path>', "Work in the given root directory."
 			option '--verbose | --quiet', "Verbosity of output for debugging.", key: :logging
 			option '-h/--help', "Print out help information."
@@ -28,6 +28,11 @@ module Command
 end
 
 describe Samovar::Command do
+	it "should use default value" do
+		top = Command::Top.parse([])
+		expect(top.options[:configuration]).to be == 'TEAPOT_CONFIGURATION'
+	end
+	
 	it "should parse a simple command" do
 		top = Command::Top.parse(["-c", "path", "bottom", "foobar", "A", "B", "--", "args", "args"])
 		

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: samovar
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Samuel Williams
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-04-24 00:00:00.000000000 Z
+date: 2016-06-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mapping