lita 3.3.1 → 4.0.0.rc1

data/lib/lita/builder.rb

@@ -0,0 +1,38 @@
+module Lita
+  # Constructs a Lita plugin from a block.
+  # @since 4.0.0
+  # @api private
+  class Builder
+    # @param namespace [String, Symbol] The Redis namespace to use for the plugin.
+    # @yield The class body of the plugin.
+    def initialize(namespace, &block)
+      @namespace = namespace.to_s
+      @block = block
+    end
+
+    # Constructs an {Lita::Adapter} from the provided block.
+    # @return [Lita::Adapter]
+    def build_adapter
+      adapter = create_plugin(Adapter)
+      adapter.class_exec(&@block)
+      adapter
+    end
+
+    # Constructs a {Lita::Handler} from the provided block.
+    # @return [Lita::Handler]
+    def build_handler
+      handler = create_plugin(Handler)
+      handler.class_exec(&@block)
+      handler
+    end
+
+    private
+
+    # Creates a class of the relevant plugin type and sets its namespace.
+    def create_plugin(plugin_type)
+      plugin = Class.new(plugin_type)
+      plugin.namespace(@namespace)
+      plugin
+    end
+  end
+end

data/lib/lita/callback.rb

@@ -0,0 +1,37 @@
+module Lita
+  # Represents the action that is taken when a route or event is triggered. It
+  # can be a block or the name of a method on object.
+  # @since 4.0.0
+  # @api private
+  class Callback
+    # A block that should be used as the callback.
+    attr_reader :block
+
+    # The name of the method in the plugin that should be called as the callback.
+    attr_reader :method_name
+
+    # @overload initialize(method_name)
+    #   @param method_name [String, Symbol] The name of the instance method that serves as the
+    #     callback.
+    # @overload initialize(callable)
+    #   @param callable [Proc] A callable object to use as the callback.
+    def initialize(method_name_or_callable)
+      if method_name_or_callable.respond_to?(:call)
+        @block = method_name_or_callable
+      else
+        @method_name = method_name_or_callable
+      end
+    end
+
+    # Invokes the callback.
+    def call(host, *args)
+      if block
+        host.instance_exec(*args, &block)
+      else
+        host.public_send(method_name, *args)
+      end
+
+      true
+    end
+  end
+end

data/lib/lita/cli.rb

@@ -65,6 +65,8 @@ module Lita
       end
 
       if options[:daemonize]
+        say I18n.t("lita.cli.daemon_deprecated"), :red
+
         Daemon.new(
           options[:pid_file],
           options[:log_file],

data/lib/lita/config.rb

@@ -1,5 +1,6 @@
 module Lita
   # An object that stores various user settings that affect Lita's behavior.
+  # @deprecated Will be removed in Lita 5.0. Use {Lita::Configuration} instead.
   class Config < Hash
     class << self
       # Initializes a new Config object with the default settings.
@@ -15,24 +16,6 @@ module Lita
         end
       end
 
-      # 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 I18n.t(
-            "lita.config.exception",
-            message: e.message,
-            backtrace: e.backtrace.join("\n")
-          )
-          abort
-        end if File.exist?(config_path)
-      end
-
       private
 
       # Adds and populates a Config object to Lita.config.handlers for every

data/lib/lita/configurable.rb

@@ -0,0 +1,29 @@
+module Lita
+  # Mixin to add the ability for a plugin to define configuration.
+  # @since 4.0.0
+  # @api private
+  module Configurable
+    # The plugins's {Configuration} object.
+    # @return [Lita::Configuration] The configuration object.
+    # @since 4.0.0
+    attr_accessor :configuration
+
+    # Sets a configuration attribute on the plugin.
+    # @return [void]
+    # @since 4.0.0
+    # @see Lita::Configuration#config
+    def config(*args, **kwargs)
+      if block_given?
+        configuration.config(*args, **kwargs, &proc)
+      else
+        configuration.config(*args, **kwargs)
+      end
+    end
+
+    # Initializes the configuration object for any inheriting classes.
+    def inherited(klass)
+      super
+      klass.configuration = Configuration.new
+    end
+  end
+end

