ego 0.3.0 → 0.4.0

data/lib/ego/options.rb

@@ -1,29 +1,42 @@
 require 'optparse'
 
 module Ego
+  # Parse command-line options and set defaults.
   class Options
 
     attr_reader :mode,
+                :plugins,
                 :robot_name,
                 :verbose,
                 :query,
                 :usage,
                 :usage_error
 
+    # @param argv [Array] command-line arguments
     def initialize(argv)
       @mode = :interpret
+      @plugins = true
       @verbose = false
       parse(argv)
       @query = argv.join(" ")
     end
 
-  private
+    private
 
+    # Parse the arguments supplied at the command line and set options
+    # accordingly.
+    #
+    # @param argv [Array] command-line arguments
+    # @return [void]
     def parse(argv)
       OptionParser.new do |opts|
         @robot_name = opts.program_name.capitalize
         opts.banner = "Usage: #{opts.program_name} [ options ] query..."
 
+        opts.on("-n", "--no-plugins", "Skip loading user plug-ins") do
+          @plugins = false
+        end
+
         opts.on("-s", "--shell", "Start in REPL-mode") do
           @mode = :shell
         end
@@ -51,6 +64,5 @@ module Ego
         end
       end
     end
-
   end
 end

data/lib/ego/plugin.rb

@@ -0,0 +1,58 @@
+module Ego
+  # A plug-in extends Ego with new handlers and other functionality, through a
+  # domain-specific language (DSL).
+  #
+  # @see Robot
+  class Plugin
+    # Manifest of all registered plug-ins
+    @@plugins = {}
+
+    attr_reader :name, :body, :builtin
+
+    # @param name [String] the plug-in name
+    # @param body the plug-in body
+    # @param builtin [Boolean] whether this is a built-in plug-in
+    def initialize(name, body, builtin: false)
+      @name = name
+      @body = body
+      @builtin = builtin
+    end
+
+    # Require 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 }
+    end
+
+    # Register a new plug-in
+    #
+    # @note You should use `Ego.plugin` in plug-in scripts, which sets a
+    #   plug-in name for you automatically.
+    #
+    # @param name [String] the plug-in name
+    # @param body the plug-in body
+    # @param builtin [Boolean] whether to register as a built-in plug-in
+    # @return [Plugin] the instantiated plug-in
+    def self.register(name, body, builtin: false)
+      @@plugins[name] = Plugin.new(name, body, builtin: builtin)
+    end
+
+    # Yield each plug-in body passing `obj` as a parameter and calling
+    # `obj#context=`.
+    #
+    # @param obj [Object] the object to decorate
+    # @return [Object] the decorated object
+    def self.decorate(obj)
+      @@plugins.each do |name, plugin|
+        if obj.respond_to?(:context)
+          obj.context = plugin
+        end
+        plugin.body.call(obj)
+      end
+
+      obj
+    end
+  end
+end

data/lib/ego/plugins/capabilities.rb

