lita 1.1.2 → 2.0.0

data/lib/lita/adapter.rb

@@ -1,10 +1,18 @@
 module Lita
+  # Adapters are the glue between Lita's API and a chat service.
   class Adapter
+    # The instance of {Lita::Robot}.
+    # @return [Lita::Robot]
     attr_reader :robot
 
     class << self
+      # A list of configuration keys that are required for the adapter to boot.
+      # @return [Array]
       attr_reader :required_configs
 
+      # Defines configuration keys that are requried for the adapter to boot.
+      # @param keys [String, Symbol] The required keys.
+      # @return [void]
       def require_config(*keys)
         @required_configs ||= []
         @required_configs.concat(keys.flatten.map(&:to_sym))
@@ -13,11 +21,37 @@ module Lita
       alias_method :require_configs, :require_config
     end
 
+    # @param robot [Lita::Robot] The currently running robot.
     def initialize(robot)
       @robot = robot
       ensure_required_configs
     end
 
+    # @!method run
+    # The main loop. Should connect to the chat service, listen for incoming
+    # messages, create {Lita::Message} objects from them, and dispatch them to
+    # the robot by calling {Lita::Robot#receive}.
+    # @return [void]
+    # @abstract This should be implemented by the adapter.
+
+    # @!method send_messages(target, strings)
+    # Sends one or more messages to a user or room.
+    # @param target [Lita::Source] The user or room to send messages to.
+    # @param strings [Array<String>] An array of messages to send.
+    # @return [void]
+    # @abstract This should be implemented by the adapter.
+
+    # @!method set_topic(target, topic)
+    # Sets the topic for a room.
+    # @param target [Lita::Source] The room to change the topic for.
+    # @param topic [String] The new topic.
+    # @return [void]
+    # @abstract This should be implemented by the adapter.
+
+    # @!method shut_down
+    # Performs any clean up necessary when disconnecting from the chat service.
+    # @return [void]
+    # @abstract This should be implemented by the adapter.
     [:run, :send_messages, :set_topic, :shut_down].each do |method|
       define_method(method) do |*args|
         Lita.logger.warn("This adapter has not implemented ##{method}.")
@@ -26,6 +60,7 @@ module Lita
 
     private
 
+    # Logs a fatal message and aborts if a required config key is not set.
     def ensure_required_configs
       required_configs = self.class.required_configs
       return if required_configs.nil?

data/lib/lita/adapters/shell.rb

@@ -1,8 +1,12 @@
 module Lita
   module Adapters
+    # An adapter that runs Lita in a UNIX shell.
     class Shell < Adapter
+      # Creates a "Shell User" and then loops a prompt and input, passing the
+      # incoming messages to the robot.
+      # @return [void]
       def run
-        user = User.new(1, name: "Shell User")
+        user = User.create(1, name: "Shell User")
         source = Source.new(user)
         puts 'Type "exit" or "quit" to end the session.'
 
@@ -11,15 +15,22 @@ module Lita
           input = $stdin.gets.chomp.strip
           break if input == "exit" || input == "quit"
           message = Message.new(robot, input, source)
-          Thread.new { robot.receive(message) }
+          message.command! if Lita.config.adapter.private_chat
+          robot.receive(message)
         end
       end
 
+      # Outputs outgoing messages to the shell.
+      # @param target [Lita::Source] Unused, since there is only one user in the
+      #   shell environment.
+      # @param strings [Array<String>] An array of strings to output.
+      # @return [void]
       def send_messages(target, strings)
-        puts
         puts strings
       end
 
+      # Adds a blank line for a nice looking exit.
+      # @return [void]
       def shut_down
         puts
       end

data/lib/lita/authorization.rb

@@ -1,30 +1,54 @@
 module Lita
+  # Methods for querying and manipulating authorization groups.
   module Authorization
     class << self
+      # Adds a user to an authorization group.
+      # @param requesting_user [Lita::User] The user who sent the command.
+      # @param user [Lita::User] The user to add to the group.
+      # @param group [Symbol, String] The name of the group.
+      # @return [Symbol] :unauthorized if the requesting user is not authorized.
+      # @return [Boolean] true if the user was added. false if the user was
+      #   already in the group.
       def add_user_to_group(requesting_user, user, group)
         return :unauthorized unless user_is_admin?(requesting_user)
         redis.sadd(normalize_group(group), user.id)
       end
 