data/lib/lita/configuration.rb

@@ -0,0 +1,179 @@
+module Lita
+  # An object that stores various settings that affect Lita's behavior.
+  # @since 4.0.0
+  class Configuration
+    # An array of any nested configuration objects.
+    # @return [Array<Lita::Configuration>] The array of child configuration objects.
+    attr_reader :children
+
+    # An array of valid types for the attribute.
+    # @return [Array<Object>] The array of valid types.
+    attr_reader :types
+
+    # A block used to validate the attribute.
+    # @return [Proc] The validation block.
+    attr_reader :validator
+
+    # The name of the configuration attribute.
+    # @return [String, Symbol] The attribute's name.
+    attr_accessor :name
+
+    # The value of the configuration attribute.
+    # @return [Object] The attribute's value.
+    attr_accessor :value
+
+    # A boolean indicating whether or not the attribute must be set.
+    # @return [Boolean] Whether or not the attribute is required.
+    attr_accessor :required
+    alias_method :required?, :required
+
+    class << self
+      # Deeply freezes a configuration object so that it can no longer be modified.
+      # @param config [Lita::Configuration] The configuration object to freeze.
+      # @return [void]
+      def freeze_config(config)
+        IceNine.deep_freeze!(config)
+      end
+
+      # 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 I18n.t(
+            "lita.config.exception",
+            message: e.message,
+            backtrace: e.backtrace.join("\n")
+          )
+          abort
+        end if File.exist?(config_path)
+      end
+    end
+
+    def initialize
+      @children = []
+      @name = :root
+    end
+
+    # Returns a boolean indicating whether or not the attribute has any child attributes.
+    # @return [Boolean] Whether or not the attribute has any child attributes.
+    def children?
+      !children.empty?
+    end
+
+    # Merges two configuration objects by making one an attribute on the other.
+    # @param name [String, Symbol] The name of the new attribute.
+    # @param attribute [Lita::Configuration] The configuration object that should be its value.
+    # @return [void]
+    def combine(name, attribute)
+      attribute.name = name
+
+      children << attribute
+    end
+
+    # Declares a configuration attribute.
+    # @param name [String, Symbol] The attribute's name.
+    # @param types [Object, Array<Object>] Optional: One or more types that the attribute's value
+    #   must be.
+    # @param type [Object, Array<Object>] Optional: One or more types that the attribute's value
+    #   must be.
+    # @param required [Boolean] Whether or not this attribute must be set. If required, and Lita
+    #   is run without it set, a {Lita::ValidationError} will be raised.
+    # @param default [Object] An optional default value for the attribute.
+    # @yield A block to be evaluated in the context of the new attribute. Used for
+    #   defining nested configuration attributes and validators.
+    # @return [void]
+    def config(name, types: nil, type: nil, required: false, default: nil)
+      attribute = self.class.new
+      attribute.name = name
+      attribute.types = types || type
+      attribute.required = required
+      attribute.value = default
+      attribute.instance_exec(&proc) if block_given?
+
+      children << attribute
+    end
+
+    # Extracts the finalized configuration object as it will be interacted with by the user.
+    # @param object [Object] The bare object that will be extended to create the final form.
+    # @return [Object] A bare object with only the methods that were declared via the
+    #   {Lita::Configuration} DSL.
+    def finalize(object = Object.new)
+      container = if children.empty?
+        finalize_simple(object)
+      else
+        finalize_nested(object)
+      end
+
+      container.public_send(name)
+    end
+
+    # Sets the valid types for the configuration attribute.
+    # @param types [Object, Array<Object>] One or more valid types.
+    # @return [void]
+    def types=(types)
+      @types = Array(types) if types
+    end
+
+    # Declares a block to be used to validate the value of an attribute whenever it's set.
+    # Validation blocks should return any object to indicate an error, or +nil+/+false+ if
+    # validation passed.
+    # @yield The code that performs validation.
+    # @return [void]
+    def validate
+      @validator = proc
+    end
+
+    # Sets the value of the attribute, raising an error if it is not among the valid types.
+    # @param value [Object] The new value of the attribute.
+    # @return [void]
+    # @raise [TypeError] If the new value is not among the declared valid types.
+    def value=(value)
+      if value && types && types.none? { |type| type === value }
+        raise TypeError, "#{name} must be one of: #{types.inspect}"
+      end
+
+      @value = value
+    end
+
+    private
+
+    # Finalize the root object.
+    def finalize_nested(object)
+      this = self
+
+      nested_object = Object.new
+      children.each { |child| child.finalize(nested_object) }
+      object.instance_exec { define_singleton_method(this.name) { nested_object } }
+
+      object
+    end
+
+    # Finalize a nested object.
+    def finalize_simple(object)
+      this = self
+
+      object.instance_exec do
+        define_singleton_method(this.name) { this.value }
+        define_singleton_method("#{this.name}=") do |value|
+          if this.validator
+            error = this.validator.call(value)
+            raise ValidationError, error if error
+          end
+
+          if this.types && this.types.none? { |type| type === value }
+            raise TypeError, "#{this.name} must be one of: #{this.types.inspect}"
+          end
+
+          this.value = value
+        end
+      end
+
+      object
+    end
+  end
+end

