samovar 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a92bf8cd31c971fc9652c6cc1a1620f8587d8d41
+  data.tar.gz: acce28bc01d1016b2c6be77f15ea50ef88b6d576
+SHA512:
+  metadata.gz: a127d1fea13405231ca8c3386f0c848fafa741aa328d38825187eeae1a0f728feb9374cceec196d17ebf569465cbc141e070d3b88033013d9527a0ca71f57df6
+  data.tar.gz: dadcdda3c02b1df2b46e2d656e4bf980a17a75bc16595410aeb195bf9131e6315395241a9f95f82d7c7b4105ef082267738ca1e52128adf9358bbdec52364041

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--warnings

data/.simplecov

@@ -0,0 +1,9 @@
+
+SimpleCov.start do
+	add_filter "/spec/"
+end
+
+if ENV['TRAVIS']
+	require 'coveralls'
+	Coveralls.wear!
+end

data/.travis.yml

@@ -0,0 +1,14 @@
+language: ruby
+sudo: false
+rvm:
+  - 2.1.8
+  - 2.2.4
+  - 2.3.0
+  - ruby-head
+  - rbx-2
+env: COVERAGE=true
+matrix:
+  fast_finish: true
+  allow_failures:
+    - rvm: ruby-head
+    - rvm: "rbx-2"

data/Gemfile

@@ -0,0 +1,9 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in samovar.gemspec
+gemspec
+
+group :test do
+	gem 'simplecov'
+	gem 'coveralls', require: false
+end

data/README.md

