Class: Cinch::User

Inherits:
Object
  • Object
show all
Includes:
Syncable
Defined in:
lib/cinch/user.rb

Instance Attribute Summary collapse

Sending messages collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Syncable

#mark_as_synced, #sync, #synced?, #unsync, #wait_until_synced

Constructor Details

#initialize(*args) ⇒ User

Returns a new instance of User.



152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
 
# File 'lib/cinch/user.rb', line 152

def initialize(*args)
  @data = {
    :user         => nil,
    :host         => nil,
    :realname     => nil,
    :authname     => nil,
    :idle         => 0,
    :signed_on_at => nil,
    :unknown?     => false,
    :channels     => [],
    :secure?      => false,
  }
  case args.size
  when 2
    @nick, @bot = args
  when 4
    @data[:user], @nick, @data[:host], @bot = args
  else
    raise ArgumentError
  end

  @synced_attributes  = Set.new

  @when_requesting_synced_attribute = lambda {|attr|
    unless @synced
      @data[:unknown?] = false
      unsync :unknown?

      unsync attr
      whois
    end
  }
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(m, *args) ⇒ Object

Provides synced access to user attributes.



402
403
404
405
406
407
408
409
410
411
412
413
 
# File 'lib/cinch/user.rb', line 402

def method_missing(m, *args)
  if m.to_s =~ /^(.+)_unsynced$/
    m = $1.to_sym
    unsync = true
  end

  if @data.has_key?(m)
    attr(m, true, unsync = false)
  else
    super
  end
end

Instance Attribute Details

#authname ⇒ String (readonly)

Returns:



103
104
105
 
# File 'lib/cinch/user.rb', line 103

def authname
  @authname
end

#bot ⇒ Bot (readonly)

Returns:



82
83
84
 
# File 'lib/cinch/user.rb', line 82

def bot
  @bot
end

#channels ⇒ Array<Channel> (readonly)

Returns All channels the user is in.

Returns:

  • (Array<Channel>) —

    All channels the user is in.



126
127
128
 
# File 'lib/cinch/user.rb', line 126

def channels
  @channels
end

#data ⇒ Hash (readonly)

By default, you can use methods like User#user, User#host and alike – If you however fear that another thread might change data while you’re using it and if this means a critical issue to your code, you can store a clone of the result of this method and work with that instead.

Examples:

on :channel do |m|
  data = m.user.data.dup
  do_something_with(data.user)
  do_something_with(data.host)
end

Returns:

  • (Hash) 


151
152
153
 
# File 'lib/cinch/user.rb', line 151

def data
  @data
end

#host ⇒ String (readonly)

Returns:



95
96
97
 
# File 'lib/cinch/user.rb', line 95

def host
  @host
end

#idle ⇒ Number (readonly)

Returns How long this user has been idle, in seconds. This is a snapshot of the last WHOIS.

Returns:

  • (Number) —

    How long this user has been idle, in seconds. This is a snapshot of the last WHOIS.



108
109
110
 
# File 'lib/cinch/user.rb', line 108

def idle
  @idle
end

#in_whois ⇒ Boolean

Returns:

  • (Boolean) 


86
87
88
 
# File 'lib/cinch/user.rb', line 86

def in_whois
  @in_whois
end

#last_nick ⇒ String (readonly)

Returns:



80
81
82
 
# File 'lib/cinch/user.rb', line 80

def last_nick
  @last_nick
end

#nick ⇒ String (readonly)

Returns:



78
79
80
 
# File 'lib/cinch/user.rb', line 78

def nick
  @nick
end

#realname ⇒ String (readonly)

Returns:



99
100
101
 
# File 'lib/cinch/user.rb', line 99

def realname
  @realname
end

#secure ⇒ Boolean (readonly)

Returns True if the user is using a secure connection, i.e. SSL.

Returns:

  • (Boolean) —

    True if the user is using a secure connection, i.e. SSL.



130
131
132
 
# File 'lib/cinch/user.rb', line 130

def secure
  @secure
end

#signed_on_at ⇒ Time (readonly)

Returns:

  • (Time) 


112
113
114
 
# File 'lib/cinch/user.rb', line 112

def signed_on_at
  @signed_on_at
end

#synced ⇒ Boolean (readonly)

Returns:

  • (Boolean) 


84
85
86
 
# File 'lib/cinch/user.rb', line 84

def synced
  @synced
end

#unknown ⇒ Boolean (readonly)

Returns True if the instance references an user who cannot be found on the server.

Returns:

  • (Boolean) —

    True if the instance references an user who cannot be found on the server.



117
118
119
 
# File 'lib/cinch/user.rb', line 117

def unknown
  @unknown
end

#user ⇒ String (readonly)

Returns:



91
92
93
 
# File 'lib/cinch/user.rb', line 91

def user
  @user
end

Class Method Details

.all ⇒ Array<User>

Deprecated.

See Bot#user_manager and CacheManager#each instead

Note:

This method does not work properly if running more than one bot

Note:

This method will be removed in Cinch 2.0.0

Returns all users

Returns:

  • (Array<User>) —

    Returns all users



68
69
70
71
72
73
 
# File 'lib/cinch/user.rb', line 68

def all
  $stderr.puts "Deprecation warning: Beginning with version 1.1.0, User.all should not be used anymore."
  puts caller

  @users.values
end

.find(nick) ⇒ User?

Deprecated.

See Bot#user_manager and Cinch::UserManager#find instead

Note:

This method does not work properly if running more than one bot

Note:

This method will be removed in Cinch 2.0.0

Finds a user.

Parameters:

  • nick (String) —

    nick of a user

Returns:



57
58
59
60
61
62
 
# File 'lib/cinch/user.rb', line 57

def find(nick)
  $stderr.puts "Deprecation warning: Beginning with version 1.1.0, User.find should not be used anymore."
  puts caller

  @users[downcased_nick]
end

.find_ensured(nick, bot) ⇒ User .find_ensured(user, nick, host, bot) ⇒ User

Deprecated.

See Bot#user_manager and Cinch::UserManager#find_ensured instead

Note:

This method does not work properly if running more than one bot

Note:

This method will be removed in Cinch 2.0.0

Overloads:

  • .find_ensured(nick, bot) ⇒ User

    Finds or creates a user based on his nick.

    Parameters:

    • nick (String) —

      The user’s nickname

    • bot (Bot) —

      An instance of Bot

  • .find_ensured(user, nick, host, bot) ⇒ User

    Finds or creates a user based on his nick but already setting user and host.

    Parameters:

    • user (String) —

      The username

    • nick (String) —

      The nickname

    • host (String) —

      The user’s hostname

    • bot (Bot) —

      An instance of bot

Returns:



27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/cinch/user.rb', line 27

def find_ensured(*args)
  $stderr.puts "Deprecation warning: Beginning with version 1.1.0, User.find_ensured should not be used anymore."
  puts caller

  case args.size
  when 2
    nick = args.first
    bot  = args.last
    bargs = [nick]
  when 4
    nick = args[1]
    bot  = args.pop
    bargs = args
  else
    raise ArgumentError
  end
  downcased_nick = nick.irc_downcase(bot.irc.isupport["CASEMAPPING"])
  @users[downcased_nick] = args.last.user_manager.find_ensured(*args[0..-2])
  # note: the complete case statement and the assignment to
  #   @users is only for keeping compatibility with older
  #   versions, which still use User.find and User.all.
end

Instance Method Details

#==(other) ⇒ Boolean Also known as: eql?

Returns:

  • (Boolean) 


424
425
426
427
428
429
430
431
432
433
434
435
 
# File 'lib/cinch/user.rb', line 424

def ==(other)
  return case other
         when self.class
           @nick == other.nick
         when String
           self.to_s == other
         when Bot
           self.nick == other.config.nick
         else
           false
         end
end

#action(message) ⇒ void

This method returns an undefined value.

Send an action (/me) to the user.

Parameters:

  • message (String) —

    the message

See Also:



333
334
335
 
# File 'lib/cinch/user.rb', line 333

def action(message)
  @bot.action(@name, message)
end

#attr(attribute, data = true, unsync = false) ⇒ Object

See Also:



195
196
197
 
# File 'lib/cinch/user.rb', line 195

def attr(attribute, data = true, unsync = false)
  super
end

#authed? ⇒ Boolean

Checks if the user is identified. Currently officially supports Quakenet and Freenode.

Returns:

  • (Boolean) —

    true if the user is identified



190
191
192
 
# File 'lib/cinch/user.rb', line 190

def authed?
  !attr(:authname).nil?
end

#ctcp(message) ⇒ void

This method returns an undefined value.

Send a CTCP to the user.

Parameters:

  • message (String) —

    the ctcp message



324
325
326
 
# File 'lib/cinch/user.rb', line 324

def ctcp(message)
  send "\001#{message}\001"
end

