class Cinch::User

@attr_reader [String] authname @attr_reader [String, nil] away The user's away message, or

`nil` if not away.

@attr_reader [Array<Channel>] channels All channels the user is

in.

@attr_reader [String] host @attr_reader [Integer] idle How long this user has been idle, in seconds.

This is a snapshot of the last WHOIS.

@attr_reader [String] nick The user's nickname @attr_reader [Boolean] online True if the user is online. @attr_reader [Boolean] oper True if the user is an IRC operator. @attr_reader [String] realname @attr_reader [Boolean] secure True if the user is using a secure

connection, i.e. SSL.

@attr_reader [Time] signed_on_at @attr_reader [Boolean] unknown True if the instance references an user who

cannot be found on the server.

@attr_reader [String] user

@version 2.0.0

Attributes

data[R]

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.

@example

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

@return [Hash]

in_whois[RW]

@return [Boolean] @api private

last_nick[R]

@return [String] @since 1.1.0

monitored[RW]

@return [Boolean] True if the user is being monitored @see monitor @see unmonitor @note The attribute writer is in fact part of the private API

monitored?[R]

@return [Boolean] True if the user is being monitored @see monitor @see unmonitor @note The attribute writer is in fact part of the private API

synced[R]

@return [Boolean]

synced?[R]

@return [Boolean]

Public Class Methods

new(*args) click to toggle source

@note Generally, you shouldn't initialize new instances of this

class. Use {UserList#find_ensured} instead.
# File lib/cinch/user.rb, line 189
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

Public Instance Methods

=~(other)
Alias for: match
attr(attribute, data = true, unsync = false) click to toggle source

@see Syncable#attr

Calls superclass method Cinch::Syncable#attr
# File lib/cinch/user.rb, line 237
def attr(attribute, data = true, unsync = false)
  super
end
authed?() click to toggle source

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

@return [Boolean] true if the user is identified @version 1.1.0

# File lib/cinch/user.rb, line 232
def authed?
  !attr(:authname).nil?
end
authname() click to toggle source
# File lib/cinch/user.rb, line 57
def authname
  attr(:authname, true, false)
end
authname_unsynced() click to toggle source

@private

# File lib/cinch/user.rb, line 117
def authname_unsynced
  attr(:authname, true, true)
end
away() click to toggle source
# File lib/cinch/user.rb, line 61
def away
  attr(:away, true, false)
end
channels() click to toggle source
# File lib/cinch/user.rb, line 86
def channels
  attr(:channels, true, false)
end
channels_unsynced() click to toggle source

@private

# File lib/cinch/user.rb, line 144
def channels_unsynced
  attr(:channels, true, true)
end
dcc_send(io, filename = File.basename(io.path)) click to toggle source

Send data via DCC SEND to a user.

@param [DCC::DCCableObject] io @param [String] filename @since 2.0.0 @return [void] @note This method blocks.

# File lib/cinch/user.rb, line 422
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) click to toggle source

@param [Hash, nil] values A hash of values gathered from WHOIS,

or `nil` if no data was returned

@return [void] @api private @since 1.0.1

# File lib/cinch/user.rb, line 275
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
host() click to toggle source
# File lib/cinch/user.rb, line 49
def host
  attr(:host, true, false)
end
host_unsynced() click to toggle source

@private

# File lib/cinch/user.rb, line 107
def host_unsynced
  attr(:host, true, true)
end
idle() click to toggle source
# File lib/cinch/user.rb, line 65
def idle
  attr(:idle, true, false)
end
idle_unsynced() click to toggle source

@private

# File lib/cinch/user.rb, line 122
def idle_unsynced
  attr(:idle, true, true)
end
inspect() click to toggle source

@return [String]

# File lib/cinch/user.rb, line 337
def inspect
  "#<User nick=#{@name.inspect}>"
end
mask(s = "%n!%u@%h") click to toggle source

Generates a mask for the user.

@param [String] s a pattern for generating the mask.

- %n = nickname
- %u = username
- %h = host
- %r = realname
- %a = authname

@return [Mask]

# File lib/cinch/user.rb, line 352
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) click to toggle source

Check if the user matches a mask.

@param [Ban, Mask, User, String] other The user or mask to match against @return [Boolean]

# File lib/cinch/user.rb, line 375
def match(other)
  Mask.from(other) =~ Mask.from(self)
