ego 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: db83be1f5d3be9a990e8990b6f10b3fabd634939
-  data.tar.gz: 2dce79d2d96a4bf49c7bcdd1c5605f79ba31df97
+  metadata.gz: 7a1b7a652d2e75a9e5a22d05a9627f1b5f63b94d
+  data.tar.gz: 5e7aa5063ddf5f986b341a9bb4ac6f9f165d3358
 SHA512:
-  metadata.gz: 29423bd9409d40de8a4fe31e2e1893e3ffe7742b82f309cbc21df6b80f74082996d8ec62d5a69c67de6a07c50db8ed5dff4467187ca71ffedc74d2cb89ca534e
-  data.tar.gz: 3741072a3a11271babcd8168db8cf49592f24cb3e415870f0bdf75e190132301fe7956caa3b1c3fcfec47fc36610cb566cf756ac6ee55c3129c294d42ab0e012
+  metadata.gz: 0711a3f6ddb2ef92913409ffb2e2a66a55b6dbec57f0fcf9057ab598803175254b26a40785996aab3d6ece9eae279f03fa55417167f057a0531d9d465e932116
+  data.tar.gz: b816f63c6fadea1d33066b65f8ca6067c2af1409e01e323353f57a58f99c3d28775dfc6d6d174c14cca138ab72fc63727b29709c1a93a578f62184d4ab1e0fa3

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.0
+  - 2.4

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown --name-tag hook:"Runs Hooks" - LICENSE.txt

data/README.md

@@ -26,19 +26,18 @@ If you want to interact with ego as a REPL, try:
 ## Extending
 
 Ego does very few things out of the box, but it's designed to be extensible!
-You can personalize ego and teach it to do new things by defining "handlers",
+You can personalize ego and teach it to do new things by defining plug-ins,
 which are small scripts that tell ego what queries to listen for and how to
-respond to them. Here's what a handler looks like that responds to a query
-beginning with "hello...", "hi...", or "hey..." with its own random greeting:
+respond to them and can even add entirely new features. Here's what a plug-in
+looks like that responds to a query beginning with "hello...", "hi...", or
+"hey..." with its own random greeting:
 
 ```ruby
-Ego::Handler.register do |handler|
-  handler.description = 'greet you'
+Ego.plugin do |robot|
+  robot.can 'greet you'
 
-  handler.listen /^(hello|hi|hey)/i, priority: 3
-
-  handler.run do |robot|
-    robot.respond [
+  robot.on /^(hello|hi|hey)/i, 3 do
+    say [
       'Hello.',
       'Hi.',
       'Ciao.',
@@ -53,44 +52,45 @@ end
 Let's break that down:
 
 ```ruby
-handler.description = 'greet you'
+robot.can 'greet you'
 ```
 
-The description is for your own reference, and answers the question "What can
-this handler do?"
+This adds a new "capability", which serves as documentation for the user and
+answers the question "What can this plug-in do?"
 
 ```ruby
-handler.listen /^(hello|hi|hey)/i, priority: 3
+robot.on /^(hello|hi|hey)/i, 3 ...
 ```
 
-This is the listener, which specifies what queries should invoke the handler.
-The first argument is a regular expression to match the query against.
+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 listeners match
-your query, you can optionally specify a `:priority` (higher number = higher
-priority). One handler can have as many listeners as you want, even ones with
-different priorities.
+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.
 
 ```ruby
-handler.run do |robot|
-  # ...
+... do
+  say [
+    'Hello.',
+    'Hi.',
+    'Ciao.',
+  ].sample
 end
 ```
 
-This is the part that gets run when your handler matches the query. From here
+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` is made available to you to respond to the user. Usually, you'll want
-to make use of part of the query in your handler. You can access named match
-groups through the optional `params` parameter:
+`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:
 
 ```ruby
-Ego::Handler.register do |handler|
-  handler.description = 'repeat what you say'
-
-  handler.listen /^say (?<input>.+)/i
+Ego.plugin do |robot|
+  robot.can 'repeat what you say'
 
