ego 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7a1b7a652d2e75a9e5a22d05a9627f1b5f63b94d
-  data.tar.gz: 5e7aa5063ddf5f986b341a9bb4ac6f9f165d3358
+  metadata.gz: 8250ad3de4494ebfced808df3a5cb09de9707a38
+  data.tar.gz: 333930e6ddc866ec268016395b38061bc26aa9ab
 SHA512:
-  metadata.gz: 0711a3f6ddb2ef92913409ffb2e2a66a55b6dbec57f0fcf9057ab598803175254b26a40785996aab3d6ece9eae279f03fa55417167f057a0531d9d465e932116
-  data.tar.gz: b816f63c6fadea1d33066b65f8ca6067c2af1409e01e323353f57a58f99c3d28775dfc6d6d174c14cca138ab72fc63727b29709c1a93a578f62184d4ab1e0fa3
+  metadata.gz: de4f362f46c4347e659330f418524a4cc3ce3f3ee0f1bdd8adcd97a63fb8257b6b61f9a34e31e9a339ba0725efc02f4faa590ef6ef1edb5f56dfd5415cc77d43
+  data.tar.gz: df7fadaf3e23e57fec7634623da1a2a56135ff6c9ec8e3b5b501fd87168d5aac8dc7057f3523a2aab4991772e5c77adfc1bddd580f8ccfb17ee6a0dfe14fe00a

data/.travis.yml

@@ -1,4 +1,7 @@
 language: ruby
 rvm:
-  - 2.0
+  - 2.3
   - 2.4
+  - 2.5
+before_install:
+  - gem update --system

data/README.md

@@ -36,7 +36,7 @@ looks like that responds to a query beginning with "hello...", "hi...", or
 Ego.plugin do |robot|
   robot.can 'greet you'
 
