trollop-subcommands 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b8f7ab781f9a6f38900f202dffce96102c844c54
+  data.tar.gz: 168656bcc8e533b4d54168ae6491529da80732b7
+SHA512:
+  metadata.gz: d0f69bbb24601c9041c87eb5afa0aa454d96b9a434291a46a9bcedfbb8bc7a0642e49c88b3e2ec716b37f0cdf992a2fbc0dffef1786e050ffb2a103797b0edc7
+  data.tar.gz: cd41090b636ab74e92c5a7d6dd74f7050e195d0e0a18e1e1cc65bf87b4d6674979a3e2b70c2a24912e18bb52bfd51d9a0278ae63b7bbccef93ebb5409ec2e09a

data/.gitignore

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

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.ruby-version

@@ -0,0 +1 @@
+2.2.2

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 jwliechty
+
+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/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Jason Liechty
+
+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,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/trollop/subcommands.rb

@@ -0,0 +1,125 @@
+require 'trollop'
+require 'trollop/subcommands/version'
+
+module Trollop
+  module Subcommands
+
+    ## Register the options block for parsing the global options. If
+    ## not invoked, a default options block with a bare-bones usage
+    ## message will be used. No need to specify `stop_on` or
+    ## `stop_on_unknown` as that is done automatically at the time of
+    ## parsing.
+    def register_global(&trollop_block)
+      parser.register_global(&trollop_block)
+    end
+
+    ## Register the options block for a given subcommand. If the
+    ## subcommand does not need options, one should still be
+    ## provided specifying the banner. The banner displays when
+    ## the when the followng arguments are given:
+    ##   my_script my_subcommand -h
+    def register_subcommand(command, &trollop_block)
+      parser.register_subcommand(command, &trollop_block)
+    end
+
+    ## Where the magic happens. Once all the subcommands and optionally
+    ## the global options are registered, invoke this method for the
+    ## command line parsing to begin. The result of this method
+    ## invocation is a struct containing the `global_options` (hash),
+    ## `subcommand` (string), and `subcommand_options` (hash).
+    def parse!(args=ARGV)
+      parser.parse!(args)
+    end
+
+    ## @private This is simply a helper method for the other publicly
+    ## exposed methods.
+    def parser
+      @parser ||= Parser.new
+    end
+
+    ## @private Used for the specs as arguments are parsed multiple
+    ## times in one process. For scripts, parsing usually occurs once.
+    def clear
+      @parser = nil
+    end
+
+    class Parser
+      def initialize
+        @subcommand_parsers_lookup = {}
+      end
+
+      def register_global(&trollop_block)
+        @global_parser = create_parser(&trollop_block)
+      end
+
+      def register_subcommand(command, &trollop_block)
+        @subcommand_parsers_lookup[command.to_s] = trollop_block
+      end
+
+      def parse!(args=ARGV)
+        @global_parser ||= default_global_parser
+        @global_parser.stop_on(subcommands)
+        @global_parser.stop_on_unknown
+        Trollop::with_standard_exception_handling(@global_parser) do
+          global_options = @global_parser.parse(args)
+          cmd = parse_subcommand(args)
+          cmd_options = parse_subcommand_options(args, cmd)
+          Result.new(global_options, cmd, cmd_options)
+        end
+      end
+
+      private
+
+      def default_global_parser
+        script_name = File.basename($0)
+        commands = @subcommand_parsers_lookup.keys.map(&:to_s)
+        create_parser do
+          banner <<-END
+Usage
+  #{script_name} COMMAND [options]
+
+COMMANDS
+  #{commands.join("\n  ")}
+
+Additional help
+  #{script_name} COMMAND -h
+
+Options
+          END
+        end
+      end
+
+      def create_parser(&block)
+        ::Trollop::Parser.new(&block)
+      end
+
+      def subcommands
+        @subcommand_parsers_lookup.keys
+      end
+
+      def parse_subcommand(args)
+        cmd = args.shift
+        raise ::Trollop::CommandlineError.new('No subcommand provided') unless cmd
+        cmd
+      end
+
+      def parse_subcommand_options(args, cmd)
+        block = @subcommand_parsers_lookup[cmd]
+        raise ::Trollop::CommandlineError.new("Unknown subcommand '#{cmd}'") unless block
+        cmd_parser = ::Trollop::Parser.new(&block)
+        ::Trollop::with_standard_exception_handling(cmd_parser) do
+          begin
+          result = cmd_parser.parse(args)
+          rescue CommandlineError => e
+            raise CommandlineError.new("#{e.message} for command '#{cmd}'")
+          end
+          result
+        end
+      end
+
+      Result = Struct.new(:global_options, :subcommand, :subcommand_options)
+    end
+
+    module_function :register_global, :register_subcommand, :parse!, :parser, :clear
+  end
+end