@@ -0,0 +1,69 @@
+# Samovar
+
+![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.
+
+[![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)
+[![Coverage Status](https://coveralls.io/repos/ioquatix/samovar/badge.svg)](https://coveralls.io/r/ioquatix/samovar)
+
+## Motivation
+
+I've been using [Trollop](https://github.com/ManageIQ/trollop) and while it's not bad, it's hard to use for sub-commands in a way that generates nice documentation. It also has pretty limited support for complex command lines (e.g. nested commands, splits, matching tokens, etc). Samovar is a high level bridge between the command line and your code: it generates decent documentation, maps nicely between the command line syntax and your functions, and supports sub-commands using classes which are easy to compose.
+
+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).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+	gem 'samovar'
+
+And then execute:
+
+	$ bundle
+
+Or install it yourself as:
+
+	$ gem install samovar
+
+## Usage
+
+The best example of a working Samovar command line is probably [Teapot](https://github.com/ioquatix/teapot/blob/master/lib/teapot/command.rb). Please feel free to submit other examples and I will link to them here.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+### 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).
+
+## License
+
+Released under the MIT license.
+
+Copyright, 2016, by [Samuel G. D. Williams](http://www.codeotaku.com/samuel-williams).
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,12 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec) do |task|
+	begin
+		require('simplecov/version')
+		task.rspec_opts = %w{--require simplecov} if ENV['COVERAGE']
+	rescue LoadError
+	end
+end
+
+task :default => :spec

data/flopp.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'samovar/version'
+
+Gem::Specification.new do |spec|
+	spec.name          = "samovar"
+	spec.version       = Samovar::VERSION
+	spec.authors       = ["Samuel Williams"]
+	spec.email         = ["samuel.williams@oriontransfer.co.nz"]
+
+	spec.summary       = %q{Samovar is a flexible option parser excellent support for sub-commands and help documentation.}
+	spec.homepage      = "https://github.com/ioquatix/samovar"
+	spec.license       = "MIT"
+
+	spec.files         = `git ls-files`.split($/)
+	spec.executables   = spec.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+	spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+	spec.require_paths = ["lib"]
+	
+	spec.add_dependency "mapping", "~> 1.0.0"
+	spec.add_dependency "rainbow", "~> 2.0"
+
+	spec.add_development_dependency "bundler", "~> 1.11"
+	spec.add_development_dependency "rake", "~> 10.0"
+	spec.add_development_dependency "rspec", "~> 3.0"
+end

data/lib/samovar.rb

@@ -0,0 +1,3 @@
+
+require_relative 'samovar/version'
+require_relative 'samovar/command'

data/lib/samovar/command.rb

@@ -0,0 +1,117 @@
+# Copyright, 2016, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require_relative 'table'
+require_relative 'options'
+require_relative 'nested'
+require_relative 'one'
+require_relative 'many'
+require_relative 'split'
+
+require_relative 'output'
+
+module Samovar
+	class IncompleteParse < StandardError
+	end
+	
+	class Command
+		def self.parse(input)
+			command = self.new(input)
+			
+			raise IncompleteParse.new("Could not parse #{input}") unless input.empty?
+			
+			return command
+		end
+		
+		def initialize(input)
+			self.class.table.parse(input) do |key, value|
+				self.send("#{key}=", value)
+			end
+		end
+		
+		def [] key
+			@attributes[key]
+		end
+		
+		class << self
+			attr_accessor :description
+		end
+		
+		def self.table
+			@table ||= Table.new
+		end
+		
+		def self.append(row)
+			attr_accessor(row.key) if row.respond_to?(:key)
+			
+			self.table << row
+		end
+		
+		def self.options(*args, **options, &block)
+			append Options.parse(*args, **options, &block)
+		end
+		
+		def self.nested(*args, **options)
+			append Nested.new(*args, **options)
+		end
+		
+		def self.one(*args, **options)
+			append One.new(*args, **options)
+		end
+		
+		def self.many(*args, **options)
+			append Many.new(*args, **options)
+		end
+		
+		def self.split(*args, **options)
+			append Split.new(*args, **options)
+		end
+		
+		def self.usage(rows, name)
+			rows.nested(name, self) do |rows|
+				return unless @table
+				
+				@table.rows.each do |row|
+					if row.respond_to?(:usage)
+						row.usage(rows)
+					else
+						rows << row
+					end
+				end
+			end
+		end
+		
+		def self.command_line(name)
+			if @table
+				"#{name} #{@table.usage}"
+			else
+				name
+			end
+		end
+		
+		def print_usage(*args, output: $stderr, formatter: Output::DetailedFormatter)
+			rows = Output::Rows.new
+			
+			self.class.usage(rows, *args)
+			
+			formatter.print(rows, output)
+		end
+	end
+end

data/lib/samovar/flags.rb

@@ -0,0 +1,102 @@
+# Copyright, 2016, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+module Samovar
+	class Flags
+		def initialize(text)
+			@text = text
+			
+			@ordered = text.split(/\s+\|\s+/).map{|part| Flag.new(part)}
+		end
+		
+		def each(&block)
+			@ordered.each(&block)
+		end
+		
+		def first
+			@ordered.first
+		end
+		
+		# Whether or not this flag should have a true/false value if not specified otherwise.
+		def boolean?
+			@ordered.count == 1 and @ordered.first.value.nil?
+		end
+		
+		def count
+			return @ordered.count
+		end
+		
+		def to_s
+			'[' + @ordered.join(' | ') + ']'
+		end
+		
+		def parse(input)
+			@ordered.each do |flag|
+				if result = flag.parse(input)
+					return result
+				end
+			end
+			
+			return nil
+		end
+	end
+	
+	class Flag
+		def initialize(text)
+			@text = text
+			
+			if text =~ /(.*?)\s(\<.*?\>)/
+				@prefix = $1
+				@value = $2
+			else
+				@prefix = @text
+			end
+			
+			*@alternatives, @prefix = @prefix.split('/')
+		end
+		
+		attr :text
+		attr :prefix
+		attr :alternatives
+		attr :value
+		
+		def to_s
+			@text
+		end
+		
+		def prefix?(token)
+			@prefix == token or @alternatives.include?(token)
+		end
+		
+		def key
+			@key ||= @prefix.sub(/^-*/, '').gsub('-', '_').to_sym
+		end
+		
+		def parse(input)
+			if prefix?(input.first)
+				if @value
+					input.shift(2).last
+				else
+					input.shift; key
+				end
+			end
+		end
+	end
+end

data/lib/samovar/many.rb

@@ -0,0 +1,47 @@
+# Copyright, 2016, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+module Samovar
+	class Many
+		def initialize(key, description, stop: /^-/)
+			@key = key
+			@description = description
+			@stop = stop
+		end
+		
+		attr :key
+		
+		def to_s
+			"<#{key}...>"
+		end
+		
+		def to_a
+			[to_s, @description]
+		end
+		
+		def parse(input)
+			if @stop and stop_index = input.index{|item| @stop === item}
+				input.shift(stop_index)
+			else
+				input.shift(input.size)
+			end
+		end
+	end
+end

data/lib/samovar/nested.rb

@@ -0,0 +1,56 @@
+# Copyright, 2016, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+module Samovar
+	class Nested
+		def initialize(name, commands, key: :command)
+			@name = name
+			@commands = commands
+			@key = key
+		end
+		
+		attr :key
+		
+		def to_s
+			@name
+		end
+		
+		def to_a
+			[@name, "One of #{@commands.keys.join(', ')}."]
+		end
+		
+		def parse(input)
+			if command = @commands[input.first]
+				input.shift
+				
+				# puts "Instantiating #{command} with #{input}"
+				command.new(input)
+			end
+		end
+		
+		def usage(rows)
+			rows << self
+			
+			@commands.each do |key, klass|
+				klass.usage(rows, key)
+			end
+		end
+	end
+end

data/lib/samovar/one.rb

@@ -0,0 +1,45 @@
+# Copyright, 2016, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+module Samovar
+	class One
+		def initialize(key, description, pattern: //)
+			@key = key
+			@description = description
+			@pattern = pattern
+		end
+		
+		attr :key
+		
+		def to_s
+			"<#{@key}>"
+		end
+		
+		def to_a
+			[to_s, @description]
+		end
+		
+		def parse(input)
+			if input.first =~ @pattern
+				input.shift
+			end
+		end
+	end
+end

data/lib/samovar/options.rb

@@ -0,0 +1,123 @@
+# Copyright, 2016, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require_relative 'flags'
+
+module Samovar
+	class Option
+		def initialize(flags, description, key: nil, default: nil, value: nil)
+			@flags = Flags.new(flags)
+			@description = description
+			
+			if key
+				@key = key
+			else
+				@key = @flags.first.key
+			end
+			
+			@default = default
+			
+			@value = value
+			@value ||= true if @flags.boolean?
+		end
+		
+		attr :flags
+		attr :description
+		attr :type
+		
+		attr :key
+		
+		def parse(input)
+			if result = @flags.parse(input)
+				@value.nil? ? result : @value
+			else
+				@default
+			end
+		end
+		
+		def to_s
+			@flags
+		end
+		
+		def to_a
+			unless @default.nil?
+				[@flags, @description, "Default: #{@default}"]
+			else
+				[@flags, @description]
+			end
+		end
+	end
+	
+	class Options
+		def self.parse(*args, **options, &block)
+			options = self.new(*args, **options)
+			
+			options.instance_eval(&block) if block_given?
+			
+			return options
+		end
+		
+		def initialize(title = "Options", key: :options)
+			@title = title
+			@ordered = []
+			@keyed = {}
+			@key = key
+		end
+		
+		attr :key
+		
+		def option(*args, **options)
+			self << Option.new(*args, **options)
+		end
+		
+		def << option
+			@ordered << option
+			option.flags.each do |flag|
+				@keyed[flag.prefix] = option
+				
+				flag.alternatives.each do |alternative|
+					@keyed[alternative] = option
+				end
+			end
+		end
+		
+		def parse(input)
+			values = Hash.new
+			
+			while option = @keyed[input.first]
+				if result = option.parse(input)
+					values[option.key] = result
+				end
+			end
+			
+			return values
+		end
+		
+		def to_s
+			@ordered.collect(&:to_s).join(' ')
+		end
+		
+		def usage(rows)
+			@ordered.each do |option|
+				rows << option
+			end
+		end
+	end
+end

data/lib/samovar/output.rb

@@ -0,0 +1,166 @@
+# Copyright, 2016, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require 'mapping/model'
+require 'rainbow'
+
+module Samovar
+	module Output
+		class Header
+			def initialize(name, object)
+				@name = name
+				@object = object
+			end
+			
+			attr :name
+			attr :object
+			
+			def align(columns)
+				@object.command_line(@name)
+			end
+		end
+		
+		class Row < Array
+			def initialize(object)
+				@object = object
+				super object.to_a.collect(&:to_s)
+			end
+			
+			attr :object
+			
+			def align(columns)
+				self.collect.with_index do |value, index|
+					value.ljust(columns.widths[index])
+				end.join('  ')
+			end
+		end
+		
+		class Columns
+			def initialize(rows)
+				@rows = rows
+				@widths = calculate_widths(rows)
+			end
+			
+			attr :widths
+			
+			def calculate_widths(rows)
+				widths = []
+				
+				rows.each do |row|
+					row.each.with_index do |column, index|
+						(widths[index] ||= []) << column.size
+					end
+				end
+				
+				return widths.collect(&:max)
+			end
+		end
+		
+		class Rows
+			include Enumerable
+			
+			def initialize(level = 0)
+				@level = level
+				@rows = []
+			end
+			
+			attr :level
+			
+			def empty?
+				@rows.empty?
+			end
+			
+			def first
+				@rows.first
+			end
+			
+			def last
+				@rows.last
+			end
+			
+			def indentation
+				@indentation ||= "\t" * @level
+			end
+			
+			def each(ignore_nested: false, &block)
+				return to_enum(:each, ignore_nested: ignore_nested) unless block_given?
+				
+				@rows.each do |row|
+					if row.is_a?(self.class)
+						row.each(&block) unless ignore_nested
+					else
+						yield row, self
+					end
+				end
+			end
+			
+			def << object
+				@rows << Row.new(object)
+				
+				return self
+			end
+			
+			def columns
+				@columns ||= Columns.new(@rows.select{|row| row.is_a? Array})
+			end
+			
+			def nested(*args)
+				@rows << Header.new(*args)
+				
+				nested_rows = self.class.new(@level + 1)
+				
+				yield nested_rows
+				
+				@rows << nested_rows
+			end
+		end
+		
+		class DetailedFormatter < Mapping::Model
+			def self.print(rows, output)
+				self.new(rows, output).print
+			end
+			
+			def initialize(rows, output)
+				@rows = rows
+				@output = output
+				@width = 80
+			end
+			
+			map(Header) do |header, rows|
+				@output.puts unless header == @rows.first
+				@output.puts "#{rows.indentation}#{Rainbow(header.object.command_line(header.name)).bright}"
+				@output.puts "#{rows.indentation}\t#{Rainbow(header.object.description).blue}"
+				@output.puts
+			end
+			
+			map(Row) do |row, rows|
+				@output.puts "#{rows.indentation}#{row.align(rows.columns)}"
+			end
+			
+			map(Rows) do |items|
+				items.collect{|row, rows| map(row, rows)}
+			end
+			
+			def print
+				map(@rows)
+			end
+		end
+	end
+end

data/lib/samovar/output/line_wrapper.rb

@@ -0,0 +1,87 @@
+# Copyright, 2016, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+module Samovar
+	module Output
+		# This is an incomplete implementation of an automatic line wrapping output buffer which handles any kind of output, provided it has special wrapping markers.
+		class LineWrapping
+			MARKER = "\e[0;0m".freeze
+			
+			def initialize(output, wrapping_width = 80, minimum_width = 20)
+				@output = output
+				@wrapping_width = wrapping_width
+				@minimum_width = minimum_width
+			end
+			
+			ESCAPE_SEQUENCE = /(.*?)(\e\[.*?m|$)/
+			
+			def printable_width(text)
+				text.size
+			end
+			
+			def wrap(line)
+				wrapping_offset = nil
+				offset = 0
+				buffer = String.new
+				lines = []
+				prefix = nil
+				
+				line.scan(ESCAPE_SEQUENCE) do |text, escape_sequence|
+					width = printable_width(text)
+					next_offset = offset + printable_width
+					
+					if next_offset > @wrapping_width
+						if wrapping_offset
+							text_wrap_offset = @wrapping_width - offset
+							
+							# This text flows past the end of the line and we have a valid wrapping offset. We need to wrap this text.
+							if best_split_index = text.rindex(/\s/, text_wrap_offset) and best_split_index >= @minimum_width
+								# We have enough space to wrap.
+								buffer << text[0...best_split_index]
+								lines << buffer
+								buffer = String.new()
+							else
+								# In this case we can't really wrap on the current line. We fall back to letting the terminal wrap.
+								return line
+							end
+						else
+							# We don't have a specific wrapping offset, and the text flows longer than the wrapping width. We can't do anything - let the terminal wrap.
+							return line
+						end
+					else
+						buffer << text << escape_sequence
+					end
+					
+					offset = next_offset
+					
+					if wrapping_offset.nil? and offset < @wrapping_width and escape_sequence == MARKER
+						wrapping_offset = offset
+					end
+				end
+			end
+			
+			def puts(*lines)
+				lines = lines.flat_map{|line| wrap(line)}
+				
+				@output.puts(*lines)
+			end
+		end
+	end
+end

data/lib/samovar/split.rb

@@ -0,0 +1,45 @@
+# Copyright, 2016, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+module Samovar
+	class Split
+		def initialize(key, description, marker: '--')
+			@key = key
+			@description = description
+			@marker = marker
+		end
+		
+		attr :key
+		
+		def to_s
+			"#{@marker} <#{@key}...>"
+		end
+		
+		def to_a
+			[to_s, @description]
+		end
+		
+		def parse(input)
+			if offset = input.index(@marker)
+				input.pop(input.size - offset).tap(&:shift)
+			end
+		end
+	end
+end

data/lib/samovar/table.rb

@@ -0,0 +1,56 @@
+# Copyright, 2016, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+module Samovar
+	class Table
+		def initialize
+			@rows = []
+			@parser = []
+		end
+		
+		attr :rows
+		
+		def << row
+			@rows << row
+			
+			if row.respond_to?(:parse)
+				@parser << row
+			end
+		end
+		
+		def usage
+			items = Array.new
+			
+			@rows.each do |row|
+				items << row.to_s
+			end
+			
+			items.join(' ')
+		end
+		
+		def parse(input)
+			@parser.each do |row|
+				if result = row.parse(input)
+					yield row.key, result, row
+				end
+			end
+		end
+	end
+end

data/lib/samovar/version.rb

@@ -0,0 +1,3 @@
+module Samovar
+  VERSION = "1.0.0"
+end

data/spec/samovar_spec.rb

@@ -0,0 +1,48 @@
+
+require 'samovar'
+require 'stringio'
+
+module Command
+	class Bottom < Samovar::Command
+		self.description = "Create a new teapot package using the specified repository."
+		
+		one :project_name, "The name of the new project in title-case, e.g. 'My Project'."
+		many :packages, "Any additional packages you'd like to include in the project."
+		split :argv, "Additional arguments to be passed to the sub-process."
+	end
+
+	class Top < Samovar::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 '-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."
+			option '-v/--version', "Print out the application version."
+		end
+		
+		nested '<command>',
+			'bottom' => Bottom
+	end
+end
+
+describe Samovar do
+	it "should parse a simple command" do
+		top = Command::Top.parse(["-c", "path", "bottom", "foobar", "A", "B", "--", "args", "args"])
+		
+		expect(top.options[:configuration]).to be == 'path'
+		expect(top.command.class).to be == Command::Bottom
+		expect(top.command.project_name).to be == 'foobar'
+		expect(top.command.packages).to be == ['A', 'B']
+		expect(top.command.argv).to be == ["args", "args"]
+	end
+	
+	it "should generate documentation" do
+		top = Command::Top.new([])
+		buffer = StringIO.new
+		top.print_usage('top', output: buffer)
+		
+		expect(buffer.string).to be_include(Command::Top.description)
+	end
+end

metadata

@@ -0,0 +1,138 @@
+--- !ruby/object:Gem::Specification
+name: samovar
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Samuel Williams
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-04-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mapping
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+- !ruby/object:Gem::Dependency
+  name: rainbow
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: 
+email:
+- samuel.williams@oriontransfer.co.nz
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".simplecov"
+- ".travis.yml"
+- Gemfile
+- README.md
+- Rakefile
+- flopp.gemspec
+- lib/samovar.rb
+- lib/samovar/command.rb
+- lib/samovar/flags.rb
+- lib/samovar/many.rb
+- lib/samovar/nested.rb
+- lib/samovar/one.rb
+- lib/samovar/options.rb
+- lib/samovar/output.rb
+- lib/samovar/output/line_wrapper.rb
+- lib/samovar/split.rb
+- lib/samovar/table.rb
+- lib/samovar/version.rb
+- spec/samovar_spec.rb
+- teapot.png
+homepage: https://github.com/ioquatix/samovar
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Samovar is a flexible option parser excellent support for sub-commands and
+  help documentation.
+test_files:
+- spec/samovar_spec.rb