mithril 0.2.0

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+## Development Versions
+
+#### Version 0.2.0
+  * Implemented ProxyController
+
+#### Version 0.1.2
+  * Added HelpActions mixin
+
+#### Version 0.1.1
+  * Added logger property to Mithril module
+
+#### Version 0.1.0
+  * Implemented AbstractController
+
+#### Version 0.0.4
+  * Renamed ActionMixin to MixinWithActions for clarity
+  * Improved specs for Mixin, MixinWithActions
+
+#### Version 0.0.3
+  * Implemented Mithril::Parsers::SimpleParser
+
+#### Version 0.0.2
+  * Implemented Mithril::Controllers::Mixins::ActionsBase
+  * Implemented Mithril::Request
+  * Added and monkey-patched RSpec Matchers
+
+#### Version 0.0.1
+  * Implemented Mithril::Mixin
+
+#### Version 0.0.0
+  * Smoke test

data/bin/mithril

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'mithril'
+
+puts "Greetings, programs!"

data/lib/mithril.rb

@@ -0,0 +1,13 @@
+# lib/mithril.rb
+
+require 'logger'
+
+module Mithril
+  def self.logger
+    return @logger ||= Logger.new(STDOUT)
+  end # class accessor logger
+  
+  def self.logger=(logger)
+    @logger = logger
+  end # class mutator logger=
+end # module

data/lib/mithril/controllers.rb

@@ -0,0 +1,7 @@
+# lib/mithril/controllers.rb
+
+require 'mithril'
+
+module Mithril
+  module Controllers; end
+end # module

data/lib/mithril/controllers/abstract_controller.rb

@@ -0,0 +1,130 @@
+# lib/mithril/controllers/abstract_controller.rb
+
+require 'mithril/controllers'
+require 'mithril/controllers/mixins/actions_base'
+require 'mithril/controllers/mixins/mixin_with_actions'
+require 'mithril/parsers/simple_parser'
+
+module Mithril::Controllers
+  # Base class for Mithril controllers. Extending controller functionality
+  # can be implemented either through direct class inheritance, e.g.
+  # 
+  #   ModuleController > ProxyController > AbstractController
+  # 
+  # or through mixing in shared functionality with a Mixin, but all controllers
+  # ought to extend AbstractController unless you have a very compelling reason
+  # otherwise.
+  class AbstractController
+    extend Mithril::Controllers::Mixins::MixinWithActions
+    
+    mixin Mithril::Controllers::Mixins::ActionsBase
+    
+    # @param [Mithril::Request] request Request object containing the volatile
+    #   state information needed to build the controller and execute commands.
+    # @raise [ArgumentError] If request does not respond to :session.
+    def initialize(request)
+      unless request.respond_to? :session
+        raise ArgumentError.new "expected request to respond_to :session" 
+      end # unless
+      
+      @request = request
+    end # constructor
+    
+    def class_name
+      (self.class.name || "").split("::").last
+    end # accessor class_name
+    private :class_name
+    
+    #########################
+    ### Executing Actions ###
+    
+    # The parser object used to process input into a command and an arguments
+    # object.
+    def parser
+      @parser ||= Mithril::Parsers::SimpleParser.new(self)
+    end # method parser
+    
+    # Delegates to the parser instance. Note that if a custom parser is used
+    # that does not conform to the expected API, the return values may be
+    # different than listed.
+    # @param [Object] input The input to be parsed.
+    # @return [Array] The first element will be the matched command, or nil if
+    #   no command was found. The second element will be the arguments object
+    #   created by the parser.
+    def parse_command(input)
+      self.parser.parse_command input
+    end # method parse_command
+    
+    # @return [Array] All commands available to this controller.
+    def commands
+      actions.keys.map do |key| key.to_s.gsub '_', ' '; end
+    end # method commands
+    
+    # @param [String, Symbol] text The command to check. The parameter is
+    #   converted to a String, and must exactly match a command available
+    #   to the controller.
+    # @return [Boolean] True if this controller has the specified command.
+    #   Otherwise false.
+    # @see #can_invoke?
+    def has_command?(text)
+      commands.include? text.to_s
+    end # method has_command?
+    
+    # @example Using :has_command? and :can_invoke?
+    #   # With an action "do" defined
+    #   has_command?("do something") #=> false
+    #   can_invoke?("do something")  #=> true
+    # @param [Object] input The sample input to be parsed. Type and format will
+    #   depend on the parser used.
+    # @return [Boolean] True if this controller has a command matching the
+    #   provided input. Otherwise false.
+    # @see #has_command?
+    def can_invoke?(input)
+      self.allow_empty_action? || !self.parse_command(input).first.nil?
+    end # method can_invoke?
+    
+    # Default output when a command cannot be found for a given input.
+    # @param [Object] input The input that failed to match a command.
+    # @return [Object]
+    def command_missing(input)
+      "I'm sorry, I don't know how to \"#{input.to_s}\". Please try another" +
+        " command, or enter \"help\" for assistance."
+    end # method command_missing
+    
+    # Parses input into a command and arguments, then matches the command to an
+    # available action (if any), invokes the action, and returns the result. If
+    # there is no matching command, but the controller has an empty action :""
+    # defined and allow_empty_action? evaluates to true, the controller will
+    # instead invoke the empty action with the parsed arguments. If no matching
+    # command is found, returns the result of command_missing.
+    # 
+    # @param [Object] input The input to be parsed and evaluated. Type and
+    #   format will depend on the parser used.
+    # @return [Object] The result of the command. If no command is found,
+    #   returns the result of command_missing.
+    # @see #allow_empty_action?
+    # @see #command_missing
+    # @see #parse_command
+    def invoke_command(text)
+      # Mithril.logger.debug "#{class_name}.invoke_command(), text =" +
+      #   " #{text.inspect}"
+      
+      command, args = self.parse_command text
+      
+      if self.has_action? command
+        self.invoke_action command, args
+      elsif allow_empty_action?
+        self.invoke_action :"", args
+      else
+        command_missing(text)
+      end # unless-elsif
+    end # method invoke_command
+    
+    # If this method evaluates to true, if the controller does not recognize an
+    # action from the input text, it will attempt to invoke the empty action
+    # :"" with the full arguments list.
+    def allow_empty_action?
+      false
+    end # method allow_empty_action?
+  end # class AbstractController
+end # module