data/lib/trollop/subcommands/version.rb

@@ -0,0 +1,5 @@
+module Trollop
+  module Subcommands
+    VERSION = '0.1.0'
+  end
+end

data/readme.md

@@ -0,0 +1,88 @@
+# Trollop::Subcommands
+
+This gem is an extension to [Trollop]. It provides a framework for commandline
+scripts that use the following subcommand pattern
+
+```bash
+my_script [global options] command [command options]
+```
+
+## Usage
+
+The framework abstracts setting up the Trollop parser to the sub command pattern
+displayed above. Just provide the Trollop options blocks for the global options
+and subcommands and you are good to go!
+
+```ruby
+#!/usr/bin/env ruby
+require 'trollop/subcommands'
+
+# do not specify in the Trollop block `stop_on` or `stop_on_unknown`
+# as the subcommand framework will do that for you
+Trollop::Subcommands::register_global do
+  banner <<-END
+Usage
+  my_script [global options] COMMAND [command options]
+
+COMMANDS
+  list               List stuff
+  create             Create stuff
+
+Additional help
+  my_script COMMAND -h
+
+Options
+  END
+  opt :some_global_option, 'Some global option', type: :string, short: :none
+end
+
+Trollop::Subcommands::register_subcommand('list') do
+  banner <<-END
+Usage
+  #{File.basename($0)} list [options]
+
+This is the list command...
+
+Options
+  END
+  opt :all, 'All the things', type: :boolean
+end
+
+Trollop::Subcommands::register_subcommand('create') do
+  banner <<-END
+Usage
+  #{File.basename($0)} create [options]
+
+This is the create command...
+
+Options
+  END
+  opt :partial, 'blah blah', type: :boolean
+  opt :name,    'blah blah', type: :string
+end
+
+result = Trollop::Subcommands::parse!
+
+
+puts "Command was #{result.subcommand}"
+puts "Global options were #{result.global_options}"
+puts "Subcommand options were #{result.subcommand_options}"
+```
+
+The here documents for the banners can distract the code a bit. It can help to
+abstract them to methods.
+
+See the scenarios covered by the [spec].
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/jwliechty/trollop-subcommands.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License]
+
+[MIT License]: http://opensource.org/licenses/MIT
+[spec]:        spec/trollop/subcommands_spec.rb
+[Trollop]:     http://trollop.rubyforge.org/

data/trollop-subcommands.gemspec

@@ -0,0 +1,34 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'trollop/subcommands/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'trollop-subcommands'
+  spec.version       = Trollop::Subcommands::VERSION
+  spec.authors       = ['Jason Liechty']
+  spec.email         = ['jason.liechty@indigobio.com']
+
+  spec.summary       = %q{Adds a subcommand framework to the Trollop command line parsing library.}
+  spec.description   = %q{Though Trollop has the ability to support subcommands, I find myself
+implementing the same logic repeatedly. The abstraction of this logic is
+now in trollop-subcommands. This provides a framework for parsing
+command line options for ruby scripts that have subcommands. The format
+is 'script_name [global_options] subcommand [subcommand_options]'. The
+framework supports all the typical scenarios around these type of
+command line scripts. All that need to be specified are the trollop
+configurations for the global options and each subcommand options. See
+the readme for more information.}
+  spec.homepage      = 'https://github.com/jwliechty/trollop-subcommands'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.10'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.3'
+
+  spec.add_dependency 'trollop', '~> 2.1'
+end

metadata

@@ -0,0 +1,120 @@
+--- !ruby/object:Gem::Specification
+name: trollop-subcommands
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jason Liechty
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-10-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !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.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+- !ruby/object:Gem::Dependency
+  name: trollop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+description: |-
+  Though Trollop has the ability to support subcommands, I find myself
+  implementing the same logic repeatedly. The abstraction of this logic is
+  now in trollop-subcommands. This provides a framework for parsing
+  command line options for ruby scripts that have subcommands. The format
+  is 'script_name [global_options] subcommand [subcommand_options]'. The
+  framework supports all the typical scenarios around these type of
+  command line scripts. All that need to be specified are the trollop
+  configurations for the global options and each subcommand options. See
+  the readme for more information.
+email:
+- jason.liechty@indigobio.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".ruby-version"
+- Gemfile
+- LICENSE
+- LICENSE.txt
+- Rakefile
+- lib/trollop/subcommands.rb
+- lib/trollop/subcommands/version.rb
+- readme.md
+- trollop-subcommands.gemspec
+homepage: https://github.com/jwliechty/trollop-subcommands
+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.4.5
+signing_key: 
+specification_version: 4
+summary: Adds a subcommand framework to the Trollop command line parsing library.
+test_files: []