+      # Removes a user from an authorization group.
+      # @param requesting_user [Lita::User] The user who sent the command.
+      # @param user [Lita::User] The user to remove from the group.
+      # @param group [Symbol, String] The name of the group.
+      # @return [Symbol] :unauthorized if the requesting user is not authorized.
+      # @return [Boolean] true if the user was removed. false if the user was
+      #   not in the group.
       def remove_user_from_group(requesting_user, user, group)
         return :unauthorized unless user_is_admin?(requesting_user)
         redis.srem(normalize_group(group), user.id)
       end
 
+      # Checks if a user is in an authorization group.
+      # @param user [Lita::User] The user.
+      # @param group [Symbol, String] The name of the group.
+      # @return [Boolean] Whether or not the user is in the group.
       def user_in_group?(user, group)
         redis.sismember(normalize_group(group), user.id)
       end
 
+      # Checks if a user is an administrator.
+      # @param user [Lita::User] The user.
+      # @return [Boolean] Whether or not the user is an administrator.
       def user_is_admin?(user)
         Array(Lita.config.robot.admins).include?(user.id)
       end
 
       private
 
+      # Ensures that group names are stored consistently in Redis.
       def normalize_group(group)
         group.to_s.downcase.strip
       end
 
+      # A Redis::Namespace for authorization data.
       def redis
         @redis ||= Redis::Namespace.new("auth", redis: Lita.redis)
       end

data/lib/lita/cli.rb

@@ -1,6 +1,7 @@
 require "thor"
 
 module Lita
+  # The command line interface for Lita.
   class CLI < Thor
     include Thor::Actions
 

data/lib/lita/config.rb

@@ -1,41 +1,74 @@
 module Lita
+  # An object that stores various user settings that affect Lita's behavior.
   class Config < Hash
-    def self.default_config
-      new.tap do |c|
-        c.robot = new
-        c.robot.name = "Lita"
-        c.robot.adapter = :shell
-        c.robot.log_level = :info
-        c.robot.admins = nil
-        c.redis = new
-        c.adapter = new
-        c.handlers = new
+    class << self
+      # Initializes a new Config object with the default settings.
+      # @return [Lita::Config] The default configuration.
+      def default_config
+        config = new.tap do |c|
+          c.robot = new
+          c.robot.name = "Lita"
+          c.robot.adapter = :shell
+          c.robot.log_level = :info
+          c.robot.admins = nil
+          c.redis = new
+          c.http = new
+          c.http.port = 8080
+          c.http.debug = false
+          c.adapter = new
+          c.handlers = new
+        end
+        load_handler_configs(config)
+        config
       end
-    end
 
-    def self.load_user_config(config_path = nil)
-      config_path = "lita_config.rb" unless config_path
+      # Loads configuration from a user configuration file.
+      # @param config_path [String] The path to the configuration file.
+      # @return [void]
+      def load_user_config(config_path = nil)
+        config_path = "lita_config.rb" unless config_path
 
-      begin
-        load(config_path)
-      rescue Exception => e
-        Lita.logger.fatal <<-MSG
+        begin
+          load(config_path)
+        rescue Exception => e
+          Lita.logger.fatal <<-MSG
 Lita configuration file could not be processed. The exception was:
 #{e.message}
 #{e.backtrace.join("\n")}
 MSG
-        abort
-      end if File.exist?(config_path)
+          abort
+        end if File.exist?(config_path)
+      end
+
+      private
+
+      # Adds and populates a Config object to Lita.config.handlers for every
+      # registered handler that implements self.default_config.
+      def load_handler_configs(config)
+        Lita.handlers.each do |handler|
+          next unless handler.respond_to?(:default_config)
+          handler_config = config.handlers[handler.namespace] = new
+          handler.default_config(handler_config)
+        end
+      end
     end
 
+    # Sets a config key.
+    # @param key [Symbol, String] The key.
+    # @param value The value.
+    # @return The value.
     def []=(key, value)
       super(key.to_sym, value)
     end
 
+    # Get a config key.
+    # @param key [Symbol, String] The key.
+    # @return The value.
     def [](key)
       super(key.to_sym)
     end
 
+    # Allows keys to be read and written with struct-like syntax.
     def method_missing(name, *args)
       name_string = name.to_s
       if name_string.chomp!("=")

data/lib/lita/handler.rb

@@ -1,77 +1,141 @@
 module Lita
+  # Base class for objects that add new behavior to Lita.
   class Handler
     extend Forwardable
 
