ego 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 35aa43cdd26bed25c5009f42b1150c92a78df513
-  data.tar.gz: 92ce09a2e64a13f14860768d7f26e074cbe6f4d4
+  metadata.gz: 2250f057ded898c375e1c7007080abbddb3ddbcb
+  data.tar.gz: 05c37f206fa38f7ba8a6879d4519dba59dfd74c6
 SHA512:
-  metadata.gz: 77c069a99cc06cb70d5427c8d286321f54d27106a9c40fc2e85937ba414c8a665bbc9d233799f4d736953f2646026138b2db547162e4f685ecda1d75c069be7d
-  data.tar.gz: 9f79212f6efa0249ec0c242ff470415f85f5675958f81dd74e440b7acf7d5c525d21733b2b19711aea2d70c81380d58ed97673b7361110d9df3fe17be698acb4
+  metadata.gz: 3e3b434aece55fb5a6f7b0c1ce850cc2b9f41cec5b092bd59e28773ff03c16c92ae9445828981eb147129f8d6c17c3ffccd1834448396325e04661dae2bde0e3
+  data.tar.gz: 1c3d3feb0fb8d531a931c5522ce2803e32d6a82d5875bed4b3b4d12b5c632c083b1eb3657439cedb5b88b03a218ef3582c4b9911df1d6b376548684b15353f9d

data/README.md

@@ -1,5 +1,7 @@
 # Ego
 