data/lib/mithril/controllers/mixins.rb

@@ -0,0 +1,7 @@
+# lib/mithril/controllers/mixins.rb
+
+require 'mithril/controllers'
+
+module Mithril::Controllers
+  module Mixins; end
+end # module

data/lib/mithril/controllers/mixins/actions_base.rb

@@ -0,0 +1,114 @@
+# lib/mithril/controllers/mixins/actions_base.rb
+
+require 'mithril/controllers/mixins/mixin_with_actions'
+
+module Mithril::Controllers::Mixins
+  # Core functions for implementing a command+args response model. ActionsBase
+  # should be mixed in to controllers, either directly or via an intermediate
+  # Mixin that implements default or shared actions.
+  # 
+  # @see Mithril::Mixin
+  # @see Mithril::Controllers::Mixins::ActionsBase::ClassMethods
+  module ActionsBase
+    extend Mithril::Controllers::Mixins::MixinWithActions
+    
+    # These methods get extended into the class of the controller through the
+    # magic of Mixin.
+    # 
+    # @see Mithril::Mixin
+    # @see Mithril::Controllers::Mixins::ActionsBase
+    module ClassMethods
+      # Defines an action to which the controller will respond.
+      # 
+      # @param [Symbol, String] key Best practice is to use snake_case,
+      #   e.g. all lower-case letters, with words separated by underscores. It
+      #   *ought* to work anyway, but caveat lector.
+      # @param [Hash] params Optional. Expects a hash of configuration values.
+      # @option params [Boolean] :private If set to true, creates a private
+      #     action. Private actions are not listed by "help" and cannot be
+      #     invoked directly by the user. They can be used to set up internal
+      #     APIs.
+      # @yieldparam [Hash] session An object describing the current (volatile)
+      #   state of the user session.
+      # @yieldparam [Object] arguments Additional information from the request
+      #   to be passed into the action. Using the default parser, the arguments
+      #   object will be an Array, but other parsers may pass in other data
+      #   structures.
+      def define_action(key, params = {}, &block)
+        key = key.to_s.downcase.gsub(/\s+|\-+/,'_').intern
+        
+        define_method :"action_#{key}", &block
+        
+        @actions ||= {}
+        @actions[key] = params
+      end # class method define_action
+      
+      # Lists the actions defined for the current controller by its base class.
+      # In almost all cases, the actions instance method should be used
+      # instead, as it handles class-based inheritance.
+      # 
+      # @param [Boolean] allow_private If true, will include private actions.
+      # @return [Hash] The actions defined on the current controller class.
+      # 
+      # @see Mithril::Controllers::Mixins::ActionsBase#actions
+      def actions(allow_private = false)
+        actions = @actions ||= {}
+        
+        unless allow_private
+          actions = actions.select { |key, action| !action.has_key? :private }
+        end # unless
+        
+        actions
+      end # class method actions
+    end # module ClassMethods
+    
+    # @return [Mithril::Request]
+    attr_reader :request
+    
+    # Lists the actions available to the current controller.
+    # 
+    # @param [Boolean] allow_private If true, will include private actions.
+    # @return [Hash] The actions available to this controller.
+    def actions(allow_private = false)
+      actions = {}
+      
+      actions.update(self.class.superclass.actions(allow_private)) if (klass = self.class.superclass).respond_to? :actions
+      
+      actions.update(self.class.actions(allow_private))
+      
+      actions
+    end # method actions
+    
+    # @param [Symbol, String] key The action key to be checked.
+    # @param [Boolean] allow_private If true, will include private actions.
+    # @return [Boolean] True if the action is available on this controller with
+    #   the specified private setting; false otherwise.
+    def has_action?(key, allow_private = false)
+      return false if key.nil?
+      
+      self.actions(allow_private).has_key? key.intern
+    end # method has_action?
+    
+    # Searches for a matching action. If found, calls the action with the given
+    # session hash and arguments list.
+    # 
+    # @param [Symbol, String] command Converted to a string. The converted
+    #   string must be an exact match (===) to the key passed in to
+    #   klass.define_action.
+    # @param [Object] arguments Additional information from the request to be
+    #   passed into the action. Using the default parser, the arguments object
+    #   will be an Array, but other parsers may pass in other data structures.
+    # @param [Boolean] allow_private If true, can invoke private actions.
+    # 
+    # @return [String, nil] The result of the action (should be a string), or
+    #   nil if no action was invoked.
+    def invoke_action(command, arguments, allow_private = false)
+      session = request ? request.session || {} : {}
+      if self.has_action? command, allow_private
+        self.send :"action_#{command}", session, arguments
+      else
+        nil
+      end # if-else
+    end # method invoke_action
+  end # module ActionsBase
+end # module

