module Irc
+
+ # +MessageMapper+ is a class designed to reduce the amount of regexps and
+ # string parsing plugins and bot modules need to do, in order to process
+ # and respond to messages.
+ #
+ # You add templates to the MessageMapper which are examined by the handle
+ # method when handling a message. The templates tell the mapper which
+ # method in its parent class (your class) to invoke for that message. The
+ # string is split, optionally defaulted and validated before being passed
+ # to the matched method.
+ #
+ # A template such as "foo :option :otheroption" will match the string "foo
+ # bar baz" and, by default, result in method +foo+ being called, if
+ # present, in the parent class. It will receive two parameters, the
+ # Message (derived from BasicUserMessage) and a Hash containing
+ # {:option => "bar", :otheroption => "baz"}
+ # See the #map method for more details.
class MessageMapper
+ # used to set the method name used as a fallback for unmatched messages.
+ # The default fallback is a method called "usage".
attr_writer :fallback
+ # parent:: parent class which will receive mapped messages
+ #
+ # create a new MessageMapper with parent class +parent+. This class will
+ # receive messages from the mapper via the handle() method.
def initialize(parent)
@parent = parent
- @routes = Array.new
+ @templates = Array.new
@fallback = 'usage'
end
-
- def map(*args)
- @routes << Route.new(*args)
+
+ # args:: hash format containing arguments for this template
+ #
+ # map a template string to an action. example:
+ # map 'myplugin :parameter1 :parameter2'
+ # (other examples follow). By default, maps a matched string to an
+ # action with the name of the first word in the template. The action is
+ # a method which takes a message and a parameter hash for arguments.
+ #
+ # The :action => 'method_name' option can be used to override this
+ # default behaviour. Example:
+ # map 'myplugin :parameter1 :parameter2', :action => 'mymethod'
+ #
+ # By default whether a handler is fired depends on an auth check. The
+ # first component of the string is used for the auth check, unless
+ # overridden via the :auth => 'auth_name' option.
+ #
+ # Static parameters (not prefixed with ':' or '*') must match the
+ # respective component of the message exactly. Example:
+ # map 'myplugin :foo is :bar'
+ # will only match messages of the form "myplugin something is
+ # somethingelse"
+ #
+ # Dynamic parameters can be specified by a colon ':' to match a single
+ # component (whitespace seperated), or a * to suck up all following
+ # parameters into an array. Example:
+ # map 'myplugin :parameter1 *rest'
+ #
+ # You can provide defaults for dynamic components using the :defaults
+ # parameter. If a component has a default, then it is optional. e.g:
+ # map 'myplugin :foo :bar', :defaults => {:bar => 'qux'}
+ # would match 'myplugin param param2' and also 'myplugin param'. In the
+ # latter case, :bar would be provided from the default.
+ #
+ # Components can be validated before being allowed to match, for
+ # example if you need a component to be a number:
+ # map 'myplugin :param', :requirements => {:param => /^\d+$/}
+ # will only match strings of the form 'myplugin 1234' or some other
+ # number.
+ #
+ # Templates can be set not to match public or private messages using the
+ # :public or :private boolean options.
+ #
+ # Further examples:
+ #
+ # # match 'karmastats' and call my stats() method
+ # map 'karmastats', :action => 'stats'
+ # # match 'karma' with an optional 'key' and call my karma() method
+ # map 'karma :key', :defaults => {:key => false}
+ # # match 'karma for something' and call my karma() method
+ # map 'karma for :key'
+ #
+ # # two matches, one for public messages in a channel, one for
+ # # private messages which therefore require a channel argument
+ # map 'urls search :channel :limit :string', :action => 'search',
+ # :defaults => {:limit => 4},
+ # :requirements => {:limit => /^\d+$/},
+ # :public => false
+ # plugin.map 'urls search :limit :string', :action => 'search',
+ # :defaults => {:limit => 4},
+ # :requirements => {:limit => /^\d+$/},
+ # :private => false
+ #
+ def map(botmodule, *args)
+ @templates << Template.new(botmodule, *args)
end
-
+
def each
- @routes.each {|route| yield route}
+ @templates.each {|tmpl| yield tmpl}
end
+
def last
- @routes.last
+ @templates.last
end
-
+
+ # m:: derived from BasicUserMessage
+ #
+ # examine the message +m+, comparing it with each map()'d template to
+ # find and process a match. Templates are examined in the order they
+ # were map()'d - first match wins.
+ #
+ # returns +true+ if a match is found including fallbacks, +false+
+ # otherwise.
def handle(m)
- return false if @routes.empty?
+ return false if @templates.empty?
failures = []
- @routes.each do |route|
- options, failure = route.recognize(m)
+ @templates.each do |tmpl|
+ options, failure = tmpl.recognize(m)
if options.nil?
- failures << [route, failure]
+ failures << [tmpl, failure]
else
- action = route.options[:action] ? route.options[:action] : route.items[0]
- next unless @parent.respond_to?(action)
- auth = route.options[:auth] ? route.options[:auth] : action
+ action = tmpl.options[:action] ? tmpl.options[:action] : tmpl.items[0]
+ unless @parent.respond_to?(action)
+ failures << [tmpl, "class does not respond to action #{action}"]
+ next
+ end
+ auth = tmpl.options[:full_auth_path]
+ debug "checking auth for #{auth}"
if m.bot.auth.allow?(auth, m.source, m.replyto)
- debug "route found and auth'd: #{action.inspect} #{options.inspect}"
+ debug "template match found and auth'd: #{action.inspect} #{options.inspect}"
@parent.send(action, m, options)
return true
end
+ debug "auth failed for #{auth}"
# if it's just an auth failure but otherwise the match is good,
# don't try any more handlers
- break
+ return false
end
end
- debug failures.inspect
+ failures.each {|f, r|
+ debug "#{f.inspect} => #{r}"
+ }
debug "no handler found, trying fallback"
if @fallback != nil && @parent.respond_to?(@fallback)
if m.bot.auth.allow?(@fallback, m.source, m.replyto)
end
- class Route
+ class Template
attr_reader :defaults # The defaults hash
attr_reader :options # The options hash
attr_reader :items
- def initialize(template, hash={})
- raise ArgumentError, "Second argument must be a hash!" unless hash.kind_of?(Hash)
+
+ def initialize(botmodule, template, hash={})
+ raise ArgumentError, "Third argument must be a hash!" unless hash.kind_of?(Hash)
@defaults = hash[:defaults].kind_of?(Hash) ? hash.delete(:defaults) : {}
@requirements = hash[:requirements].kind_of?(Hash) ? hash.delete(:requirements) : {}
self.items = template
+ if hash.has_key?(:auth)
+ warning "Command #{template} in #{botmodule} uses old :auth syntax, please upgrade"
+ end
+ if hash.has_key?(:full_auth_path)
+ warning "Command #{template} in #{botmodule} sets :full_auth_path, please don't do this"
+ else
+ case botmodule
+ when String
+ pre = botmodule
+ when Plugins::BotModule
+ pre = botmodule.name
+ else
+ raise ArgumentError, "Can't find auth base in #{botmodule.inspect}"
+ end
+ words = items.reject{ |x|
+ x == pre || x.kind_of?(Symbol)
+ }
+ if words.empty?
+ post = nil
+ else
+ post = words.first
+ end
+ if hash.has_key?(:auth_path)
+ extra = hash[:auth_path]
+ if extra.sub!(/^:/, "")
+ pre += "::" + post
+ post = nil
+ end
+ if extra.sub!(/:$/, "")
+ post = [post,words[1]].compact.join("::") if words.length > 1
+ end
+ pre = nil if extra.sub!(/^!/, "")
+ post = nil if extra.sub!(/!$/, "")
+ else
+ extra = nil
+ end
+ hash[:full_auth_path] = [pre,extra,post].compact.join("::")
+ # TODO check if the full_auth_path is sane
+ end
+
@options = hash
+ # debug "Create template #{self.inspect}"
end
+
def items=(str)
items = str.split(/\s+/).collect {|c| (/^(:|\*)(\w+)$/ =~ c) ? (($1 == ':' ) ? $2.intern : "*#{$2}".intern) : c} if str.kind_of?(String) # split and convert ':xyz' to symbols
items.shift if items.first == ""
# Verify uniqueness of each component.
@items.inject({}) do |seen, item|
if item.kind_of? Symbol
- raise ArgumentError, "Illegal template -- duplicate item #{item}\n #{str.inspect}" if seen.key? item
- seen[item] = true
+ # We must remove the initial * when present,
+ # because the parameters hash will intern both :item and *item as :item
+ it = item.to_s.sub(/^\*/,"").intern
+ raise ArgumentError, "Illegal template -- duplicate item #{it} in #{str.inspect}" if seen.key? it
+ seen[it] = true
end
seen
end
options[item] = value
else
if @defaults.has_key?(item)
- debug "item #{item} doesn't pass reqs but has a default of #{@defaults[item]}"
- options[item] = @defaults[item].clone
+ options[item] = @defaults[item]
# push the test-failed component back on the stack
components.unshift value
else
return nil, "Unused components were left: #{components.join '/'}" unless components.empty?
- return nil, "route is not configured for private messages" if @options.has_key?(:private) && !@options[:private] && m.private?
- return nil, "route is not configured for public messages" if @options.has_key?(:public) && !@options[:public] && !m.private?
-
+ return nil, "template is not configured for private messages" if @options.has_key?(:private) && !@options[:private] && m.private?
+ return nil, "template is not configured for public messages" if @options.has_key?(:public) && !@options[:public] && !m.private?
+
options.delete_if {|k, v| v.nil?} # Remove nil values.
return options, nil
end
"<#{self.class.to_s} #{@items.collect{|c| c.kind_of?(String) ? c : c.inspect}.join(' ').inspect}#{default_str}#{when_str}>"
end
- # Verify that the given value passes this route's requirements
+ # Verify that the given value passes this template's requirements
def passes_requirements?(name, value)
return @defaults.key?(name) && @defaults[name].nil? if value.nil? # Make sure it's there if it should be
projects / user / henk / code / ruby / rbot.git / blobdiff