data/lib/lita/configuration_validator.rb

@@ -0,0 +1,66 @@
+module Lita
+  # Validates a registry's configuration, checking for required attributes that are missing.
+  # @since 4.0.0
+  # @api private
+  class ConfigurationValidator
+    # @param registry [Lita::Registry] The registry to validate.
+    def initialize(registry)
+      @registry = registry
+    end
+
+    # Validates adapter and handler configuration.
+    # @return [void]
+    # @raise [Lita::ValidationError] If any required configuration attributes are missing.
+    def call
+      validate_adapters
+      validate_handlers
+    end
+
+    private
+
+    # The registry's adapters.
+    def adapters
+      @registry.adapters
+    end
+
+    # All a plugin's top-level configuration attributes.
+    def children_for(plugin)
+      plugin.configuration.children
+    end
+
+    # Generates the fully qualified name of a configuration attribute.
+    def full_attribute_name(names, name)
+      (names + [name]).join(".")
+    end
+
+    # The registry's handlers.
+    def handlers
+      @registry.handlers
+    end
+
+    # Validates the registry's adapters.
+    def validate_adapters
+      adapters.each_value { |adapter| validate(:adapter, adapter, children_for(adapter)) }
+    end
+
+    # Validates the registry's handlers.
+    def validate_handlers
+      handlers.each { |handler| validate(:handler, handler, children_for(handler)) }
+    end
+
+    # Validates an array of attributes, recursing if any nested attributes are encountered.
+    def validate(type, plugin, attributes, attribute_namespace = [])
+      attributes.each do |attribute|
+        if attribute.children?
+          validate(type, plugin, attribute.children, attribute_namespace.clone.push(attribute.name))
+        elsif attribute.required? && attribute.value.nil?
+          raise ValidationError, I18n.t(
+            "lita.config.missing_required_#{type}_attribute",
+            type => plugin.namespace,
+            attribute: full_attribute_name(attribute_namespace, attribute.name)
+          )
+        end
+      end
+    end
+  end
+end

data/lib/lita/daemon.rb

@@ -2,6 +2,7 @@ require "fileutils"
 
 module Lita
   # Converts Lita to a daemon process.
+  # @deprecated Will be removed in Lita 5.0. Use your operating system's process manager instead.
   class Daemon
     # @param pid_path [String] The path to the PID file.
     # @param log_path [String] The path to the log file.
@@ -49,17 +50,9 @@ module Lita
     # Redirect the standard streams to a log file.
     def set_up_logs
       log_file = File.new(@log_path, "a")
-      stdout.reopen(log_file)
-      stderr.reopen(log_file)
-      stderr.sync = stdout.sync = true
-    end
-
-    def stdout
-      $stdout
-    end
-
-    def stderr
-      $stderr
+      STDOUT.reopen(log_file)
+      STDERR.reopen(log_file)
+      STDERR.sync = STDOUT.sync = true
     end
   end
 end

