class Discordrb::Role

A Discord role that contains permissions and applies to certain users

Attributes

color[R]

@return [ColourRGB] the role colour

colour[R]

@return [ColourRGB] the role colour

hoist[R]

@return [true, false] whether or not this role should be displayed separately from other users

managed[R]

@return [true, false] whether or not this role is managed by an integration or a bot

managed?[R]

@return [true, false] whether or not this role is managed by an integration or a bot

mentionable[R]

@return [true, false] whether this role can be mentioned using a role mention

mentionable?[R]

@return [true, false] whether this role can be mentioned using a role mention

name[R]

@return [String] this role's name (“new role” if it hasn't been changed)

permissions[R]

@return [Permissions] this role's permissions.

position[R]

@return [Integer] the position of this role in the hierarchy

server[R]

@return [Server] the server this role belongs to

Public Class Methods

new(data, bot, server = nil) click to toggle source

@!visibility private

# File lib/discordrb/data.rb, line 942
def initialize(data, bot, server = nil)
  @bot = bot
  @server = server
  @permissions = Permissions.new(data['permissions'], RoleWriter.new(self, @bot.token))
  @name = data['name']
  @id = data['id'].to_i

  @position = data['position']

  @hoist = data['hoist']
  @mentionable = data['mentionable']
  @managed = data['managed']

  @colour = ColourRGB.new(data['color'])
end

Public Instance Methods

color=(colour)
Alias for: colour=
colour=(colour) click to toggle source

Sets the role colour to something new @param colour [ColourRGB] The new colour

# File lib/discordrb/data.rb, line 1013
def colour=(colour)
  update_role_data(colour: colour)
end
Also aliased as: color=
delete(reason = nil) click to toggle source

Deletes this role. This cannot be undone without recreating the role! @param reason [String] the reason for this role's deletion

# File lib/discordrb/data.rb, line 1055
def delete(reason = nil)
  API::Server.delete_role(@bot.token, @server.id, @id, reason)
  @server.delete_role(@id)
end
hoist=(hoist) click to toggle source

Changes whether or not this role is displayed at the top of the user list @param hoist [true, false] The value it should be changed to

# File lib/discordrb/data.rb, line 1001
def hoist=(hoist)
  update_role_data(hoist: hoist)
end
inspect() click to toggle source

The inspect method is overwritten to give more useful output

# File lib/discordrb/data.rb, line 1061
def inspect
  "<Role name=#{@name} permissions=#{@permissions.inspect} hoist=#{@hoist} colour=#{@colour.inspect} server=#{@server.inspect}>"
end
members() click to toggle source

@return [Array<Member>] an array of members who have this role. @note This requests a member chunk if it hasn't for the server before, which may be slow initially

# File lib/discordrb/data.rb, line 965
def members
  @server.members.select { |m| m.role? self }
end
Also aliased as: users
mention() click to toggle source

@return [String] a string that will mention this role, if it is mentionable.

# File lib/discordrb/data.rb, line 959
def mention
  "<@&#{@id}>"
end
mentionable=(mentionable) click to toggle source

Changes whether or not this role can be mentioned @param mentionable [true, false] The value it should be changed to

# File lib/discordrb/data.rb, line 1007
def mentionable=(mentionable)
  update_role_data(mentionable: mentionable)
end
move_above(other = nil)
Alias for: sort_above
name=(name) click to toggle source

Sets the role name to something new @param name [String] The name that should be set

# File lib/discordrb/data.rb, line 995
def name=(name)
  update_role_data(name: name)
end
packed=(packed, update_perms = true) click to toggle source

Changes this role's permissions to a fixed bitfield. This allows setting multiple permissions at once with just one API call.

Information on how this bitfield is structured can be found at discordapp.com/developers/docs/topics/permissions. @example Remove all permissions from a role

role.packed = 0

@param packed [Integer] A bitfield with the desired permissions value. @param update_perms [true, false] Whether the internal data should also be updated. This should always be true

when calling externally.
# File lib/discordrb/data.rb, line 1029
def packed=(packed, update_perms = true)
  update_role_data(permissions: packed)
  @permissions.bits = packed if update_perms
end
sort_above(other = nil) click to toggle source

Moves this role above another role in the list. @param other [Role, resolve_id, nil] The role above which this role should be moved. If it is `nil`,

the role will be moved above the @everyone role.

@return [Integer] the new position of this role

# File lib/discordrb/data.rb, line 1038
def sort_above(other = nil)
  other = @server.role(other.resolve_id) if other
  roles = @server.roles.sort_by(&:position)
  roles.delete_at(@position)

  index = other ? roles.index { |role| role.id == other.id } + 1 : 1
  roles.insert(index, self)

  updated_roles = roles.map.with_index { |role, position| { id: role.id, position: position } }
  @server.update_role_positions(updated_roles)
  index
end
Also aliased as: move_above
update_data(new_data) click to toggle source

Updates the data cache from a hash containing data @note For internal use only @!visibility private

# File lib/discordrb/data.rb, line 986
def update_data(new_data)
  @name = new_data[:name] || new_data['name'] || @name
  @hoist = new_data['hoist'] unless new_data['hoist'].nil?
  @hoist = new_data[:hoist] unless new_data[:hoist].nil?
  @colour = new_data[:colour] || (new_data['color'] ? ColourRGB.new(new_data['color']) : @colour)
end
update_from(other) click to toggle source

Updates the data cache from another Role object @note For internal use only @!visibility private

# File lib/discordrb/data.rb, line 974
def update_from(other)
  @permissions = other.permissions
  @name = other.name
  @hoist = other.hoist
  @colour = other.colour
  @position = other.position
  @managed = other.managed
end
users()
Alias for: members

Private Instance Methods

update_role_data(new_data) click to toggle source
# File lib/discordrb/data.rb, line 1067
def update_role_data(new_data)
  API::Server.update_role(@bot.token, @server.id, @id,
                          new_data[:name] || @name,
                          (new_data[:colour] || @colour).combined,
                          new_data[:hoist].nil? ? @hoist : new_data[:hoist],
                          new_data[:mentionable].nil? ? @mentionable : new_data[:mentionable],
                          new_data[:permissions] || @permissions.bits)
  update_data(new_data)
end