data/lib/mithril/controllers/mixins/help_actions.rb

@@ -0,0 +1,46 @@
+# lib/mithril/controllers/mixins/help_actions.rb
+
+require 'mithril/controllers/mixins/actions_base'
+require 'mithril/controllers/mixins/mixin_with_actions'
+
+module Mithril::Controllers::Mixins
+  module HelpActions
+    extend MixinWithActions
+    
+    mixin ActionsBase
+    
+    def help_message
+      ""
+    end # method help_message
+    
+    define_action :help do |session, arguments|
+      if arguments.first =~ /help/i
+        return "The help command provides general assistance, or information" +
+          " on specific commands.\n\nFormat: help COMMAND"
+      end # if
+      
+      words = arguments.dup
+      key   = nil
+      
+      while 0 < words.count
+        cmd = words.join(' ')
+        key = words.join('_').intern
+        
+        if self.respond_to?(:has_command?) && self.has_command?(cmd)
+          return self.invoke_command "#{cmd} help"
+        elsif self.has_action? key
+          return self.invoke_action key, %w(help)
+        end # if
+        
+        words.pop
+      end # while
+      
+      str = 0 < self.help_message.length ? "#{self.help_message}\n\n" : ""
+      
+      names = self.respond_to?(:commands) ?
+        self.commands :
+        self.actions.map { |key, value| key.to_s.gsub('_',' ') }
+      str += "The following commands are available: #{names.uniq.join(", ")}"
+    end # action help
+  end # module
+end # module