end
Also aliased as: =~
monitor() click to toggle source

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

@since 2.0.0 @return [void] @see unmonitor

# File lib/cinch/user.rb, line 386
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
nick() click to toggle source
# File lib/cinch/user.rb, line 28
def nick
  name
end
online() click to toggle source

@note This attribute will be updated by various events, but unless {#monitor} is being used, this information cannot be ensured to be always correct.

# File lib/cinch/user.rb, line 81
def online
  attr(:online?, true, false)
end
Also aliased as: online?
online=(bool) click to toggle source

Updates the user's online state and dispatch the correct event.

@since 2.0.0 @return [void] @api private

# File lib/cinch/user.rb, line 461
def online=(bool)
  notify = self.__send__("online?_unsynced") != bool && @monitored
  sync(:online?, bool, true)

  return unless notify
  if bool
    @bot.handlers.dispatch(:online, nil, self)
  else
    @bot.handlers.dispatch(:offline, nil, self)
  end
end
online?()
Alias for: online
online?_unsynced()
Alias for: online_unsynced
online_unsynced() click to toggle source

@private

# File lib/cinch/user.rb, line 138
def online_unsynced
  attr(:online?, true, true)
end
Also aliased as: online?_unsynced
oper() click to toggle source

@since 2.1.0

# File lib/cinch/user.rb, line 96
def oper
  attr(:oper?, true, false)
end
Also aliased as: oper?
oper?()
Alias for: oper
oper?_unsynced()
Alias for: oper_unsynced
oper_unsynced() click to toggle source

@private @since 2.1.0

# File lib/cinch/user.rb, line 156
def oper_unsynced
  attr(:oper?, true, true)
end
Also aliased as: oper?_unsynced
realname() click to toggle source
# File lib/cinch/user.rb, line 53
def realname
  attr(:realname, true, false)
end
realname_unsynced() click to toggle source

@private

# File lib/cinch/user.rb, line 112
def realname_unsynced
  attr(:realname, true, true)
end
refresh() click to toggle source

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.

@return [void] @note The alias `whois` is deprecated and will be removed in a

future version.
# File lib/cinch/user.rb, line 248
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
Also aliased as: whois
secure() click to toggle source
# File lib/cinch/user.rb, line 90
def secure
  attr(:secure?, true, false)
end
Also aliased as: secure?
secure?()
Alias for: secure
secure?_unsynced()
Alias for: secure_unsynced
secure_unsynced() click to toggle source

@private

# File lib/cinch/user.rb, line 149
def secure_unsynced
  attr(:secure?, true, true)
end
Also aliased as: secure?_unsynced
signed_on_at() click to toggle source
# File lib/cinch/user.rb, line 69
def signed_on_at
  attr(:signed_on_at, true, false)
end
signed_on_at_unsynced() click to toggle source

@private

# File lib/cinch/user.rb, line 127
def signed_on_at_unsynced
  attr(:signed_on_at, true, true)
end
to_s() click to toggle source

@return [String]

# File lib/cinch/user.rb, line 332
def to_s
  @name
end
unknown() click to toggle source
# File lib/cinch/user.rb, line 73
def unknown
  attr(:unknown?, true, false)
end
Also aliased as: unknown?
unknown?()
Alias for: unknown
unknown?_unsynced()
Alias for: unknown_unsynced
unknown_unsynced() click to toggle source

@private

# File lib/cinch/user.rb, line 132
def unknown_unsynced
  attr(:unknown?, true, true)
end
Also aliased as: unknown?_unsynced
unmonitor() click to toggle source

Stops monitoring a user's online state.

@since 2.0.0 @return [void] @see monitor

# File lib/cinch/user.rb, line 405
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() click to toggle source

@return [void] @since 1.0.1 @api private @see Syncable#unsync_all

Calls superclass method Cinch::Syncable#unsync_all
# File lib/cinch/user.rb, line 327
def unsync_all
  super
end
update_nick(new_nick) click to toggle source

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

@param [String] new_nick The user's new nick @api private @return [void]

# File lib/cinch/user.rb, line 478
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
user() click to toggle source
# File lib/cinch/user.rb, line 45
def user
  attr(:user, true, false)
end
user_unsynced() click to toggle source

@private

# File lib/cinch/user.rb, line 102
def user_unsynced
  attr(:user, true, true)
end
whois()
Alias for: refresh