Class: Aide::Bot

Inherits:
Object
  • Object
show all
Defined in:
lib/aide/bot.rb

Overview

The Bot class is the workhorse of aide. It is responsible for representing and executing the logic described by the dsl, and interacts with xmpp4r in order to send and receive messages via the jabber protocol.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Bot

Creates a new Bot instance.



24
25
26
 
# File 'lib/aide/bot.rb', line 24

def initialize
  @actions = {}
end

Instance Attribute Details

#actions=(value) ⇒ Object (writeonly)

Hash[String, Block] - the match strings to look for, and the code to execute when found.



10
11
12
 
# File 'lib/aide/bot.rb', line 10

def actions=(value)
  @actions = value
end

#allow_list ⇒ Object

Array - a list of jabber IDs to allow this bot to interact with. Precludes block_list.



17
18
19
 
# File 'lib/aide/bot.rb', line 17

def allow_list
  @allow_list
end

#block_list ⇒ Object

Array - a list of jabber IDs to explicitly block. Ignored if allow_list is set.



19
20
21
 
# File 'lib/aide/bot.rb', line 19

def block_list
  @block_list
end

#password=(value) ⇒ Object (writeonly)

Password - the password for this bot to use.



15
16
17
 
# File 'lib/aide/bot.rb', line 15

def password=(value)
  @password = value
end

#username=(value) ⇒ Object (writeonly)

String - the username to sign this bot in with.



13
14
15
 
# File 'lib/aide/bot.rb', line 13

def username=(value)
  @username = value
end

Instance Method Details

#add_action(match, block) ⇒ Object

Adds an action to the bot.

Parameters:

  • match: String. The text to match for this action.

  • block: Proc. The code to execute when this action is fired.



152
153
154
 
# File 'lib/aide/bot.rb', line 152

def add_action(match, block)
  @actions[match] = block
end

#add_allow_list(list) ⇒ Object

Allows for appending to the allow_list.

Parameters:

  • list: Array. The list of users to add to the allow_list.



161
162
163
164
 
# File 'lib/aide/bot.rb', line 161

def add_allow_list(list)
  @allow_list ||= []
  @allow_list += list
end

#add_block_list(list) ⇒ Object

Allows for appending to the block_list.

Parameters:

  • list: Array. The list of users to add to the block_list.



171
172
173
174
 
# File 'lib/aide/bot.rb', line 171

def add_block_list(list)
  @block_list ||= []
  @block_list += list
end

#is_user_allowed?(username) ⇒ Boolean

Checks a given username to see if it is explicitly allowed or blocked.

Parameters

  • username: String. The username to check privileges for.

Returns

boolean - the value of this boolean depends on the level of privileges set when the Bot was configured. If an allow_list is defined, then that list has highest precedence - true is returned if the user is in that list, and false is returned otherwise. If allow_list is not defined, but block_list is, then the inverse check is performed (true is returned when the user is absent from the block_list, and vice-versa). If neither list is defined then the user is assumed to be authorized.

Returns:

  • (Boolean) 


140
141
142
143
144
 
# File 'lib/aide/bot.rb', line 140

def is_user_allowed?(username)
  return @allow_list.member?(username) if @allow_list
  return !@block_list.member?(username) if @block_list
  return true
end

#login ⇒ Object

Logs this Bot instance in to the jabber network and starts it listening for messages.

Preconditions

This method assumes that the Bot has already been properly configured; specifically, that at least the username and password properties have been set.

Postconditions

  • The Bot will be logged on,

  • Its presence will be set to ‘chat,’ and

  • It will be listening for messages from privileged users in its own thread

(see is_user_allowed?)

Returns

nil



43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/aide/bot.rb', line 43

def 
  if @password == nil or @username == nil
    raise Aide::, "credentials missing"
  end
  @client = Jabber::Client.new(Jabber::JID.new(@username))
  @client.connect
  
  #actual authentication with the host
  begin
    @client.auth(@password)
  rescue Jabber::AuthenticationFailure => af
    raise Aide::, "Authentication failure: #{af.message}", af.backtrace
  end
  
  @client.send(Jabber::Presence.new)
  @thread = Thread.new do
    @client.add_message_callback do |m|
      if m.type == :chat and is_user_allowed? m.from.split('/')[0]
        process_message m
      end
    end
  end

end

#logout ⇒ Object

Log the bot out of jabber and kill the thread that is listening for messages.



106
107
108
109
 
# File 'lib/aide/bot.rb', line 106

def logout
  @client.close
  @thread.stop
end

#match(text) ⇒ Object

Given the text of a message, determines if that text matches any of the actions defined for this Bot.

Parameters

  • text: String. The text of the message to check for matches.

Returns

Hash[:action_name, :message] Where :action_name corresponds to the name of the action this text matches, and :message corresponds to everything in text after the match. Returns nil if no match was found.



122
123
124
125
 
# File 'lib/aide/bot.rb', line 122

def match(text)
  nil
  # defaulting to no match until this method is implemented
end

#process_message(message) ⇒ Object

Examines the given message to see if any actions need to be performed on it. If this message matches any actions defined for this Bot, an Aide::ActionContext is created and used to evaluate the block associated with that action.

Parameters

  • message: Jabber::Message. The message to process.



85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/aide/bot.rb', line 85

def process_message(message)
  results = match(message.body)
  return nil unless results #no need to do anything if there's no match
  
  context = Aide::ActionContext.new      
  block = @actions[results[:action_name]]
  context.message = results[:message]
  context.from = message.from
  context.to = message.to
  context.bot = self
  context.text = message.body
  context.type = message.type
  context.instance_eval(block.call)
  
  nil #no need to complicate things by returning the results of the block
end

#send(message) ⇒ Object

Sends the given message.

Parameters

  • message: Jabber::Message. The message to send.



73
74
75
 
# File 'lib/aide/bot.rb', line 73

def send(message)
  @client.send message 
end