-  robot.on /^(hello|hi|hey)/i, 3 do
+  robot.on /^(hello|hi|hey)/i do
     say [
       'Hello.',
       'Hi.',
@@ -59,15 +59,11 @@ This adds a new "capability", which serves as documentation for the user and
 answers the question "What can this plug-in do?"
 
 ```ruby
-robot.on /^(hello|hi|hey)/i, 3 ...
+robot.on /^(hello|hi|hey)/i ...
 ```
 
 This is the condition that determines what queries should invoke the following
-action. The first argument is a regular expression to match the query against.
-Sometimes you may want to match very specific things and sometimes something
-broader. To help ego respond the right way when two or more patterns match
-your query, you can optionally specify a priority (higher number = higher
-priority) as the second argument.
+action. A regular expression is specified to match the query against.
 
 ```ruby
 ... do
@@ -83,14 +79,14 @@ This is the part that gets run when the pattern matches the query. From here
 you can do anything you want including deferring to external programs. The
 `robot` provides various methods to you to respond to the user. Usually, you'll
 want to make use of part of the query inside the action. You can access named
-match groups through the optional `params` parameter:
+match groups as block arguments:
 
 ```ruby
 Ego.plugin do |robot|
   robot.can 'repeat what you say'
 
-  robot.on /^say (?<input>.+)/i do |params|
-    say params[:input]
+  robot.on /^say (?<input>.+)/i do |input|
+    say input
   end
 end
 ```
@@ -113,7 +109,7 @@ execute any Ruby scripts in this directory indiscriminately.
 
 ## License
 
-Copyright (C) 2016-2017  Noah Frederick
+Copyright (C) 2016-2018  Noah Frederick
 
 This program is free software: you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by

data/ego.gemspec

@@ -23,7 +23,7 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.required_ruby_version = "~> 2.0"
+  spec.required_ruby_version = "~> 2.3"
 
   spec.add_development_dependency "bundler", "~> 1.6"
   spec.add_development_dependency "rake"

data/lib/ego.rb

@@ -20,22 +20,20 @@ module Ego
   #   Ego.plugin do |robot|
   #     robot.can 'repeat what you say'
   #
-  #     robot.on /^say (?<input>.+)/i do |params|
-  #       say params[:input]
+  #     robot.on /^say (?<input>.+)/i do |input|
+  #       say input
   #     end
   #   end
   #
   # @param name [String, nil] the plug-in name (uses plug-in file's basename if given `nil`)
-  # @param builtin [Boolean] whether to register as a built-in plug-in
   # @param body the plug-in body
   # @return [Plugin] the instantiated plug-in
   #
   # @see Robot
-  def self.plugin(name = nil, builtin: false, &body)
-    if name.nil?
-      path = caller_locations(1, 1)[0].absolute_path
-      name = File.basename(path, '.*')
-    end
+  def self.plugin(name = nil, &body)
+    path = caller_locations(1, 1)[0].absolute_path
+    name ||= File.basename(path, '.*')
+    builtin = path.start_with?(__dir__)
 
     Plugin.register(name, body, builtin: builtin)
   end

data/lib/ego/capability.rb

@@ -1,9 +1,11 @@
+require_relative 'plugin'
+
 module Ego
   # A capability defines functionality added to a `Robot` instance by a
   # plug-in.
   #
   # @note New capabilities should be specified by plug-ins using the
-  #   `robot#can` method.
+  #   `Robot#can` method.
   #
   # @example Add a capability to the robot instance
   #   Ego.plugin do |robot|
@@ -16,10 +18,9 @@ module Ego
     attr_reader :desc, :plugin
 
     # @param desc [String] the capability description answering "What can the robot do?"
-    # @param plugin [Plugin] the plug-in that provides the capability
-    def initialize(desc, plugin)
+    def initialize(desc)
       @desc = desc
-      @plugin = plugin
+      @plugin = Plugin.context
     end
 
     # @return [String] the capability description

data/lib/ego/handler.rb

@@ -3,7 +3,7 @@ require_relative 'robot_error'
 module Ego
   # Handlers map user queries to actions.
   #
-  # @note Handlers should be registered by plug-ins using the `robot#on`
+  # @note Handlers should be registered by plug-ins using the `Robot#on`
   #   method.
   #
   # @example Add a handler to the robot instance
@@ -56,9 +56,13 @@ module Ego
     #
     # @param query [String] the query to match the condition against
     # @return [false] if condition doesn't match
-    # @return the return value of condition
+    # @return [Array] parameters to pass to the action
     def handle(query)
-      @condition.call(query) || false
+      return false unless result = @condition.call(query)
+
+      @action.parameters.each_with_object([]) do |param, arr|
+        arr << result[param.pop]
+      end
     end
 
     protected

data/lib/ego/plugin.rb

@@ -6,6 +6,8 @@ module Ego
   class Plugin
     # Manifest of all registered plug-ins
     @@plugins = {}
+    # Current plug-in context
+    @@context = nil
 
     attr_reader :name, :body, :builtin
 
@@ -18,12 +20,12 @@ module Ego
       @builtin = builtin
     end
 
-    # Require all given plug-in paths
+    # Load all given plug-in paths
     #
     # @param paths [Array] absolute paths to plug-in files
     # @return [void]
     def self.load(paths)
-      paths.each { |path| require path }
+      paths.each { |path| Kernel.load path }
     end
 
     # Register a new plug-in
@@ -46,13 +48,19 @@ module Ego
     # @return [Object] the decorated object
     def self.decorate(obj)
       @@plugins.each do |name, plugin|
-        if obj.respond_to?(:context)
-          obj.context = plugin
-        end
+        @@context = plugin
         plugin.body.call(obj)
+        @@context = nil
       end
 
       obj
     end
+
+    # Get the currently executing plug-in.
+    #
+    # @return [Plugin] currently executing plugin
+    def self.context
+      @@context
+    end
   end
 end

data/lib/ego/plugin_helper.rb

@@ -0,0 +1,66 @@
+require 'ego/filesystem'
+
+module Ego
+  # The PluginHelper assists the user in writing extensions by generating
+  # boilerplate code.
+  #
+  # @see Plugin
+  class PluginHelper
+    # @param query [String] example user query
+    # @param program_name [String] the executable name
+    def initialize(query:, program_name:)
+      @query = query
+      @program_name = program_name
+    end
+
+    # Derive a slug from the user query.
+    #
+    # @return [String] slug
+    def slug
+      @slug ||= @query
+        .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+        .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+        .tr('\'', '')
+        .gsub(/\W+/, '_')
+        .gsub(/__+/, '_')
+        .sub(/_$/, '')
+        .downcase
+    end
+
+    # Derive a plug-in path from the user query.
+    #
+    # @return [String] plug-in path
+    def path
+      @path ||= Filesystem.config("plugins/#{slug}.rb")
+        .sub(/^#{ENV['HOME']}/, '~')
+    end
+
+    # Provide a hint for initializing a new plug-in.
+    #
+    # @return [String] hint text
+    def hint
+      require 'shellwords'
+      @hint ||= <<~EOF
+        I don't understand "#{@query}".
+
+        If you would like to add this capability, start by running:
+          #{@program_name} #{@query.shellescape} > #{path}
+      EOF
+    end
+
+    # Provide a template for initializing a new plug-in.
+    #
+    # @return [String] template contents
+    def template
+      @template ||= <<~EOF
+        Ego.plugin do |robot|
+          robot.can 'do something new'
+
+          robot.on(/^#{@query}$/i) do |params|
+            alert 'Not implemented yet. Go ahead and edit #{path}.'
+          end
+        end
+      EOF
+    end
+  end
+end

data/lib/ego/plugins/capabilities.rb

@@ -1,4 +1,4 @@
-Ego.plugin builtin: true do |robot|
+Ego.plugin do |robot|
   robot.can 'list capabilities'
 
   robot.on(
@@ -14,4 +14,20 @@ Ego.plugin builtin: true do |robot|
       printf("- %s %s\n", cap.to_s, plugin)
     end
   end
+
+  # Returns `true` if any registered handler can handle the given query.
+  #
+  # @param query [String] user query
+  # @return [Boolean] whether any handler matches the query
+  robot.provide :understand? do |query|
+    !first_handler_for(query).nil?
+  end
+
+  robot.on(/^(can|do|would) you understand\s+(?<query>.+)/i => 6) do |query|
+    if understand?(query)
+      say 'Yes, I understand that.'
+    else
+      say 'No, I do not understand that.'
+    end
+  end
 end

data/lib/ego/plugins/fallback.rb

@@ -1,36 +1,20 @@
-Ego.plugin builtin: true do |robot|
-  robot.can 'help you write extensions'
+Ego.plugin do |robot|
+  robot.can 'help you write plug-ins'
 
   robot.on_unhandled_query do |query|
-    plugin_slug = query
-      .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
-      .gsub(/([a-z\d])([A-Z])/, '\1_\2')
-      .tr('\'', '')
-      .gsub(/\W+/, '_')
-      .gsub(/__+/, '_')
-      .downcase
+    require 'ego/plugin_helper'
 
-    plugin_path = Ego::Filesystem.config("plugins/#{plugin_slug}.rb")
-    plugin_path.sub!(/^#{ENV['HOME']}/, '~')
+    helper = Ego::PluginHelper.new(
+      query: query,
+      program_name: options.usage.program_name
+    )
 
     if $stdout.isatty
-      require 'shellwords'
-      alert %q(I don't understand "%s".), query
-      alert ''
-      alert 'If you would like to add this capability, start by running:'
-      alert '  %s %s > %s', $PROGRAM_NAME, query.shellescape, plugin_path
+      alert helper.hint
     end
 
     if verbose? || !$stdout.isatty
-      puts <<~EOF
-        Ego.plugin do |robot|
-          robot.can 'do something new'
-
-          robot.on(/^#{query}$/i) do |params|
-            alert 'Not implemented yet. Go ahead and edit #{plugin_path}.'
-          end
-        end
-      EOF
+      puts helper.template
     end
   end
 end

data/lib/ego/plugins/robot_io.rb

@@ -1,4 +1,4 @@
-Ego.plugin builtin: true do |robot|
+Ego.plugin do |robot|
   robot.can 'output text to the terminal'
 
   # Provide #say, #emote, #alert, and #debug
@@ -10,7 +10,7 @@ Ego.plugin builtin: true do |robot|
   end
 
   robot.can 'repeat what you say'
-  robot.on(/^(?:say|echo)\s+(?<input>.+)/i) do |match|
-    say match[:input]
+  robot.on(/^(?:say|echo)\s+(?<input>.+)/i) do |input|
+    say input
   end
 end

data/lib/ego/plugins/social.rb

@@ -1,4 +1,4 @@
-Ego.plugin builtin: true do |robot|
+Ego.plugin do |robot|
   robot.can 'socialize'
 
   robot.on(/^((who|what) are you|what('?s| is) your name)/i) do

data/lib/ego/plugins/status.rb

@@ -0,0 +1,19 @@
+Ego.plugin do |robot|
+  robot.can 'report robot status'
+
+  robot.define_hook :on_status
+
+  robot.on_ready do
+    @startup_time = Time.now
+  end
+
+  robot.on_status do
+    printf "uptime: %i seconds\n", Time.now - @startup_time
+    printf "verbosity: %s\n", (verbose? ? 'verbose' : 'normal')
+  end
+
+  robot.on(/(status|diagnostic|uptime)/i => 1) do
+    emote 'running self-diagnostics'
+    run_hook :on_status
+  end
+end

data/lib/ego/plugins/system.rb

@@ -1,4 +1,4 @@
-Ego.plugin builtin: true do |robot|
+Ego.plugin do |robot|
   robot.can 'execute system commands'
 
   robot.provide :system do |*args|

data/lib/ego/printer.rb

@@ -21,7 +21,7 @@ module Ego
 
     # Write stylized message to `$stdout` indicating an emote.
     #
-    # Plug-ins may use this method to indicating what the robot is doing.
+    # Plug-ins may use this method to indicate what the robot is doing.
     #
     # @example
     #   robot.emote 'runs away'
@@ -48,16 +48,15 @@ module Ego
       errs sprintf(message, *replacements).light_red
     end
 
-    # Write stylized message to `$stderr` indicating a debugging message
-    # message.
+    # Write stylized message to `$stderr` indicating a debugging message.
     #
     # Plug-ins may use this method to provide extra information when the
     # `--verbose` flag is supplied at the command-line.
     #
     # @example
-    #   name = 'world'
-    #   robot.alert 'Hello, %s.', name
-    #   # => "Hello, world."
+    #   result = 'output'
+    #   robot.debug 'Result: %s.', result
+    #   # => "Result: output"
     #
     # @param message [Object] message to write
     # @param *replacements [Object, ...] `printf`-style replacements

data/lib/ego/robot.rb

@@ -16,8 +16,6 @@ module Ego
     include Hooks::InstanceHooks
 
     attr_reader :name, :options, :capabilities
-    # Set/get currently executing plug-in
-    attr_accessor :context
 
     alias_method :provide, :define_singleton_method
 
@@ -31,7 +29,6 @@ module Ego
     def initialize(options)
       @name = options.robot_name
       @options = options
-      @context = nil
       @capabilities = []
       @handlers = []
     end
@@ -70,10 +67,7 @@ module Ego
     #
     # @see Capability
     def can(desc)
-      unless @context
-        raise RobotError, 'Cannot add capability outside of plug-in context'
-      end
-      @capabilities << Capability.new(desc, @context)
+      @capabilities << Capability.new(desc)
     end
 
     # Register a new query handler.
@@ -136,13 +130,14 @@ module Ego
     # @return result of the action
     def run_action(action, params)
       run_hook :before_action, action, params
-      result = instance_exec(params, &action)
+      result = instance_exec(*params, &action)
       run_hook :after_action, action, params, result
       result
     end
 
-    # Call `#handle` on each registered handler until a truthy value is
-    # returned, then run the associated action.
+    # Run the action for the highest-priority handler that can handle the given
+    # query and return the result. Associated hooks are run before and after
+    # running the action.
     #
     # @hook before_handle_query
     # @hook after_handle_query
@@ -156,16 +151,32 @@ module Ego
     def handle(query)
       run_hook :before_handle_query, query
 
-      @handlers.sort.reverse_each do |handler|
-        if params = handler.handle(query)
-          result = run_action(handler.action, params)
+      first_handler_for(query) do |handler, params|
+        return run_action(handler.action, params).tap do |result|
           run_hook :after_handle_query, query, handler
-          return result
         end
       end
 
       run_hook :on_unhandled_query, query
       false
     end
+
+    # Find the highest-priority handler for a given query and return it. When a
+    # block is passed, the block is called if and only if a handler is found,
+    # passing the handler and parsed params as the block's arguments.
+    #
+    # @param query [String] user query
+    # @return [nil] if no handler can handle query
+    # @return [Handler] the first matching handler
+    def first_handler_for(query)
+      @handlers.sort.reverse_each do |handler|
+        if params = handler.handle(query)
+          yield(handler, params) if block_given?
+          return handler
+        end
+      end
+
+      nil
+    end
   end
 end

data/lib/ego/version.rb

@@ -1,4 +1,4 @@
 module Ego
   # Gem version
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

data/spec/ego/capability_spec.rb

@@ -3,20 +3,24 @@ require 'ego/capability'
 RSpec.describe Ego::Capability do
   let(:desc) { 'my desc' }
   let(:plugin) { double('Ego::Plugin') }
-  subject { described_class.new(desc, plugin) }
 
-  context 'on initization' do
+  describe '#initialize' do
     it 'sets its description' do
+      allow(Ego::Plugin).to receive(:context) { plugin }
+      subject = described_class.new(desc)
       expect(subject.desc).to eq(desc)
     end
 
-    it 'sets its plug-in' do
+    it 'sets the plug-in context' do
+      allow(Ego::Plugin).to receive(:context) { plugin }
+      subject = described_class.new(desc)
       expect(subject.plugin).to be plugin
     end
   end
 
   describe '#to_s' do
     it 'returns the description' do
+      subject = described_class.new(desc)
       expect(subject.to_s).to eq(desc)
     end
   end

data/spec/ego/handler_spec.rb

@@ -1,7 +1,7 @@
 require 'ego/handler'
 
 RSpec.describe Ego::Handler do
-  let(:condition) { ->(q) { 'bar' if q == 'foo' } }
+  let(:condition) { ->(q) { {p: 'bar', q: 'baz'} if q == 'foo' } }
   let(:regexp) { /^baz/i }
   let(:action) { ->(p) { puts p } }
   let(:priority) { 2 }
@@ -55,8 +55,26 @@ RSpec.describe Ego::Handler do
     end
 
     context 'when the query can be handled' do
-      it 'returns the result of the condition closure' do
-        expect(subject.handle('foo')).to eq('bar')
+      it 'returns an array of parameters' do
+        expect(subject.handle('foo')).to be_a Array
+      end
+
+      it 'returns parameters specified as action arguments' do
+        expect(subject.handle('foo')).to include('bar')
+      end
+
+      it 'does not return parameters not specified as action arguments' do
+        expect(subject.handle('foo')).not_to include('baz')
+      end
+
+      it 'respects the order of action arguments' do
+        subject = described_class.new(condition, ->(q, p) { }, priority)
+        expect(subject.handle('foo')).to eq(['baz', 'bar'])
+      end
+
+      it 'gracefully handles extra action arguments' do
+        subject = described_class.new(condition, ->(p, q, r) { }, priority)
+        expect { subject.handle('foo') }.not_to raise_error
       end
     end
   end

data/spec/ego/plugin_helper_spec.rb

@@ -0,0 +1,59 @@
+require 'ego/plugin_helper'
+
+RSpec.describe Ego::PluginHelper do
+  let(:query) { 'Do something new!' }
+  let(:program_name) { 'ego' }
+  subject { described_class.new(query: query, program_name: program_name) }
+
+  describe '#slug' do
+    it 'slugifies the query' do
+      expect(subject.slug).to eq('do_something_new')
+    end
+  end
+
+  describe '#path' do
+    it 'returns a path to the plugins directory' do
+      expect(subject.path).to match(/\/plugins\//)
+    end
+
+    it 'uses a tilde for the home directory' do
+      expect(subject.path).to match(/^~\//)
+    end
+
+    it 'names the file after the slug' do
+      expect(subject.path).to match(subject.slug)
+    end
+
+    it 'appends an extension' do
+      expect(subject.path).to match(/\.rb$/)
+    end
+  end
+
+  describe '#hint' do
+    it 'contains the original query' do
+      expect(subject.hint).to match(query)
+    end
+
+    it 'contains the program name followed by the shell-escaped query' do
+      expect(subject.hint).to match(/ego Do\\ something\\ new\\! > /)
+    end
+
+    it 'contains the suggested plug-in path' do
+      expect(subject.hint).to match(subject.path)
+    end
+  end
+
+  describe '#template' do
+    it 'contains ruby code to bootstrap a new plug-in' do
+      expect(subject.template).to match(/^Ego\.plugin do \|robot\|/)
+    end
+
+    it 'contains the original query as a regex' do
+      expect(subject.template).to match(query)
+    end
+
+    it 'suggests editing the plug-in path' do
+      expect(subject.template).to match("edit #{subject.path}")
+    end
+  end
+end

data/spec/ego/plugin_spec.rb

@@ -38,6 +38,7 @@ RSpec.describe Ego::Plugin do
 
     before do
       described_class.class_variable_set :@@plugins, {}
+      described_class.class_variable_set :@@context, nil
       described_class.register('a', proc { |obj|
         obj.a = 'foo'
       })
@@ -46,9 +47,18 @@ RSpec.describe Ego::Plugin do
       })
     end
 
-    it 'sets obj#context to each registered plugin' do
-      expect(obj).to receive(:context=).twice
+    it 'sets self.context to each registered plugin' do
+      described_class.register('c', proc { |obj|
+        obj.context = described_class.context
+      })
+      described_class.decorate(obj)
+      expect(obj.context).to be_instance_of(described_class)
+    end
+
+    it 'sets resets self.context to nil' do
+      expect(described_class.context).to be_nil
       described_class.decorate(obj)
+      expect(described_class.context).to be_nil
     end
 
     it 'calls each plugin body passing the obj' do

data/spec/ego/plugins/capabilities_spec.rb

@@ -0,0 +1,73 @@
+require 'ego/robot'
+
+RSpec.describe Ego::Robot, 'with capabilities plug-in' do
+  subject { robot_with_plugin('capabilities') }
+
+  describe '#understand?' do
+    it 'is defined on the robot instance' do
+      expect(subject.respond_to?(:understand?)).to be true
+    end
+
+    it 'returns false for queries the robot cannot handle' do
+      expect(subject.understand?('xxx')).to be false
+    end
+
+    it 'returns true for queries the robot can handle' do
+      subject.on(/^zzz$/) { }
+      expect(subject.understand?('zzz')).to be true
+    end
+  end
+
+  it { should be_able_to 'list capabilities' }
+
+  it { should handle_query 'list what you can do' }
+  it { should handle_query 'list handlers' }
+  it { should handle_query 'show me handlers' }
+  it { should handle_query 'show me what you can do' }
+  it { should handle_query 'show me what queries you understand' }
+  it { should handle_query 'show me what queries you can understand' }
+  it { should handle_query 'tell me what you can do' }
+  it { should handle_query 'tell me what you are able to do' }
+  it { should handle_query 'tell me what you can understand' }
+  it { should handle_query 'tell me what queries you can understand' }
+  it { should handle_query 'help' }
+  it { should handle_query 'help me' }
+  it { should handle_query 'what can you do' }
+  it { should handle_query 'what can you understand' }
+  it { should handle_query 'what are you able to do' }
+  it { should handle_query 'what do you do' }
+  it { should handle_query 'what do you understand' }
+  it { should handle_query 'what are you able to handle' }
+
+  it 'prints list of capabilities' do
+    expect { subject.handle('help') }.to output(
+      <<~OUT
+        I can...
+        - list capabilities (capabilities*)
+      OUT
+    ).to_stdout
+  end
+
+  it { should handle_query 'can you understand x' }
+  it { should handle_query 'can you understand x?' }
+  it { should handle_query 'do you understand x' }
+  it { should handle_query 'would you understand x' }
+  it { should_not handle_query 'do you understand' }
+  it { should_not handle_query 'do you understand?' }
+
+  it 'prints a message when it can understand' do
+    expect { subject.handle('do you understand can you understand x') }.to output(
+      <<~OUT
+        Yes, I understand that.
+      OUT
+    ).to_stdout
+  end
+
+  it 'prints a message when it can not understand' do
+    expect { subject.handle('do you understand xxx') }.to output(
+      <<~OUT
+        No, I do not understand that.
+      OUT
+    ).to_stdout
+  end
+end

data/spec/ego/plugins/fallback_spec.rb

@@ -0,0 +1,22 @@
+require 'ego/robot'
+
+RSpec.describe Ego::Robot, 'with fallback plug-in' do
+  subject { robot_with_plugin('fallback') }
+  let(:unhandlable_query) { 'xxx' }
+
+  it { should be_able_to 'help you write plug-ins' }
+
+  it { should_not handle_query :unhandlable_query }
+
+  it 'prints a hint when a query is unhandled' do
+    expect { subject.handle('xxx') }.to output(
+      /^Ego\.plugin/
+    ).to_stdout
+  end
+
+  it 'prints a hint containing the original query' do
+    expect { subject.handle('xxx') }.to output(
+      /xxx/
+    ).to_stdout
+  end
+end

data/spec/ego/plugins/robot_io_spec.rb

@@ -0,0 +1,28 @@
+require 'ego/robot'
+
+RSpec.describe Ego::Robot, 'with robot_io plug-in' do
+  subject { robot_with_plugin('robot_io') }
+
+  it { should be_able_to 'output text to the terminal' }
+
+  describe '#verbose?' do
+    it 'is defined on the robot instance' do
+      expect(subject.respond_to?(:verbose?)).to be true
+    end
+  end
+
+  it { should be_able_to 'repeat what you say' }
+
+  it { should handle_query 'say hello' }
+  it { should handle_query 'echo hello' }
+  it { should_not handle_query 'whatever you say' }
+  it { should_not handle_query 'there is an echo in here' }
+
+  it 'prints the input' do
+    expect { subject.handle('say hello, robot') }.to output(
+      <<~OUT
+        hello, robot
+      OUT
+    ).to_stdout
+  end
+end

data/spec/ego/plugins/social_spec.rb

@@ -0,0 +1,32 @@
+require 'ego/robot'
+
+RSpec.describe Ego::Robot, 'with social plug-in' do
+  subject { robot_with_plugin('social') }
+
+  it { should be_able_to 'socialize' }
+
+  it { should handle_query 'who are you' }
+  it { should handle_query 'what are you' }
+  it { should handle_query 'what is your name' }
+  it { should handle_query 'what\'s your name' }
+
+  it 'prints its name' do
+    expect { subject.handle('who are you') }.to output(
+      /^(I'm TestBot|This is TestBot, a robot)\./
+    ).to_stdout
+  end
+
+  it { should handle_query 'hello' }
+  it { should handle_query 'salve' }
+  it { should handle_query 'ave' }
+  it { should handle_query 'hi' }
+  it { should handle_query 'hey' }
+  it { should handle_query 'ciao' }
+  it { should handle_query 'hej' }
+
+  it 'greets you' do
+    expect { subject.handle('hello') }.to output(
+      /^[[:upper:]].+\./
+    ).to_stdout
+  end
+end

data/spec/ego/plugins/status_spec.rb

@@ -0,0 +1,58 @@
+require 'ego/robot'
+
+RSpec.describe Ego::Robot, 'with status plug-in' do
+  subject { robot_with_plugin('status') }
+
+  it { should be_able_to 'report robot status' }
+
+  it { should handle_query 'status' }
+  it { should handle_query 'what is your status' }
+  it { should handle_query 'diagnostic' }
+  it { should handle_query 'diagnostics' }
+  it { should handle_query 'do self-diagnostic' }
+  it { should handle_query 'uptime' }
+  it { should handle_query 'what is your uptime' }
+
+  describe '#on_status' do
+    it 'is defined' do
+      expect(subject.respond_to?(:on_status)).to be true
+    end
+
+    it 'can be hooked into' do
+      subject.on_status { print '--status--' }
+      expect { subject.run_hook :on_status }.to output(/--status--/).to_stdout
+    end
+  end
+
+  describe 'handler' do
+    it 'runs the on_status hook' do
+      allow(subject).to receive(:puts)
+      allow(subject).to receive(:run_hook)
+
+      expect(subject).to receive(:run_hook).with(:on_status)
+      subject.handle('status')
+    end
+
+    it 'prints an emote' do
+      allow(subject).to receive(:run_hook)
+
+      expect { subject.handle('status') }.to output(
+        <<~OUT
+          *running self-diagnostics*
+        OUT
+      ).to_stdout
+    end
+
+    it 'prints robot uptime' do
+      expect { subject.handle('status') }.to output(
+        /uptime: \d+ seconds\n/
+      ).to_stdout
+    end
+
+    it 'prints robot verbosity' do
+      expect { subject.handle('status') }.to output(
+        /verbosity: (normal|verbose)\n/
+      ).to_stdout
+    end
+  end
+end

data/spec/ego/plugins/system_spec.rb

@@ -0,0 +1,72 @@
+require 'ego/robot'
+
+RSpec.describe Ego::Robot, 'with system plug-in' do
+  subject { robot_with_plugin('system') }
+
+  it { should be_able_to 'execute system commands' }
+
+  describe '#system' do
+    let(:args) { ['foo', 'bar'] }
+
+    before do
+      allow(Kernel).to receive(:system).and_return(true)
+      allow(subject).to receive(:debug)
+      allow(subject).to receive(:alert)
+    end
+
+    it 'is defined' do
+      expect(subject.respond_to?(:system)).to be true
+    end
+
+    it 'calls Kernel.system' do
+      expect(Kernel).to receive(:system).with(*args)
+      subject.system *args
+    end
+
+    it 'prints a debug message' do
+      expect(subject).to receive(:debug).with(
+        'Running system with arguments %s.',
+        args
+      )
+      subject.system *args
+    end
+
+    it 'prints nothing on success' do
+      expect(subject).not_to receive(:alert)
+      subject.system *args
+    end
+
+    it 'prints an alert on error' do
+      allow(Kernel).to receive(:system).with(*args).and_return(false)
+      expect(subject).to receive(:alert).with(
+        'Sorry, there was a problem running %s.',
+        args.first
+      )
+      subject.system *args
+    end
+  end
+
+  it { should be_able_to 'tell you your login name' }
+
+  it { should handle_query 'what is my name' }
+  it { should handle_query 'what is my user name' }
+  it { should handle_query 'what is my username' }
+  it { should handle_query 'what is my login name' }
+  it { should handle_query 'what\'s my name' }
+  it { should handle_query 'what\'s my user name' }
+  it { should handle_query 'what\'s my username' }
+  it { should handle_query 'what\'s my login name' }
+  it { should handle_query 'who am I' }
+  it { should handle_query 'who am I logged in as' }
+  it { should_not handle_query 'what is your name' }
+  it { should_not handle_query 'who are you' }
+
+  it 'tells you your login name' do
+    expect(subject).to receive(:system).with('who').and_return(true)
+    expect { subject.handle('who am I') }.to output(
+      <<~OUT
+        You are currently logged in as:
+      OUT
+    ).to_stdout
+  end
+end

data/spec/ego/printer_spec.rb

@@ -5,6 +5,9 @@ module Ego
     let(:verbose_printer) { (Class.new { include Printer; def verbose?; true; end }).new }
     let(:printer) { (Class.new { include Printer }).new }
 
+    before(:all) { String.disable_colorization = false }
+    after(:all) { String.disable_colorization = true }
+
     describe '#puts' do
       it 'is callable on the module' do
         expect(described_class.respond_to?(:puts)).to be true

data/spec/ego/robot_spec.rb

@@ -77,34 +77,17 @@ RSpec.describe Ego::Robot do
   end
 
   describe '#can' do
-    context 'without a plug-in context set' do
-      it 'fails' do
-        expect { subject.can('fail') }.to raise_error(Ego::RobotError)
-      end
+    it 'adds a capability' do
+      expect(subject.capabilities).to be_empty
+      subject.can('do A')
+      expect(subject.capabilities.count).to eq(1)
+      subject.can('do B')
+      expect(subject.capabilities.count).to eq(2)
     end
 
-    context 'with a plug-in context set' do
-      let(:plugin_name) { 'my_plug' }
-      before do
-        allow(plugin).to receive(:name) { plugin_name }
-        subject.context = plugin
-      end
-
-      it 'adds a capability' do
-        expect(subject.capabilities).to be_empty
-        subject.can('succeed')
-        expect(subject.capabilities).not_to be_empty
-      end
-
-      it 'sets the capability description' do
-        subject.can('succeed')
-        expect(subject.capabilities.last.desc).to eq('succeed')
-      end
-
-      it 'records the plug-in with the capability' do
-        subject.can('succeed')
-        expect(subject.capabilities.last.plugin.name).to eq(plugin_name)
-      end
+    it 'sets the capability description' do
+      subject.can('succeed')
+      expect(subject.capabilities.last.desc).to eq('succeed')
     end
   end
 
@@ -158,11 +141,11 @@ RSpec.describe Ego::Robot do
 
   describe '#run_action' do
     it 'calls the action with supplied parameters' do
-      expect(subject.run_action(->(params) { params }, 'foo')).to eq('foo')
+      expect(subject.run_action(->(params) { params }, ['foo'])).to eq('foo')
     end
 
     it 'executes the action in the context of the robot instance' do
-      expect(subject.run_action(->(params) { name }, 'foo')).to eq(subject.name)
+      expect(subject.run_action(->() { name }, [])).to eq(subject.name)
     end
   end
 
@@ -208,20 +191,38 @@ RSpec.describe Ego::Robot do
     end
   end
 
-  describe '#handle' do
+  describe '#first_handler_for' do
     before do
       subject.on(
-        ->(q) { :three if 'bar'.match(q) } => 3,
-        ->(q) { :two if 'foo'.match(q) } => 2,
-        ->(q) { :one if 'foo'.match(q) } => 1,
-      ) { |params| params }
+        ->(q) { {} if 'bar'.match(q) } => 3,
+        ->(q) { {} if 'foo'.match(q) } => 2,
+        ->(q) { {} if 'foo'.match(q) } => 1,
+      ) { }
     end
 
     it 'chooses the highest-priority handler that matches the query' do
+      expect(subject.first_handler_for('foo').priority).to eq(2)
+    end
+
+    it 'returns nil when no handlers match' do
+      expect(subject.first_handler_for('xxx')).to be_nil
+    end
+  end
+
+  describe '#handle' do
+    before do
+      subject.on(
+        ->(q) { {param: :three} if 'bar'.match(q) } => 3,
+        ->(q) { {param: :two} if 'foo'.match(q) } => 2,
+        ->(q) { {param: :one} if 'foo'.match(q) } => 1,
+      ) { |param| param }
+    end
+
+    it 'returns the result of the action' do
       expect(subject.handle('foo')).to eq(:two)
     end
 
-    it 'returns false when no handlers match' do
+    it 'returns false when the query is unhandled' do
       expect(subject.handle('xxx')).to be false
     end
   end

data/spec/ego/runner_spec.rb

@@ -0,0 +1,55 @@
+require 'ego/runner'
+
+RSpec.describe Ego::Runner do
+  context 'with empty arguments' do
+    subject { described_class.new([]) }
+
+    it 'prints usage help' do
+      expect { subject.run }.to output(
+        /^Usage:/
+      ).to_stdout
+    end
+  end
+
+  context 'with --help' do
+    subject { described_class.new(['--help']) }
+
+    it 'prints usage help' do
+      expect { subject.run }.to output(
+        /^Usage:/
+      ).to_stdout
+    end
+  end
+
+  context 'with --version' do
+    subject { described_class.new(['--version']) }
+
+    it 'prints gem version' do
+      expect { subject.run }.to output(
+        "ego v#{Ego::VERSION}\n"
+      ).to_stdout
+    end
+  end
+
+  context 'with invalid arguments' do
+    subject { described_class.new(['--invalid-flag']) }
+
+    it 'prints usage error and help' do
+      expect { subject.run }.to raise_exception(SystemExit).and output(
+        /^invalid option:/
+      ).to_stderr.and output(
+        /^Usage:/
+      ).to_stdout
+    end
+  end
+
+  context 'with simple query' do
+    subject { described_class.new(['--no-plugins', 'echo hello']) }
+
+    it 'prints a response' do
+      expect { subject.run }.to output(
+        /hello/
+      ).to_stdout
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -21,3 +21,50 @@ RSpec.configure do |config|
   # be too noisy due to issues in dependencies.
   config.warnings = true
 end
+
+# Get a new robot instance with plugin.
+#
+# @param plugin [String] basename of plugin script
+# @return [Ego::Robot] the decorated robot instance
+def robot_with_plugin(plugin)
+  require 'ego'
+
+  options = double('Ego::Options')
+  opt_parser = double('OptionParser')
+
+  allow(opt_parser).to receive_messages({
+    program_name: 'ego',
+  })
+
+  allow(options).to receive_messages({
+    robot_name: 'TestBot',
+    verbose: false,
+    usage: opt_parser,
+  })
+
+  robot = Ego::Robot.new(options)
+  robot.extend(Ego::Printer) # Needed to test most robot output
+  String.disable_colorization = true
+
+  paths = Ego::Filesystem.builtin_plugins.select do |path|
+    path.end_with?("/#{plugin}.rb")
+  end
+
+  Ego::Plugin.class_variable_set :@@plugins, {}
+  Ego::Plugin.load paths
+  Ego::Plugin.decorate(robot).ready
+end
+
+RSpec::Matchers.define :handle_query do |query|
+  match do |robot|
+    !robot.first_handler_for(query).nil?
+  end
+end
+
+RSpec::Matchers.define :be_able_to do |desc|
+  match do |robot|
+    robot.capabilities.select do |capability|
+      capability.desc == desc
+    end.any?
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ego
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Noah Frederick
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-12-05 00:00:00.000000000 Z
+date: 2018-02-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -123,10 +123,12 @@ files:
 - lib/ego/handler.rb
 - lib/ego/options.rb
 - lib/ego/plugin.rb
+- lib/ego/plugin_helper.rb
 - lib/ego/plugins/capabilities.rb
 - lib/ego/plugins/fallback.rb
 - lib/ego/plugins/robot_io.rb
 - lib/ego/plugins/social.rb
+- lib/ego/plugins/status.rb
 - lib/ego/plugins/system.rb
 - lib/ego/printer.rb
 - lib/ego/robot.rb
@@ -136,10 +138,18 @@ files:
 - spec/ego/capability_spec.rb
 - spec/ego/handler_spec.rb
 - spec/ego/options_spec.rb
+- spec/ego/plugin_helper_spec.rb
 - spec/ego/plugin_spec.rb
+- spec/ego/plugins/capabilities_spec.rb
+- spec/ego/plugins/fallback_spec.rb
+- spec/ego/plugins/robot_io_spec.rb
+- spec/ego/plugins/social_spec.rb
+- spec/ego/plugins/status_spec.rb
+- spec/ego/plugins/system_spec.rb
 - spec/ego/printer_spec.rb
 - spec/ego/robot_error_spec.rb
 - spec/ego/robot_spec.rb
+- spec/ego/runner_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/noahfrederick/ego
 licenses:
@@ -153,7 +163,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - "~>"
     - !ruby/object:Gem::Version
-      version: '2.0'
+      version: '2.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -169,8 +179,16 @@ test_files:
 - spec/ego/capability_spec.rb
 - spec/ego/handler_spec.rb
 - spec/ego/options_spec.rb
+- spec/ego/plugin_helper_spec.rb
 - spec/ego/plugin_spec.rb
+- spec/ego/plugins/capabilities_spec.rb
+- spec/ego/plugins/fallback_spec.rb
+- spec/ego/plugins/robot_io_spec.rb
+- spec/ego/plugins/social_spec.rb
+- spec/ego/plugins/status_spec.rb
+- spec/ego/plugins/system_spec.rb
 - spec/ego/printer_spec.rb
 - spec/ego/robot_error_spec.rb
 - spec/ego/robot_spec.rb
+- spec/ego/runner_spec.rb
 - spec/spec_helper.rb