Class: Cinch::User

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

Overview

Version:

  • 2.0.0

Direct Known Subclasses

Bot

Instance Attribute Summary collapse

Attributes inherited from Target

#bot, #name

Instance Method Summary collapse

Methods included from Syncable

#attribute_synced?, #mark_as_synced, #sync, #unsync, #wait_until_synced

Methods inherited from Target

#<=>, #action, #concretize, #ctcp, #eql?, #notice, #safe_action, #safe_notice, #safe_privmsg, #safe_send, #send

Constructor Details

#initialize(*args) ⇒ User

Note:

Generally, you shouldn’t initialize new instances of this class. Use Cinch::UserList#find_ensured instead.

Returns a new instance of User.



190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
# File 'lib/cinch/user.rb', line 190

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

  @synced_attributes  = Set.new

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

      refresh
    end
  }

  @monitored = false
end

Instance Attribute Details

#authnameString (readonly)

Returns the current value of authname.

Returns:

  • (String)

    the current value of authname



26
27
28
# File 'lib/cinch/user.rb', line 26

def authname
  @authname
end

#awayString? (readonly)

The user’s away message, or nil if not away.

Returns:

  • (String, nil)

    the current value of away



26
27
28
# File 'lib/cinch/user.rb', line 26

def away
  @away
end

#channelsArray<Channel> (readonly)

All channels the user is in.

Returns:

  • (Array<Channel>)

    the current value of channels



26
27
28
# File 'lib/cinch/user.rb', line 26

def channels
  @channels
end

#dataHash (readonly)

By default, you can use methods like #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)


175
176
177
# File 'lib/cinch/user.rb', line 175

def data
  @data
end

#hostString (readonly)

Returns the current value of host.

Returns:

  • (String)

    the current value of host



26
27
28
# File 'lib/cinch/user.rb', line 26

def host
  @host
end

#idleInteger (readonly)

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

Returns:

  • (Integer)

    the current value of idle



26
27
28
# File 'lib/cinch/user.rb', line 26

def idle
  @idle
end

#in_whoisBoolean

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.

Returns:

  • (Boolean)


44
45
46
# File 'lib/cinch/user.rb', line 44

def in_whois
  @in_whois
end

#last_nickString (readonly)

Returns:

Since:

  • 1.1.0



35
36
37
# File 'lib/cinch/user.rb', line 35

def last_nick
  @last_nick
end

#monitoredBoolean Also known as: monitored?

Note:

The attribute writer is in fact part of the private API

Returns True if the user is being monitored.

Returns:

  • (Boolean)

    True if the user is being monitored

See Also:



181
182
183
# File 'lib/cinch/user.rb', line 181

def monitored
  @monitored
end

#nickString (readonly)

The user’s nickname

Returns:

  • (String)

    the current value of nick



26
27
28
# File 'lib/cinch/user.rb', line 26

def nick
  @nick
end

#onlineObject Also known as: online?

Note:

This attribute will be updated by various events, but

unless #monitor is being used, this information cannot be ensured to be always correct.



26
27
28
# File 'lib/cinch/user.rb', line 26

def online
  @online
end

#operObject (readonly) Also known as: oper?

Since:

  • 2.1.0



26
27
28
# File 'lib/cinch/user.rb', line 26

def oper
  @oper
end

#realnameString (readonly)

Returns the current value of realname.

Returns:

  • (String)

    the current value of realname



26
27
28
# File 'lib/cinch/user.rb', line 26

def realname
  @realname
end

#secureBoolean (readonly) Also known as: secure?

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

Returns:

  • (Boolean)

    the current value of secure



26
27
28
# File 'lib/cinch/user.rb', line 26

def secure
  @secure
end

#signed_on_atTime (readonly)

Returns the current value of signed_on_at.

Returns:

  • (Time)

    the current value of signed_on_at



26
27
28
# File 'lib/cinch/user.rb', line 26

def signed_on_at
  @signed_on_at
end

#syncedBoolean (readonly) Also known as: synced?

Returns:

  • (Boolean)


38
39
40
# File 'lib/cinch/user.rb', line 38

def synced
  @synced
end

#unknownBoolean (readonly) Also known as: unknown?

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

Returns:

  • (Boolean)

    the current value of unknown



26
27
28
# File 'lib/cinch/user.rb', line 26

def unknown
  @unknown
end

#userString (readonly)

Returns the current value of user.

Returns:

  • (String)

    the current value of user



26
27
28
# File 'lib/cinch/user.rb', line 26

def user
  @user
end

Instance Method Details

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

See Also:



238
239
240
# File 'lib/cinch/user.rb', line 238

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

Version:

  • 1.1.0



233
234
235
# File 'lib/cinch/user.rb', line 233

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

#dcc_send(io, filename = File.basename(io.path))

Note:

This method blocks.

This method returns an undefined value.

Send data via DCC SEND to a user.

Parameters:

Since:

  • 2.0.0



423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
# File 'lib/cinch/user.rb', line 423