-  handler.run do |robot, params|
-    robot.respond params[:input]
+  robot.on /^say (?<input>.+)/i do |params|
+    say params[:input]
   end
 end
 ```
@@ -100,12 +100,17 @@ Try it out (this one is already included):
     $ ego say something
     > something
 
-Ego looks for user-defined handlers in `$XDG_CONFIG_HOME/ego/handlers/`
-(that's `~/.config/ego/handlers/` by default), and registers them
-automatically at runtime. Each handler goes in it's own file with an `.rb`
-extension (e.g., `~/.config/ego/handlers/my_handler.rb`). Be careful—ego will
+Ego looks for user-defined plug-ins in `$XDG_CONFIG_HOME/ego/plugins/`
+(that's `~/.config/ego/plugins/` by default), and registers them
+automatically at runtime. Each plug-in goes in it's own file with an `.rb`
+extension (e.g., `~/.config/ego/plugins/my_plugin.rb`). Be careful—ego will
 execute any Ruby scripts in this directory indiscriminately.
 
+### See Also
+
+- [API documentation](http://www.rubydoc.info/gems/ego)
+- [Examples in the wiki](https://github.com/noahfrederick/ego/wiki)
+
 ## License
 
 Copyright (C) 2016-2017  Noah Frederick

data/ego.gemspec

@@ -31,4 +31,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "guard-rspec"
 
   spec.add_runtime_dependency "colorize", "~> 0.7"
+  spec.add_runtime_dependency "hooks", "~> 0.4"
 end

data/lib/ego.rb

@@ -1,5 +1,42 @@
-require_relative 'ego/version'
-require_relative 'ego/options'
 require_relative 'ego/filesystem'
 require_relative 'ego/robot'
-require_relative 'ego/handler'
+require_relative 'ego/plugin'
+require_relative 'ego/printer'
+require_relative 'ego/version'
+
+module Ego
+  # Public interface for defining a plug-in.
+  #
+  # Ego looks for user-defined plug-ins in `$XDG_CONFIG_HOME/ego/plugins/`
+  # (that's `~/.config/ego/plugins/` by default), and registers them
+  # automatically at runtime. Each plug-in goes in it's own file with an `.rb`
+  # extension (e.g., `~/.config/ego/plugins/my_plugin.rb`).
+  #
+  # Be careful—ego will execute any Ruby scripts in this directory
+  # indiscriminately.
+  #
+  # @example Create and register a new plug-in
+  #   # ~/.config/ego/plugins/echo.rb
+  #   Ego.plugin do |robot|
+  #     robot.can 'repeat what you say'
+  #
+  #     robot.on /^say (?<input>.+)/i do |params|
+  #       say params[: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
+
+    Plugin.register(name, body, builtin: builtin)
+  end
+end

data/lib/ego/capability.rb

@@ -0,0 +1,30 @@
+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.
+  #
+  # @example Add a capability to the robot instance
+  #   Ego.plugin do |robot|
+  #     robot.can 'repeat what you say'
+  #     # ...
+  #   end
+  #
+  # @see Robot#can
+  class Capability
+    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)
+      @desc = desc
+      @plugin = plugin
+    end
+
+    # @return [String] the capability description
+    def to_s
+      @desc
+    end
+  end
+end

data/lib/ego/filesystem.rb

@@ -1,31 +1,60 @@
-module Ego::Filesystem
-  HANDLER_GLOB = 'handler/*.rb'
-
-  BASENAME = 'ego'
-
-  XDG_CACHE_HOME = ENV['XDG_CACHE_HOME'] || File.expand_path('~/.cache')
-  XDG_CONFIG_HOME = ENV['XDG_CONFIG_HOME'] || File.expand_path('~/.config')
-  XDG_DATA_HOME = ENV['XDG_DATA_HOME'] || File.expand_path('~/.local/share')
-
-  module_function
-
-  def cache(path = '')
-    File.join(XDG_CACHE_HOME, BASENAME, path)
-  end
-
-  def config(path = '')
-    File.join(XDG_CONFIG_HOME, BASENAME, path)
-  end
-
-  def data(path = '')
-    File.join(XDG_DATA_HOME, BASENAME, path)
-  end
-
-  def builtin_handlers
-    Dir[File.expand_path(HANDLER_GLOB, __dir__)]
-  end
-
-  def user_handlers
-    Dir[File.expand_path(HANDLER_GLOB, config)]
+module Ego
+  # Provides utility methods for getting configuration, data, and cache paths.
+  module Filesystem
+    # Glob pattern for matching plug-in files
+    PLUGIN_GLOB = 'plugins/*.rb'
+
+    # XDG subdirectoy name
+    BASENAME = 'ego'
+
+    # Value of `$XDG_CACHE_HOME` or fallback if not set
+    XDG_CACHE_HOME = ENV['XDG_CACHE_HOME'] || File.expand_path('~/.cache')
+    # Value of `$XDG_CONFIG_HOME` or fallback if not set
+    XDG_CONFIG_HOME = ENV['XDG_CONFIG_HOME'] || File.expand_path('~/.config')
+    # Value of `$XDG_DATA_HOME` or fallback if not set
+    XDG_DATA_HOME = ENV['XDG_DATA_HOME'] || File.expand_path('~/.local/share')
+
+    module_function
+
+    # @param path [String] path to append
+    # @return [String] the path to cache directory with `path` appended
+    #
+    # @see config
+    # @see data
+    def cache(path = '')
+      File.join(XDG_CACHE_HOME, BASENAME, path)
+    end
+
+    # @param path [String] path to append
+    # @return [String] the path to config directory with `path` appended
+    #
+    # @see cache
+    # @see data
+    def config(path = '')
+      File.join(XDG_CONFIG_HOME, BASENAME, path)
+    end
+
+    # @param path [String] path to append
+    # @return [String] the path to data directory with `path` appended
+    #
+    # @see cache
+    # @see config
+    def data(path = '')
+      File.join(XDG_DATA_HOME, BASENAME, path)
+    end
+
+    # @return [Array] all built-in plug-in paths
+    #
+    # @see user_plugins
+    def builtin_plugins
+      Dir[File.expand_path(PLUGIN_GLOB, __dir__)]
+    end
+
+    # @return [Array] all user plug-in paths
+    #
+    # @see builtin_plugins
+    def user_plugins
+      Dir[File.expand_path(PLUGIN_GLOB, config)]
+    end
   end
 end

data/lib/ego/handler.rb

@@ -1,76 +1,79 @@
-require_relative 'listener'
-require_relative 'formatter'
+require_relative 'robot_error'
 
 module Ego
+  # Handlers map user queries to actions.
+  #
+  # @note Handlers should be registered by plug-ins using the `robot#on`
+  #   method.
+  #
+  # @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
+  #
+  # @see Robot#on
   class Handler