data/lib/mithril/controllers/mixins/mixin_with_actions.rb

@@ -0,0 +1,27 @@
+# lib/mithril/controllers/mixins/mixin_with_actions.rb
+
+require 'mithril/controllers/mixins'
+require 'mithril/mixin'
+
+module Mithril::Controllers::Mixins
+  module MixinWithActions
+    include Mithril::Mixin
+  
+  private
+    # Extends the mixin method to implement inheritance of @actions ivar.
+    def mixin(source_module) # :doc:
+      super
+      
+      self.mixins.each do |mixin|
+        next unless source_module.respond_to? :actions
+        if self.instance_variable_defined? :@actions
+          source_module.actions.each do |key, value|
+            @actions[key] = value
+          end # each
+        else
+          @actions = source_module.actions.dup
+        end # if-else
+      end # each
+    end # method mixin
+  end # module
+end # module

data/lib/mithril/controllers/proxy_controller.rb

@@ -0,0 +1,89 @@
+# lib/mithril/controllers/proxy_controller.rb
+
+require 'mithril/controllers/abstract_controller'
+
+module Mithril::Controllers
+  # Redirects incoming commands to a proxy controller based on the :proxy
+  # method. If no proxy is present, evaluates commands as normal.
+  class ProxyController < AbstractController
+    # The subject controller to which commands are redirected. Must be
+    # overriden in subclasses.
+    # 
+    # @return [AbstractController]
+    def proxy
+      nil # override this in sub-classes
+    end # method proxy
+    
+    # If evalutes to true, then any actions defined on this controller will be
+    # available even when a proxy is present. Defaults to true, but can be
+    # overriden in subclasses.
+    #
+    # @return [Boolean]
+    def allow_own_actions_while_proxied?
+      true
+    end # method allow_own_actions_while_proxied?
+    
+    # @see AbstractController#commands
+    def commands
+      if proxy.nil?
+        super
+      elsif self.allow_own_actions_while_proxied?
+        super + proxy.commands
+      else
+        proxy.commands
+      end # if-elsif-else
+    end # method commands
+    
+    # @see AbstractController#can_invoke?
+    alias_method :can_invoke_on_self?, :can_invoke?
+    
+    # As can_invoke?, but returns true iff the command is available on this
+    # controller directly, as opposed to through a proxy subject.
+    # 
+    # @param [String]
+    # @return [Boolean]
+    # @see ProxyController#can_invoke_on_self?
+    def can_invoke?(input)
+      if self.proxy.nil?
+        super
+      elsif self.allow_own_actions_while_proxied? && self.can_invoke_on_self?(input)
+        super
+      else
+        proxy.can_invoke?(input)
+      end # if-elsif-else
+    end # method can_invoke_on_self?
+    
+    # If no proxy is present, attempts to invoke the command on self. If a
+    # proxy subject is present and the parent can invoke that command and
+    # allow_own_actions_while_proxied? evaluates to true, attempts to invoke
+    # the command on self. Otherwise, if the proxy subject can invoke that
+    # command, invokes the command on the proxy subject.
+    # 
+    # This precedence order was selected to allow reflection within commands,
+    # e.g. the help action in Mixins::HelpActions that lists all available
+    # commands.
+    # 
+    # @param [Object] input The input to be parsed and evaluated. Type and
+    #   format will depend on the parser used.
+    # @return [Object] The result of the command. If no command is found,
+    #   returns the result of command_missing.
+    # @see #proxy
+    # @see AbstractController#invoke_command
+    def invoke_command(input)
+      # Mithril.logger.debug "#{class_name}.invoke_command(), text =" +
+      #   " #{text.inspect}, session = #{request.session.inspect}, proxy =" +
+      #   " #{proxy}"
+      
+      if self.proxy.nil?
+        super
+      elsif self.allow_own_actions_while_proxied? && self.can_invoke_on_self?(input)
+        super
+      elsif proxy.can_invoke? input
+        proxy.invoke_command input
+      else
+        command_missing(input)
+      end # if-elsif-else
+    end # method invoke_command
+  end # class ProxyController
+end # module
+