def dcc_send(io, filename = File.basename(io.path))
  own_ip = bot.config.dcc.own_ip || @bot.irc.socket.addr[2]
  dcc = DCC::Outgoing::Send.new(receiver: self,
                                filename: filename,
                                io: io,
                                own_ip: own_ip
                                )

  dcc.start_server

  handler = Handler.new(@bot, :message,
                        Pattern.new(/^/,
                                    /\001DCC RESUME #{filename} #{dcc.port} (\d+)\001/,
                                    /$/)) do |m, position|
    next unless m.user == self
    dcc.seek(position.to_i)
    m.user.send "\001DCC ACCEPT #{filename} #{dcc.port} #{position}\001"

    handler.unregister
  end
  @bot.handlers.register(handler)

  @bot.loggers.info "DCC: Outgoing DCC SEND: File name: %s - Size: %dB - IP: %s - Port: %d - Status: waiting" % [filename, io.size, own_ip, dcc.port]
  dcc.send_handshake
  begin
    dcc.listen
    @bot.loggers.info "DCC: Outgoing DCC SEND: File name: %s - Size: %dB - IP: %s - Port: %d - Status: done" % [filename, io.size, own_ip, dcc.port]
  rescue Timeout::Error
    @bot.loggers.info "DCC: Outgoing DCC SEND: File name: %s - Size: %dB - IP: %s - Port: %d - Status: failed (timeout)" % [filename, io.size, own_ip, dcc.port]
  ensure
    handler.unregister
  end
end

#end_of_whois(values)

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

Since:

  • 1.0.1



276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
# File 'lib/cinch/user.rb', line 276

def end_of_whois(values)
  @in_whois = false
  if values.nil?
    # for some reason, we did not receive user information. one
    # reason is freenode throttling WHOIS
    Thread.new do
      sleep 2
      refresh
    end
    return
  end

  if values[:unknown?]
    sync(:unknown?, true, true)
    self.online = false
    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[:registered]
    values[:authname] ||= self.nick
    values.delete(:registered)
  end
  {
    :authname => nil,
    :idle     => 0,
    :secure?  => false,
    :oper?    => false,
    :away     => nil,
    :channels => [],
  }.merge(values).each do |attr, value|
    sync(attr, value, true)
  end

  sync(:unknown?, false, true)
  self.online = true
end

#inspectString

Returns:



338
339
340
# File 'lib/cinch/user.rb', line 338

def inspect
  "#<User nick=#{@name.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:



353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
# File 'lib/cinch/user.rb', line 353

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

  Mask.new(s)
end

#match(other) ⇒ Boolean Also known as: =~

Check if the user matches a mask.

Parameters:

Returns:

  • (Boolean)


376
377
378
# File 'lib/cinch/user.rb', line 376

def match(other)
  Mask.from(other) =~ Mask.from(self)
end

#monitor

This method returns an undefined value.

Starts monitoring a user’s online state by either using MONITOR or periodically running WHOIS.

See Also:

Since:

  • 2.0.0



387
388
389
390
391
392
393
394
395
396
397
398
399
# File 'lib/cinch/user.rb', line 387

def monitor
  if @bot.irc.isupport["MONITOR"] > 0
    @bot.irc.send "MONITOR + #@name"
  else
    refresh
    @monitored_timer = Timer.new(@bot, interval: 30) {
      refresh
    }
    @monitored_timer.start
  end

  @monitored = true
end

#refresh Also known as: whois

Note:

The alias whois is deprecated and will be removed in a future version.

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.



249
250
251
252
253
254
255
256
257
258
259
260
261
# File 'lib/cinch/user.rb', line 249

def refresh
  return if @in_whois
  @data.keys.each do |attr|
    unsync attr
  end

  @in_whois = true
  if @bot.irc.network.whois_only_one_argument?
    @bot.irc.send "WHOIS #@name"
  else
    @bot.irc.send "WHOIS #@name #@name"
  end
end

#to_sString

Returns:



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

def to_s
  @name
end

#unmonitor

This method returns an undefined value.

Stops monitoring a user’s online state.

See Also:

Since:

  • 2.0.0



406
407
408
409
410
411
412
413
414
# File 'lib/cinch/user.rb', line 406

def unmonitor
  if @bot.irc.isupport["MONITOR"] > 0
    @bot.irc.send "MONITOR - #@name"
  else
    @monitored_timer.stop if @monitored_timer
  end

  @monitored = false
end

#unsync_all

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



328
329
330
# File 'lib/cinch/user.rb', line 328

def unsync_all
  super
end

#update_nick(new_nick)

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.

Used to update the user’s nick on nickchange events.

Parameters:

  • new_nick (String)

    The user’s new nick



479
480
481
482
483
484
485
486
# File 'lib/cinch/user.rb', line 479

def update_nick(new_nick)
  @last_nick, @name = @name, new_nick
  # Unsync authname because some networks tie authentication to
  # the nick, so the user might not be authenticated anymore after
  # changing their nick
  unsync(:authname)
  @bot.user_list.update_nick(self)
end