#end_of_whois(values, not_found = false) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Parameters:

  • values (Hash, nil) —

    A hash of values gathered from WHOIS, or ‘nil` if no data was returned

  • not_found (Boolean) (defaults to: false) —

    Has to be true if WHOIS resulted in an unknown user

Since:

  • 1.0.1



223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
 
# File 'lib/cinch/user.rb', line 223

def end_of_whois(values, not_found = false)
  @in_whois = false
  if not_found
    sync(:unknown?, true, true)
    sync(:idle, 0, true)
    sync(:channels, [], true)

    fields = @data.keys
    fields.delete(:unknown?)
    fields.delete(:idle)
    fields.delete(:channels)
    fields.each do |field|
      sync(field, nil, true)
    end

    return
  end

  if values.nil?
    # for some reason, we did not receive user information. one
    # reason is freenode throttling WHOIS
    Thread.new do
      sleep 2
      whois
    end
    return
  end

  {
    :authname => nil,
    :idle => 0,
    :secure? => false,
  }.merge(values).each do |attr, value|
    sync(attr, value, true)
  end

  sync(:unknown?, false, true)
  @synced = true
end

#hash ⇒ Fixnum

Returns:

  • (Fixnum) 


439
440
441
 
# File 'lib/cinch/user.rb', line 439

def hash
  @nick.hash
end

#inspect ⇒ String

Returns:



361
362
363
 
# File 'lib/cinch/user.rb', line 361

def inspect
  "#<User nick=#{@nick.inspect}>"
end

#mask(s = "%n!%u@%h") ⇒ Mask

Generates a mask for the user.

Parameters:

  • s (String) (defaults to: "%n!%u@%h") —

    a pattern for generating the mask.

    • %n = nickname

    • %u = username

    • %h = host

    • %r = realname

    • %a = authname

Returns:



376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
 
# File 'lib/cinch/user.rb', line 376

def mask(s = "%n!%u@%h")
  s = s.gsub(/%(.)/) {
    case $1
    when "n"
      @nick
    when "u"
      self.user
    when "h"
      self.host
    when "r"
      self.realname
    when "a"
      self.authname
    end
  }

  Mask.new(s)
end

#notice(message) ⇒ void

This method returns an undefined value.

Send a notice to the user.

Parameters:

  • message (String) —

    the message



288
289
290
 
# File 'lib/cinch/user.rb', line 288

def notice(message)
  @bot.notice(@nick, message)
end

#respond_to?(m) ⇒ Boolean

Returns:

  • (Boolean) 


415
416
417
418
419
420
421
 
# File 'lib/cinch/user.rb', line 415

def respond_to?(m)
  if m.to_s =~ /^(.+)_unsynced$/
    m = $1.to_sym
  end

  return @data.has_key?(m) || super
end

#safe_action(message) ⇒ void

TODO:

Handle mIRC color codes more gracefully.

This method returns an undefined value.

Send an action (/me) to the user but remove any non-printable characters. The purpose of this method is to send text from untrusted sources, like other users or feeds.

Note: this will break any mIRC color codes embedded in the string.

Parameters:

  • message (String) —

    the message

See Also:



349
350
351
 
# File 'lib/cinch/user.rb', line 349

def safe_action(message)
  @bot.safe_action(@name, message)
end

#safe_notice(message) ⇒ void

TODO:

Handle mIRC color codes more gracefully.

This method returns an undefined value.

Like #safe_send but for notices.

Parameters:

  • message (String) —

    the message

See Also:



298
299
300
 
# File 'lib/cinch/user.rb', line 298

def safe_notice(message)
  @bot.safe_notice(@nick, message)
end

#safe_send(message) ⇒ void Also known as: safe_privmsg, safe_msg

TODO:

Handle mIRC color codes more gracefully.

This method returns an undefined value.

Send a message to the user, but remove any non-printable characters. The purpose of this method is to send text from untrusted sources, like other users or feeds.

Note: this will break any mIRC color codes embedded in the string.

Parameters:

  • message (String) —

    the message

See Also:



314
315
316
 
# File 'lib/cinch/user.rb', line 314

def safe_send(message)
  @bot.safe_msg(@nick, message)
end

#secure? ⇒ Boolean

Returns True if the user is using a secure connection, i.e. SSL.

Returns:

  • (Boolean) —

    True if the user is using a secure connection, i.e. SSL.



131
132
133
 
# File 'lib/cinch/user.rb', line 131

def secure
  @secure
end

#send(message) ⇒ void Also known as: privmsg, msg

This method returns an undefined value.

Send a message to the user.

Parameters:

  • message (String) —

    the message



278
279
280
 
# File 'lib/cinch/user.rb', line 278

def send(message)
  @bot.msg(@nick, message)
end

#to_s ⇒ String

Returns:



356
357
358
 
# File 'lib/cinch/user.rb', line 356

def to_s
  @nick
end

#unknown? ⇒ Boolean

Returns True if the instance references an user who cannot be found on the server.

Returns:

  • (Boolean) —

    True if the instance references an user who cannot be found on the server.



118
119
120
 
# File 'lib/cinch/user.rb', line 118

def unknown
  @unknown
end

#unsync_all ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

See Also:

Since:

  • 1.0.1



267
268
269
270
 
# File 'lib/cinch/user.rb', line 267

def unsync_all
  @synced = false
  super
end

#update_nick(new_nick) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



396
397
398
399
 
# File 'lib/cinch/user.rb', line 396

def update_nick(new_nick)
  @last_nick, @nick = @nick, new_nick
  @bot.user_manager.update_nick(self)
end

#whois ⇒ void Also known as: refresh

This method returns an undefined value.

Queries the IRC server for information on the user. This will set the User’s state to not synced. After all information are received, the object will be set back to synced.



204
205
206
207
208
209
210
211
212
213
 
# File 'lib/cinch/user.rb', line 204

def whois
  return if @in_whois
  @synced = false
  @data.keys.each do |attr|
    unsync attr
  end

  @in_whois = true
  @bot.raw "WHOIS #@nick #@nick"
end