3 # +MessageMapper+ is a class designed to reduce the amount of regexps and
4 # string parsing plugins and bot modules need to do, in order to process
5 # and respond to messages.
7 # You add templates to the MessageMapper which are examined by the handle
8 # method when handling a message. The templates tell the mapper which
9 # method in its parent class (your class) to invoke for that message. The
10 # string is split, optionally defaulted and validated before being passed
11 # to the matched method.
13 # A template such as "foo :option :otheroption" will match the string "foo
14 # bar baz" and, by default, result in method +foo+ being called, if
15 # present, in the parent class. It will receive two parameters, the
16 # Message (derived from BasicUserMessage) and a Hash containing
17 # {:option => "bar", :otheroption => "baz"}
18 # See the #map method for more details.
20 # used to set the method name used as a fallback for unmatched messages.
21 # The default fallback is a method called "usage".
24 # parent:: parent class which will receive mapped messages
26 # create a new MessageMapper with parent class +parent+. This class will
27 # receive messages from the mapper via the handle() method.
28 def initialize(parent)
30 @templates = Array.new
34 # args:: hash format containing arguments for this template
36 # map a template string to an action. example:
37 # map 'myplugin :parameter1 :parameter2'
38 # (other examples follow). By default, maps a matched string to an
39 # action with the name of the first word in the template. The action is
40 # a method which takes a message and a parameter hash for arguments.
42 # The :action => 'method_name' option can be used to override this
43 # default behaviour. Example:
44 # map 'myplugin :parameter1 :parameter2', :action => 'mymethod'
46 # By default whether a handler is fired depends on an auth check. The
47 # first component of the string is used for the auth check, unless
48 # overridden via the :auth => 'auth_name' option.
50 # Static parameters (not prefixed with ':' or '*') must match the
51 # respective component of the message exactly. Example:
52 # map 'myplugin :foo is :bar'
53 # will only match messages of the form "myplugin something is
56 # Dynamic parameters can be specified by a colon ':' to match a single
57 # component (whitespace seperated), or a * to suck up all following
58 # parameters into an array. Example:
59 # map 'myplugin :parameter1 *rest'
61 # You can provide defaults for dynamic components using the :defaults
62 # parameter. If a component has a default, then it is optional. e.g:
63 # map 'myplugin :foo :bar', :defaults => {:bar => 'qux'}
64 # would match 'myplugin param param2' and also 'myplugin param'. In the
65 # latter case, :bar would be provided from the default.
67 # Components can be validated before being allowed to match, for
68 # example if you need a component to be a number:
69 # map 'myplugin :param', :requirements => {:param => /^\d+$/}
70 # will only match strings of the form 'myplugin 1234' or some other
73 # Templates can be set not to match public or private messages using the
74 # :public or :private boolean options.
78 # # match 'karmastats' and call my stats() method
79 # map 'karmastats', :action => 'stats'
80 # # match 'karma' with an optional 'key' and call my karma() method
81 # map 'karma :key', :defaults => {:key => false}
82 # # match 'karma for something' and call my karma() method
83 # map 'karma for :key'
85 # # two matches, one for public messages in a channel, one for
86 # # private messages which therefore require a channel argument
87 # map 'urls search :channel :limit :string', :action => 'search',
88 # :defaults => {:limit => 4},
89 # :requirements => {:limit => /^\d+$/},
91 # plugin.map 'urls search :limit :string', :action => 'search',
92 # :defaults => {:limit => 4},
93 # :requirements => {:limit => /^\d+$/},
96 def map(botmodule, *args)
97 @templates << Template.new(botmodule, *args)
101 @templates.each {|tmpl| yield tmpl}
108 # m:: derived from BasicUserMessage
110 # examine the message +m+, comparing it with each map()'d template to
111 # find and process a match. Templates are examined in the order they
112 # were map()'d - first match wins.
114 # returns +true+ if a match is found including fallbacks, +false+
117 return false if @templates.empty?
119 @templates.each do |tmpl|
120 options, failure = tmpl.recognize(m)
122 failures << [tmpl, failure]
124 action = tmpl.options[:action] ? tmpl.options[:action] : tmpl.items[0]
125 unless @parent.respond_to?(action)
126 failures << [tmpl, "class does not respond to action #{action}"]
129 auth = tmpl.options[:full_auth_path]
130 debug "checking auth for #{auth}"
131 if m.bot.auth.allow?(auth, m.source, m.replyto)
132 debug "template match found and auth'd: #{action.inspect} #{options.inspect}"
133 @parent.send(action, m, options)
136 debug "auth failed for #{auth}"
137 # if it's just an auth failure but otherwise the match is good,
138 # don't try any more handlers
142 failures.each {|f, r|
143 debug "#{f.inspect} => #{r}"
145 debug "no handler found, trying fallback"
146 if @fallback != nil && @parent.respond_to?(@fallback)
147 if m.bot.auth.allow?(@fallback, m.source, m.replyto)
148 @parent.send(@fallback, m, {})
158 attr_reader :defaults # The defaults hash
159 attr_reader :options # The options hash
162 def initialize(botmodule, template, hash={})
163 raise ArgumentError, "Third argument must be a hash!" unless hash.kind_of?(Hash)
164 @defaults = hash[:defaults].kind_of?(Hash) ? hash.delete(:defaults) : {}
165 @requirements = hash[:requirements].kind_of?(Hash) ? hash.delete(:requirements) : {}
166 self.items = template
167 if hash.has_key?(:auth)
168 warning "Command #{template} in #{botmodule} uses old :auth syntax, please upgrade"
170 if hash.has_key?(:full_auth_path)
171 warning "Command #{template} in #{botmodule} sets :full_auth_path, please don't do this"
176 when Plugins::BotModule
179 raise ArgumentError, "Can't find auth base in #{botmodule.inspect}"
181 post = items.reject{ |x|
182 x == pre || x.kind_of?(Symbol)
189 if hash.has_key?(:auth_path)
190 extra = hash[:auth_path]
191 pre = nil if extra.sub!(/^!/, "")
192 post = nil if extra.sub!(/!$/, "")
196 hash[:full_auth_path] = [pre,extra,post].compact.join("::")
197 # TODO check if the full_auth_path is sane
204 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
205 items.shift if items.first == ""
206 items.pop if items.last == ""
209 if @items.first.kind_of? Symbol
210 raise ArgumentError, "Illegal template -- first component cannot be dynamic\n #{str.inspect}"
213 # Verify uniqueness of each component.
214 @items.inject({}) do |seen, item|
215 if item.kind_of? Symbol
216 # We must remove the initial * when present,
217 # because the parameters hash will intern both :item and *item as :item
218 it = item.to_s.sub(/^\*/,"").intern
219 raise ArgumentError, "Illegal template -- duplicate item #{it} in #{str.inspect}" if seen.key? it
226 # Recognize the provided string components, returning a hash of
227 # recognized values, or [nil, reason] if the string isn't recognized.
229 components = m.message.split(/\s+/)
232 @items.each do |item|
233 if /^\*/ =~ item.to_s
235 value = @defaults.has_key?(item) ? @defaults[item].clone : []
237 value = components.clone
240 def value.to_s() self.join(' ') end
241 options[item.to_s.sub(/^\*/,"").intern] = value
242 elsif item.kind_of? Symbol
243 value = components.shift || @defaults[item]
244 if passes_requirements?(item, value)
245 options[item] = value
247 if @defaults.has_key?(item)
248 options[item] = @defaults[item]
249 # push the test-failed component back on the stack
250 components.unshift value
252 return nil, requirements_for(item)
256 return nil, "No value available for component #{item.inspect}" if components.empty?
257 component = components.shift
258 return nil, "Value for component #{item.inspect} doesn't match #{component}" if component != item
262 return nil, "Unused components were left: #{components.join '/'}" unless components.empty?
264 return nil, "template is not configured for private messages" if @options.has_key?(:private) && !@options[:private] && m.private?
265 return nil, "template is not configured for public messages" if @options.has_key?(:public) && !@options[:public] && !m.private?
267 options.delete_if {|k, v| v.nil?} # Remove nil values.
272 when_str = @requirements.empty? ? "" : " when #{@requirements.inspect}"
273 default_str = @defaults.empty? ? "" : " || #{@defaults.inspect}"
274 "<#{self.class.to_s} #{@items.collect{|c| c.kind_of?(String) ? c : c.inspect}.join(' ').inspect}#{default_str}#{when_str}>"
277 # Verify that the given value passes this template's requirements
278 def passes_requirements?(name, value)
279 return @defaults.key?(name) && @defaults[name].nil? if value.nil? # Make sure it's there if it should be
281 case @requirements[name]
285 match = @requirements[name].match(value)
286 match && match[0].length == value.length
288 @requirements[name] == value.to_s
292 def requirements_for(name)
293 name = name.to_s.sub(/^\*/,"").intern if (/^\*/ =~ name.inspect)
294 presence = (@defaults.key?(name) && @defaults[name].nil?)
295 requirement = case @requirements[name]
297 when Regexp then "match #{@requirements[name].inspect}"
298 else "be equal to #{@requirements[name].inspect}"
300 if presence && requirement then "#{name} must be present and #{requirement}"
301 elsif presence || requirement then "#{name} must #{requirement || 'be present'}"
302 else "#{name} has no requirements"