-    attr_reader :redis, :robot
-    private :redis
-
-    def_delegators :@message, :args, :command?, :scan, :user
-
-    class Route < Struct.new(:pattern, :method_name, :command, :required_groups)
+    # A Redis::Namespace scoped to the handler.
+    # @return [Redis::Namespace]
+    attr_reader :redis
+
+    # The running {Lita::Robot} instance.
+    # @return [Lita::Robot]
+    attr_reader :robot
+
+    # A Struct representing a chat route defined by a handler.
+    class Route < Struct.new(
+      :pattern,
+      :method_name,
+      :command,
+      :required_groups,
+      :help
+    )
       alias_method :command?, :command
     end
 
     class << self
-      def route(pattern, to: nil, command: false, restrict_to: nil)
+      # Creates a chat route.
+      # @param pattern [Regexp] A regular expression to match incoming messages
+      #   against.
+      # @param method [Symbol, String] The name of the method to trigger.
+      # @param command [Boolean] Whether or not the message must be directed at
+      #   the robot.
+      # @param restrict_to [Array<Symbol, String>, nil] A list of authorization
+      #   groups the user must be in to trigger the route.
+      # @param help [Hash] A map of example invocations to descriptions.
+      # @return [void]
+      def route(pattern, method, command: false, restrict_to: nil, help: {})
+        groups = restrict_to.nil? ? nil : Array(restrict_to)
+        routes << Route.new(pattern, method, command, groups, help)
+      end
+
+      # A list of chat routes defined by the handler.
+      # @return [Array<Lita::Handler::Route>]
+      def routes
         @routes ||= []
-        required_groups = restrict_to.nil? ? nil : Array(restrict_to)
-        @routes << Route.new(pattern, to, command, required_groups)
       end
 
+      # The main entry point for the handler at runtime. Checks if the message
+      # matches any of the routes and invokes the route's method if it does.
+      # Called by {Lita::Robot#receive}.
+      # @param robot [Lita::Robot] The currently running robot.
+      # @param message [Lita::Message] The incoming message.
+      # @return [void]
       def dispatch(robot, message)
-        instance = new(robot, message)
-
-        @routes.each do |route|
-          if route_applies?(route, instance)
-            instance.public_send(
-              route.method_name,
-              matches_for_route(route, instance)
-            )
+        routes.each do |route|
+          if route_applies?(route, message)
+            Lita.logger.debug <<-LOG.chomp
+Dispatching message to #{self}##{route.method_name}.
+LOG
+            new(robot).public_send(route.method_name, Response.new(
+              message,
+              matches: message.match(route.pattern)
+            ))
           end
-        end if defined?(@routes)
+        end
+      end
+
+      # Creates a new {Lita::HTTPRoute} which is used to define an HTTP route
+      # for the built-in web server.
+      # @see Lita::HTTPRoute
+      # @return [Lita::HTTPRoute] The new {Lita::HTTPRoute}.
+      def http
+        HTTPRoute.new(self)
+      end
+
+      # An array of all HTTP routes defined for the handler.
+      # @return [Array<Lita::HTTPRoute>] The array of routes.
+      def http_routes
+        @http_routes ||= []
+      end
+
+      # The namespace for the handler, used for its configuration object and
+      # Redis store. If the handler is an anonymous class, it must explicitly
+      # define +self.name+.
+      # @return [String] The handler's namespace.
+      # @raise [RuntimeError] If +self.name+ is not defined.
+      def namespace
+        if name
+          Util.underscore(name.split("::").last)
+        else
+          raise "Handlers that are anonymous classes must define self.name."
+        end
       end
 
       private
 
-      def route_applies?(route, instance)
+      # Determines whether or not an incoming messages should trigger a route.
+      def route_applies?(route, message)
         # Message must match the pattern
-        return unless route.pattern === instance.message_body
+        return unless route.pattern === message.body
 
         # Message must be a command if the route requires a command
-        return if route.command? && !instance.command?
+        return if route.command? && !message.command?
 
         # User must be in auth group if route is restricted
         return if route.required_groups && route.required_groups.none? do |group|
-          Authorization.user_in_group?(instance.user, group)
+          Authorization.user_in_group?(message.user, group)
         end
 
         true
       end
-
-      def matches_for_route(route, instance)
-        instance.scan(route.pattern)
-      end
     end
 
-    def initialize(robot, message)
+    # @param robot [Lita::Robot] The currently running robot.
+    def initialize(robot)
       @robot = robot