+[![Gem Version](https://badge.fury.io/rb/ego.svg)](https://badge.fury.io/rb/ego)
+
 Ego is a personal command-line assistant that provides a flexible, natural
 language interface (sort of) for interacting with other programs. Think of
 it as a single-user IRC bot that can be extended with handlers for various
@@ -7,15 +9,106 @@ natural-language queries.
 
 ## Installation
 
+Ego requires Ruby. If you already have Ruby installed, run:
+
     $ gem install ego
 
 ## Usage
 
+Ego responds to natural-language queries at the command-line:
+
     $ ego what can you do?
 
+If you want to interact with ego as a REPL, try:
+
+    $ ego --shell
+
+## 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",
+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:
+
+```ruby
+Ego::Handler.register do |handler|
+  handler.description = 'greet you'
+
+  handler.listen /^(hello|hi|hey)/i, priority: 3
+
+  handler.run do |robot|
+    robot.respond [
+      'Hello.',
+      'Hi.',
+      'Ciao.',
+    ].sample
+  end
+end
+```
+
+    $ ego hello
+    > Hi.
+
+Let's break that down:
+
+```ruby
+handler.description = 'greet you'
+```
+
+The description is for your own reference, and answers the question "What can
+this handler do?"
+
+```ruby
+handler.listen /^(hello|hi|hey)/i, priority: 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.
+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.
+
+```ruby
+handler.run do |robot|
+  # ...
+end
+```
+
+This is the part that gets run when your handler 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:
+
+```ruby
+Ego::Handler.register do |handler|
+  handler.description = 'repeat what you say'
+
+  handler.listen /^say (?<input>.+)/i
+
+  handler.run do |robot, params|
+    robot.respond params[:input]
+  end
+end
+```
+
+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
+execute any Ruby scripts in this directory indiscriminately.
+
 ## License
 
-Copyright (C) 2016  Noah Frederick
+Copyright (C) 2016-2017  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,6 +23,8 @@ 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.add_development_dependency "bundler", "~> 1.6"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "rspec", "~> 3.4"

data/lib/ego.rb

@@ -1,5 +1,5 @@
-require "ego/version"
-
-module Ego
-  # Your code goes here...
-end
+require_relative 'ego/version'
+require_relative 'ego/options'
+require_relative 'ego/filesystem'
+require_relative 'ego/robot'
+require_relative 'ego/handler'

data/lib/ego/handler/default.rb

@@ -6,10 +6,26 @@ Ego::Handler.register do |handler|
   handler.run do |robot, params|
     robot.respond %Q{I don't understand "#{params[0]}".}
 
+    handler_slug = params[0]
+      .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+      .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+      .tr('\'', '')
+      .gsub(/\W+/, '_')
+      .gsub(/__+/, '_')
+      .downcase
+
     STDERR.puts <<-EOF
-Perhaps add a handler to #{Ego::Filesystem.config 'handler/{}.rb'}:
+Perhaps add a handler to #{Ego::Filesystem.config "handler/#{handler_slug}.rb"}:
+
+Ego::Handler.register do |handler|
+  handler.description = 'do something'
+
+  handler.listen /^#{params[0]}$/
 
-...
+  handler.run do |robot, params|
+    # ...
+  end
+end
     EOF
   end
 end

data/lib/ego/handler/echo.rb

@@ -4,7 +4,6 @@ Ego::Handler.register do |handler|
   handler.listen /^(?:say|echo)\s+(?<input>.+)/i, priority: 6
 
   handler.run do |robot, params|
-    robot.debug params
-    # robot.respond params[:input]
+    robot.respond params[:input]
   end
 end

data/lib/ego/handler/handlers.rb

@@ -5,6 +5,7 @@ Ego::Handler.register do |handler|
 
   handler.listen /^(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
   handler.listen /^what (?:can you|are you able to|do you) (?:do|handle|understand)\??$/i
+  handler.listen /^help/i, priority: 2
 
   handler.run do |robot|
     robot.respond 'I know how to...'

data/lib/ego/listener.rb

@@ -1,4 +1,5 @@
 module Ego
+  # Listeners map user queries to handlers.
   class Listener
     include Comparable
 
@@ -16,7 +17,7 @@ module Ego
     end
 
     def match query
-      return false unless matches = @pattern.match(query)
+      return false unless (matches = @pattern.match(query))
 
       @parser.call matches
     end

data/lib/ego/options.rb

@@ -24,6 +24,10 @@ module Ego
         @robot_name = opts.program_name.capitalize
         opts.banner = "Usage: #{opts.program_name} [ options ] query..."
 
+        opts.on("-s", "--shell", "Start in REPL-mode") do
+          @mode = :shell
+        end
+
         opts.on("-v", "--version", "Print version number") do
           @mode = :version
         end

data/lib/ego/robot.rb

@@ -10,26 +10,15 @@ module Ego
 
     def respond message
       @formatter.robot_respond message
-      true
     end
 
     def it message
       @formatter.robot_action message
-      true
     end
 
     def debug message
       return unless @options.verbose
       @formatter.debug message
-      true
-    end
-
-    def stop
-      true
-    end
-
-    def continue
-      false
     end
   end
 end

data/lib/ego/runner.rb

@@ -1,13 +1,12 @@
-require_relative 'version'
-require_relative 'options'
-require_relative 'filesystem'
-require_relative 'robot'
-require_relative 'handler'
+require_relative '../ego'
 
 module Ego
   # The Ego::Runner class, given an array of arguments, initializes the
   # required objects and executes the request.
   class Runner
+    PROMPT = 'ego, '.green.freeze
+    QUIT = /^q(uit)?|exit|(good)?bye$/.freeze
+
     # Takes an array of arguments and parses them into options:
     #
     #   runner = Ego::Runner.new(ARGV)
@@ -31,12 +30,44 @@ module Ego
         exit(-1) if @options.usage_error
       when :version
         @formatter.puts "ego v#{Ego::VERSION}"
+      when :shell
+        init_robot
+        start_repl
       else
-        robot = Ego::Robot.new(@options, @formatter)
-        Ego::Handler.load Ego::Filesystem.user_handlers
-        Ego::Handler.load Ego::Filesystem.builtin_handlers
-        Ego::Handler.dispatch robot, @options.query
+        init_robot
+        handle_query @options.query
+      end
+    end
+
+    protected
+
+    def init_robot
+      @robot = Ego::Robot.new(@options, @formatter)
+      Ego::Handler.load Ego::Filesystem.user_handlers
+      Ego::Handler.load Ego::Filesystem.builtin_handlers
+    end
+
+    def handle_query(query)
+      Ego::Handler.dispatch @robot, query
+    end
+
+    def prompt
+      Readline.readline(PROMPT, true)
+    end
+
+    def start_repl
+      require 'readline'
+
+      # Store the state of the terminal
+      stty_save = `stty -g`.chomp
+
+      loop do
+        query = prompt
+        break if query.nil? || query.strip =~ QUIT
+        handle_query query.strip
       end
+    rescue Interrupt => e
+      system('stty', stty_save) # Restore state
     end
   end
 end

data/lib/ego/version.rb

@@ -1,3 +1,3 @@
 module Ego
-  VERSION = "0.1.0"
+  VERSION = '0.2.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ego
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Noah Frederick
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-03-12 00:00:00.000000000 Z
+date: 2017-08-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -128,9 +128,9 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - "~>"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -138,7 +138,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.6.8
 signing_key: 
 specification_version: 4
 summary: An extensible personal command-line assistant