data/lib/lita/default_configuration.rb

@@ -0,0 +1,146 @@
+module Lita
+  # Builds the configuration object that is stored in each {Lita::Registry}.
+  # @since 4.0.0
+  # @api private
+  class DefaultConfiguration
+    # Valid levels for Lita's logger.
+    LOG_LEVELS = %w(debug info warn error fatal)
+
+    # A {Registry} to extract configuration for plugins from.
+    # @return [Lita::Registry] The registry.
+    attr_reader :registry
+
+    # The top-level {Configuration} attribute.
+    # @return [Lita::Configuration] The root attribute.
+    attr_reader :root
+
+    # @param registry [Lita::Registry] The registry to build a default configuration object from.
+    def initialize(registry)
+      @registry = registry
+      @root = Configuration.new
+
+      adapters_config
+      handlers_config
+      http_config
+      redis_config
+      robot_config
+    end
+
+    # Processes the {Configuration} object to return a raw object with only the appropriate methods.
+    # This is the value that's actually stored in {Lita::Registry#config}.
+    # @return [Object] The final form of the configuration object.
+    def finalize
+      final_config = root.finalize
+      add_adapter_attribute(final_config)
+      add_struct_access_to_redis(final_config.redis)
+      final_config
+    end
+
+    private
+
+    # Builds config.adapters
+    def adapters_config
+      adapters = registry.adapters
+
+      root.config :adapters do
+        adapters.each do |key, adapter|
+          combine(key, adapter.configuration)
+        end
+      end
+    end
+
+    # Builds config.adapter
+    def add_adapter_attribute(config)
+      config.singleton_class.class_exec { attr_accessor :adapter }
+      config.adapter = Class.new(Config) do
+        def []=(key, value)
+          deprecation_warning
+
+          super
+        end
+
+        def [](key)
+          deprecation_warning
+
+          super
+        end
+
+        def method_missing(name, *args)
+          deprecation_warning
+
+          super
+        end
+
+        def deprecation_warning
+          Lita.logger.warn(I18n.t("lita.config.adapter_deprecated"))
+        end
+        private :deprecation_warning
+      end.new
+    end
+
+    # Allow config.redis to be accessed as a struct, for backwards compatibility.
+    def add_struct_access_to_redis(redis)
+      def redis.method_missing(name, *args)
+        Lita.logger.warn(I18n.t("lita.config.redis_struct_access_deprecated"))
+        name_string = name.to_s
+        if name_string.chomp!("=")
+          self[name_string.to_sym] = args.first
+        else
+          self[name_string.to_sym]
+        end
+      end
+    end
+
+    # Builds config.handlers
+    def handlers_config
+      handlers = registry.handlers
+
+      root.config :handlers do
+        handlers.each do |handler|
+          if handler.configuration.children?
+            combine(handler.namespace, handler.configuration)
+          else
+            old_config = Config.new
+            handler.default_config(old_config) if handler.respond_to?(:default_config)
+            config(handler.namespace, default: old_config)
+          end
+        end
+      end
+    end
+
+    # Builds config.http
+    def http_config
+      root.config :http do
+        config :host, type: String, default: "0.0.0.0"
+        config :port, type: Integer, default: 8080
+        config :min_threads, type: Integer, default: 0
+        config :max_threads, type: Integer, default: 16
+        config :middleware, type: Array, default: []
+      end
+    end
+
+    # Builds config.redis
+    def redis_config
+      root.config :redis, type: Hash, default: {}
+    end
+
+    # Builds config.robot
+    def robot_config
+      root.config :robot do
+        config :name, type: String, default: "Lita"
+        config :mention_name, type: String
+        config :alias, type: String
+        config :adapter, types: [String, Symbol], default: :shell
+        config :locale, types: [String, Symbol], default: I18n.locale
+        config :log_level, types: [String, Symbol], default: :info do
+          validate do |value|
+            unless LOG_LEVELS.include?(value.to_s.downcase.strip)
+              "log_level must be one of: #{LOG_LEVELS.join(", ")}"
+            end
+          end
+        end
+        config :admins
+      end
+    end
+  end
+end