-      @message = message
       @redis = Redis::Namespace.new(redis_namespace, redis: Lita.redis)
     end
 
-    def reply(*strings)
-      @robot.send_messages(@message.source, *strings)
-    end
-
-    def message_body
-      @message.body
+    # Creates a new +Faraday::Connection+ for making HTTP requests.
+    # @param options [Hash] A set of options passed on to Faraday.
+    # @yield [builder] A Faraday builder object for adding middleware.
+    # @return [Faraday::Connection] The new connection object.
+    def http(options = {}, &block)
+      options = default_faraday_options.merge(options)
+      Faraday::Connection.new(nil, options, &block)
     end
 
     private
 
+    # Default options for new Faraday connections. Sets the user agent to the
+    # current version of Lita.
+    def default_faraday_options
+      { headers: { "User-Agent" => "Lita v#{VERSION}" } }
+    end
+
+    # The handler's namespace for Redis.
     def redis_namespace
-      name = self.class.name.split("::").last.downcase
-      "handlers:#{name}"
+      "handlers:#{self.class.namespace}"
     end
   end
 end

data/lib/lita/handlers/authorization.rb

@@ -1,51 +1,60 @@
 module Lita
   module Handlers
+    # Provides a chat interface for administering authorization groups.
     class Authorization < Handler
-      route(/^auth\s+add/, to: :add, command: true)
-      route(/^auth\s+remove/, to: :remove, command: true)
+      route(/^auth\s+add/, :add, command: true, help: {
+        "auth add USER GROUP" => "Add USER to authorization group GROUP. Requires admin privileges."
+      })
+      route(/^auth\s+remove/, :remove, command: true, help: {
+        "auth remove USER GROUP" => "Remove USER from authorization group GROUP. Requires admin privileges."
+      })
 
-      def self.help
-        robot_name = Lita.config.robot.name
+      # Adds a user to an authorization group.
+      # @param response [Lita::Response] The response object.
+      # @return [void]
+      def add(response)
+        return unless valid_message?(response)
 
-        {
-          "#{robot_name}: auth add USER GROUP" => "Add USER to authorization group GROUP. Requires admin privileges.",
-          "#{robot_name}: auth remove USER GROUP" => "Remove USER from authorization group GROUP. Requires admin privileges."
-        }
-      end
-
-      def add(matches)
-        return unless valid_message?
-
-        case Lita::Authorization.add_user_to_group(user, @user, @group)
+        case Lita::Authorization.add_user_to_group(response.user, @user, @group)
         when :unauthorized
-          reply "Only administrators can add users to groups."
+          response.reply "Only administrators can add users to groups."
         when true
-          reply "#{@user.name} was added to #{@group}."
+          response.reply "#{@user.name} was added to #{@group}."
         else
-          reply "#{@user.name} was already in #{@group}."
+          response.reply "#{@user.name} was already in #{@group}."
         end
       end
 
-      def remove(matches)
-        return unless valid_message?
+      # Removes a user from an authorization group.
+      # @param response [Lita::Response] The response object.
+      # @return [void]
+      def remove(response)
+        return unless valid_message?(response)
 
-        case Lita::Authorization.remove_user_from_group(user, @user, @group)
+        case Lita::Authorization.remove_user_from_group(
+          response.user,
+          @user,
+          @group
+        )
         when :unauthorized
-          reply "Only administrators can remove users from groups."
+          response.reply "Only administrators can remove users from groups."
         when true
-          reply "#{@user.name} was removed from #{@group}."
+          response.reply "#{@user.name} was removed from #{@group}."
         else
-          reply "#{@user.name} was not in #{@group}."
+          response.reply "#{@user.name} was not in #{@group}."
         end
       end
 
       private
 
-      def valid_message?
-        command, identifier, @group = args
+      # Validates that incoming messages have the right format and a valid user.
+      # Also assigns the user and group to instance variables for the main
+      # methods to use later.
+      def valid_message?(response)
+        command, identifier, @group = response.args
 
         unless identifier && @group
-          reply "Format: #{robot.name} auth add USER GROUP"
+          response.reply "Format: #{robot.name} auth add USER GROUP"
           return
         end
 
@@ -53,7 +62,9 @@ module Lita
         @user = User.find_by_name(identifier) unless @user
 
         unless @user
-          reply %{No user was found with the identifier "#{identifier}".}
+          response.reply <<-REPLY.chomp
+No user was found with the identifier "#{identifier}".
+REPLY
           return
         end