-    @@handlers = {}
-    @@listeners = []
+    include Comparable
 
-    attr_reader :name
-    attr_accessor :description
+    attr_reader :condition, :action, :priority
 
-    def initialize(name)
-      @name = name
+    # @param condition [Proc, #match] the condition that triggers the supplied action
+    # @param action [Proc] the block to be executed when condition is met
+    # @param priority [Integer] the handler priority (higher number = higher priority)
+    def initialize(condition, action, priority = 5)
+      @condition = normalize(condition)
+      @action = action
+      @priority = priority
     end
 
-    def to_s
-      "#{@description}"
+    # Compare `priority` with `other.priority`.
+    #
+    # @param other [Handler] the handler to compare with
+    def <=>(other)
+      @priority <=> other.priority
     end
 
-    def listen(pattern, priority: 5, &parser)
-      unless block_given?
-        parser = Proc.new { |matches| matches }
-      end
-      @@listeners << Ego::Listener.new(pattern, priority, parser, @name)
-    end
-
-    def run(robot = nil, params = nil, &action)
-      if block_given?
-        @action = action
-      end
-
-      if robot.nil?
-        return
-      elsif @action.arity == 1
-        @action.call(robot)
-      else
-        @action.call(robot, params)
-      end
-    end
-
-    def self.register(name: nil)
-      if name.nil?
-        handler_path = caller_locations(1, 1)[0].absolute_path
-        name = File.basename(handler_path, '.*')
-      end
-
-      handler = Ego::Handler.new(name)
-      yield handler
-
-      @@handlers[handler.name] = handler
-    end
-
-    def self.has(handler_name)
-      @@handlers.has_key? handler_name
+    # Match the given query against the condition.
+    #
+    # @param query [String] the query to match the condition against
+    # @return [false] if condition doesn't match
+    # @return the return value of condition
+    def handle(query)
+      @condition.call(query) || false
     end
 
-    def self.load(handler_names)
-      handler_names.each do |path|
-        handler = File.basename(path, '.*')
-        require path unless has(handler)
-      end
-    end
+    protected
 
-    def self.dispatch(robot, query)
-      @@listeners.sort.reverse_each do |listener|
-        if params = listener.match(query)
-          return @@handlers[listener.handler].run(robot, params)
-        end
+    # Normalize the condition to a callable object.
+    #
+    # @param condition [Proc, #match] the condition that triggers the supplied action
+    def normalize(condition)
+      if condition.respond_to?(:match)
+        # Must assign regexp to avoid recursion in lambda
+        regexp = condition
+        condition = ->(query) { regexp.match(query) }
       end
-    end
 
-    def self.handlers
-      @@handlers
+      condition
     end
   end
 end