@@ -0,0 +1,17 @@
+Ego.plugin builtin: true do |robot|
+  robot.can 'list capabilities'
+
+  robot.on(
+    /^(show me|show|tell me|list)\s+(handlers|what you can do|what (?:you are|you're) able to do|what you do|what (?:queries )?you (?:can )?understand)$/i => 5,
+    /^what (?:can you|are you able to|do you) (?:do|handle|understand)\??$/i => 5,
+    /^help/i => 2,
+  ) do
+    say 'I can...'
+
+    @capabilities.each do |cap|
+      builtin = cap.plugin.builtin ? '*' : ''
+      plugin = sprintf('(%s%s)', cap.plugin.name, builtin).magenta
+      printf("- %s %s\n", cap.to_s, plugin)
+    end
+  end
+end

data/lib/ego/plugins/fallback.rb

@@ -0,0 +1,36 @@
+Ego.plugin builtin: true do |robot|
+  robot.can 'help you write extensions'
+
+  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
+
+    plugin_path = Ego::Filesystem.config("plugins/#{plugin_slug}.rb")
+    plugin_path.sub!(/^#{ENV['HOME']}/, '~')
+
+    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
+    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
+    end
+  end
+end

data/lib/ego/plugins/robot_io.rb

@@ -0,0 +1,16 @@
+Ego.plugin builtin: true do |robot|
+  robot.can 'output text to the terminal'
+
+  # Provide #say, #emote, #alert, and #debug
+  robot.extend(Ego::Printer)
+
+  # A verbose robot doesn't suppress #debug output
+  robot.provide :verbose? do
+    @options.verbose
+  end
+
+  robot.can 'repeat what you say'
+  robot.on(/^(?:say|echo)\s+(?<input>.+)/i) do |match|
+    say match[:input]
+  end
+end

data/lib/ego/plugins/social.rb

@@ -0,0 +1,19 @@
+Ego.plugin builtin: true do |robot|
+  robot.can 'socialize'
+
+  robot.on(/^((who|what) are you|what('?s| is) your name)/i) do
+    say ["I'm #{name}.", "This is #{robot.name}, a robot."].sample
+  end
+
+  robot.on(/^(hello|salve|ave|hi|hey|ciao|hej)/i => 3) do
+    say [
+      'Hello.',
+      'Salve tu.',
+      'Ave.',
+      'Hi.',
+      'Hey.',
+      'Ciao.',
+      'Hej.',
+    ].sample
+  end
+end

data/lib/ego/plugins/system.rb

@@ -0,0 +1,21 @@
+Ego.plugin builtin: true do |robot|
+  robot.can 'execute system commands'
+
+  robot.provide :system do |*args|
+    debug 'Running system with arguments %s.', args
+
+    unless Kernel.system(*args)
+      alert 'Sorry, there was a problem running %s.', args.first
+    end
+  end
+
+  robot.can 'tell you your login name'
+
+  robot.on(
+    /^what(?:'?s| is) my (?:user|login)? ?name/i => 5,
+    /^who am I(?: logged in as)?/i => 5,
+  ) do
+    say 'You are currently logged in as:'
+    system 'who'
+  end
+end

data/lib/ego/printer.rb

@@ -0,0 +1,95 @@
+require 'colorize'
+
+module Ego
+  # Utility methods for writing output with formatting.
+  module Printer
+    String.disable_colorization = !$stdout.isatty
+
+    # Write stylized message to `$stdout` indicating speech.
+    #
+    # @example
+    #   name = 'world'
+    #   robot.say 'Hello, %s.', name
+    #   # => "Hello, world."
+    #
+    # @param message [Object] message to write
+    # @param *replacements [Object, ...] `printf`-style replacements
+    # @return [nil]
+    def say(message, *replacements)
+      puts sprintf(message, *replacements).bold
+    end
+
+    # Write stylized message to `$stdout` indicating an emote.
+    #
+    # Plug-ins may use this method to indicating what the robot is doing.
+    #
+    # @example
+    #   robot.emote 'runs away'
+    #   # => "*runs away*"
+    #
+    # @param message [Object] message to write
+    # @return [nil]
+    def emote(message)
+      puts "*#{message}*".magenta
+    end
+
+    # Write stylized message to `$stderr` indicating an error or warning
+    # message.
+    #
+    # @example
+    #   name = 'world'
+    #   robot.alert 'Hello, %s.', name
+    #   # => "Hello, world."
+    #
+    # @param message [Object] message to write
+    # @param *replacements [Object, ...] `printf`-style replacements
+    # @return [nil]
+    def alert(message, *replacements)
+      errs sprintf(message, *replacements).light_red
+    end
+
+    # Write stylized message to `$stderr` indicating a debugging message
+    # 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."
+    #
+    # @param message [Object] message to write
+    # @param *replacements [Object, ...] `printf`-style replacements
+    # @return [nil]
+    def debug(message, *replacements)
+      errs sprintf(message, *replacements) if verbose?
+    end
+
+    # Whether to print debugging messages. Can be overridden by classes that
+    # include `Printer`.
+    #
+    # @return [false] should print debugging messages?
+    def verbose?; false; end
+
+    module_function
+
+    # Writes the given message(s) to `$stdout`, appending a newline if not
+    # already included.
+    #
+    # @param *message [Object, ...] message(s) to write
+    # @return [nil]
+    def puts(*message)
+      $stdout.puts(*message)
+    end
+
+    # Writes the given message(s) to `$stderr`, appending a newline if not
+    # already included.
+    #
+    # @param *message [Object, ...] message(s) to write
+    # @return [nil]
+    def errs(*message)
+      $stderr.puts(*message)
+    end
+  end
+end

data/lib/ego/robot.rb

@@ -1,24 +1,171 @@
+require_relative 'capability'
+require_relative 'handler'
+require_relative 'robot_error'
+require 'hooks'
+
 module Ego
+  # The robot instance provides a DSL for plug-ins to use to implement new
+  # functionality and also share that functionality with other plug-ins.
+  #
+  # Much built-in functionality of Ego is also implemented using the plug-in
+  # DSL.
+  #
+  # @see Ego.plugin
   class Robot
-    attr_reader :name, :options
+    include Hooks
+    include Hooks::InstanceHooks
+
+    attr_reader :name, :options, :capabilities
+    # Set/get currently executing plug-in
+    attr_accessor :context
+
+    alias_method :provide, :define_singleton_method
+
+    define_hooks :on_ready, :on_shutdown
+    define_hooks :before_handle_query, :after_handle_query, :on_unhandled_query
+    define_hooks :before_action, :after_action
 
-    def initialize(options, formatter)
+    # @param options [Options] the options to create a robot with
+    #
+    # @see Options
+    def initialize(options)
       @name = options.robot_name
       @options = options
-      @formatter = formatter
+      @context = nil
+      @capabilities = []
+      @handlers = []
     end
 
-    def respond(message, *replacements)
-      @formatter.robot_respond message, *replacements
+    # Run `on_ready` hook.
+    #
+    # Should be called after plug-ins are registered, before handling queries.
+    #
+    # @hook on_ready
+    #
+    # @return [self]
+    def ready
+      run_hook :on_ready
+      self
     end
 
-    def it(message)
-      @formatter.robot_action message
+    # Run `on_shutdown` hook.
+    #
+    # Should be called after all queries are handled, before program
+    # termination.
+    #
+    # @hook on_shutdown
+    #
+    # @return [void]
+    def shutdown
+      run_hook :on_shutdown
     end
 
-    def debug(message, *replacements)
-      return unless @options.verbose
-      @formatter.debug message, *replacements
+    # Adds a new capability, which documents functionality added by a plug-in.
+    #
+    # @example Add a capability to the robot instance
+    #   robot.can 'repeat what you say'
+    #
+    # @param desc [String] capability description
+    # @return [Array] all capabilities registered to the robot
+    #
+    # @see Capability
+    def can(desc)
+      unless @context
+        raise RobotError, 'Cannot add capability outside of plug-in context'
+      end
+      @capabilities << Capability.new(desc, @context)
+    end
+
+    # Register a new query handler.
+    #
+    # The robot will execute the given block (the "action") when the given
+    # pattern (the "condition") matches. Conditions are assigned priorities,
+    # which determined in what order conditions are checked against the query.
+    #
+    # @example Add a handler to the robot instance
+    #   robot.on(/^pattern/) do
+    #     # ...
+    #   end
+    #
+    # @example Add a handler with priority to the robot instance
+    #   robot.on(/^pattern/, 7) do
+    #     # ...
+    #   end
+    #
+    # @example Add multiple handlers for the same action
+    #   robot.on(
+    #     /pattern/ => 6,
+    #     /other pattern/ => 7,
+    #     /another/ => 3,
+    #   ) do
+    #     # ...
+    #   end
+    #
+    # @example Passing a lambda as a condition
+    #   robot.on(->(query) { query.length > 10 }) do
+    #     # ...
+    #   end
+    #
+    # @param condition [Proc, #match] the condition that triggers the supplied action
+    # @param priority [Integer] the handler priority (higher number = higher priority)
+    # @param action [Proc] the block to be executed when condition is met
+    # @return [void]
+    #
+    # @see Handler#initialize
+    def on(condition, priority = 5, &action)
+      unless action
+        raise RobotError, "Hook requires an action: robot.on #{condition.inspect}"
+      end
+
+      if condition.respond_to?(:each_pair)
+        # Condition is a hash of conditions and priorities
+        condition.each_pair { |c, p| on(c, p, &action) }
+      else
+        # Register a new handler with condition
+        @handlers << Handler.new(condition, action, priority)
+      end
+    end
+
+    # Run action with given parameters in the context of the robot instance.
+    #
+    # @hook before_action
+    # @hook after_action
+    #
+    # @param action [#call] the action
+    # @param params the action parameters
+    # @return result of the action
+    def run_action(action, params)
+      run_hook :before_action, action, params
+      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.
+    #
+    # @hook before_handle_query
+    # @hook after_handle_query
+    # @hook on_unhandled_query
+    #
+    # @param query [String] user query
+    # @return [false] if query is not handled
+    # @return result of the action
+    #
+    # @see Handler#handle
+    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)
+          run_hook :after_handle_query, query, handler
+          return result
+        end
+      end
+
+      run_hook :on_unhandled_query, query
+      false
     end
   end
 end