Merge pull request #51 from 3scale/plugin-framework-second-try

Plugin framework

.gitignore

@@ -5,6 +5,7 @@
 /coverage/
 /doc/
 /pkg/
+/vendor/
 /spec/reports/
 /tmp/
 .DS_Store

.travis.yml

@@ -10,5 +10,5 @@ rvm:
 script:
 - rake install
 - 3scale help
-- 3scale copy help
-- 3scale import help
+- 3scale help copy
+- 3scale help import

3scale_toolbox.gemspec

@@ -7,8 +7,8 @@ Gem::Specification.new do |spec|
   spec.name          = '3scale_toolbox'
   spec.version       = ThreeScaleToolbox::VERSION
   spec.licenses      = ['MIT']
-  spec.authors       = ['Michal Cichra']
-  spec.email         = ['[email protected]']
+  spec.authors       = ['Michal Cichra', 'Eguzki Astiz Lezaun']
+  spec.email         = ['[email protected]', '[email protected]']
 
   spec.summary       = %q{3scale CLI Toolbox.}
   spec.description   = %q{3scale CLI tools to manage your API from the terminal.}
@@ -23,5 +23,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.required_ruby_version = '>= 2.1'
 
-  spec.add_dependency '3scale-api', '~> 0.1.2'
+  spec.add_dependency '3scale-api', '~> 0.1'
+  spec.add_dependency 'cri', '~> 2.10'
 end

README.md

@@ -37,6 +37,13 @@ After checking out the repo, run `bin/setup` to install dependencies. You can al
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+## Plugins
+
+As of 3scale Toolbox 0.5.0, 3scale Toolbox will load plugins installed in gems or $LOAD_PATH. Plugins are discovered via Gem::find_files then loaded.
+Install, uninstall and update plugins using tools like [RubyGems](https://guides.rubygems.org/rubygems-basics/) and/or [Bundler](https://bundler.io/).
+
+[Make your own plugin](docs/plugins.md)
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/3scale/3scale_toolbox.

docs/plugins.md

@@ -0,0 +1,133 @@
+# Developing 3scale Toolbox CLI plugins
+
+3scale Toolbox CLI is based on [cri](https://github.com/ddfreyne/cri) library for building command line tools.
+Plugin system also uses [cri](https://github.com/ddfreyne/cri) to leverage easy to develop, flexible and extensible plugin system.
+
+3scale Toolbox will load plugins installed in gems or $LOAD_PATH. Plugins are discovered via *Gem::find_files*, then loaded.
+Plugins must be named ‘3scale_toolbox_plugin’ (.rb, .so, etc) and placed at the root of your gem’s #require_path.
+
+Plugins may add commands to *3scale* CLI or may add *subcommands* to any existing command.
+Subcommands may be added to main commands or other subcommands as children.
+
+Nothing better than few examples to illustrate .
+
+Let's create a plugin to add a main `simple hello world` command.
+
+```
+$ cat lib/3scale_toolbox_plugin.rb
+require '3scale_toolbox/cli'
+
+module FooCommand
+  extend ThreeScaleToolbox::Command
+
+  def self.command
+    Cri::Command.define do
+      name        'foo'
+      usage       'foo [options]'
+      summary     '3scale foo'
+      description '3scale foo command'
+      flag :h, :help, 'show help for this command' do |_, cmd|
+        puts cmd.help
+        exit 0
+      end
+      run do |opts, args, _|
+        puts "foo done"
+      end
+    end
+  end
+end
+ThreeScaleToolbox::CLI.add_command(FooCommand)
+
+$ RUBYOPT=-Ilib 3scale foo
+Hello World
+```
+Few things worth to highlight.
+- Your module must be extended by *ThreeScaleToolbox::Command* module. It allows your command to be added to CLI command tree.
+- Must implement `command` module function and return instance of `Cri::Command` from [cri](https://github.com/ddfreyne/cri)
+- Add your command to `3scale` CLI command tree by calling `ThreeScaleToolbox::CLI.add_command`
+
+Your plugin help is also available using builtin *help* command
+
+```
+$ RUBYOPT=-Ilib 3scale help foo
+NAME
+    foo - foo command
+
+USAGE
+    3scale foo [options]
+
+DESCRIPTION
+    This command does a lot of stuff.
+
+OPTIONS
+    -h --help         show help for this command
+
+OPTIONS FOR 3SCALE
+    -v --version      Prints the version of this command
+```
+
+Let's create a plugin to add a `simple hello world` subcommand for the builtin *copy* command.
+
+```
+$ cat lib/3scale_toolbox_plugin.rb
+require '3scale_toolbox/base_command'
+require '3scale_toolbox/commands/copy_command'
+
+module FooCommand
+  extend ThreeScaleToolbox::Command
+
+  def self.command
+    Cri::Command.define do
+      name        'foo'
+      usage       'foo [options]'
+      summary     '3scale copy foo'
+      description '3scale copy foo subcommand'
+      flag :h, :help, 'show help for this command' do |_, cmd|
+        puts cmd.help
+        exit 0
+      end
+      run do |opts, args, _|
+        puts "foo done"
+      end
+    end
+  end
+end
+
+ThreeScaleToolbox::Commands::CopyCommand.add_subcommand(FooCommand)
+
+$ RUBYOPT=-Ilib 3scale copy foo
+foo done
+```
+
+Few things worth to highlight.
+- Your module must be extended by *ThreeScaleToolbox::Command* module. It allows your command to be added to CLI command tree.
+- Must implement `command` module function and return instance of `Cri::Command` from [cri](https://github.com/ddfreyne/cri)
+- Add your subcommand to `3scale` CLI command tree by calling parent command's module's `add_subcommand` method.
+
+Checking `copy` command help, it can be verified the new subcommand `foo` is added.
+
+```
+$ RUBYOPT=-Ilib 3scale help copy
+NAME
+    copy - 3scale CLI copy
+
+USAGE
+    3scale copy <command> [options]
+
+DESCRIPTION
+    3scale CLI copy tools to manage your API from the terminal.
+
+SUBCOMMANDS
+    foo         3scale copy foo
+    service     3scale CLI copy service
+
+OPTIONS
+    -h --help         show help for this command
+
+OPTIONS FOR 3SCALE
+    -v --version      Prints the version of this command
+```
+
+Now, package your plugin as a [gem](https://guides.rubygems.org/make-your-own-gem/) and let us know about it.
+
+## Existing Plugins

exe/3scale

@@ -1,14 +1,8 @@
 #!/usr/bin/env ruby
 
+require '3scale_toolbox'
 require '3scale_toolbox/cli'
 
-options, argv = ThreeScaleToolbox::CLI.parse
+args = ARGV.clone
 
-unless options.command
-  puts 'Available subcommands: '
-  puts ThreeScaleToolbox::CLI.subcommands
-  puts
-  ThreeScaleToolbox::CLI.print_help!
-end
-
-exec options.command.full_path, *ARGV
+ThreeScaleToolbox::CLI.run args