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

icon[R]

@return [String, nil] The icon hash for this role.

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

tags[R]

@return [Tags, nil] The role tags

Public Class Methods

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

@!visibility private

# File lib/discordrb/data/role.rb, line 92
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'])

  @icon = data['icon']

  @tags = Tags.new(data['tags']) if data['tags']
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/role.rb, line 168
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/role.rb, line 224
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/role.rb, line 156
def hoist=(hoist)
  update_role_data(hoist: hoist)
end
icon=(file) click to toggle source

Upload a role icon for servers with the ROLE_ICONS feature. @param file [File]

# File lib/discordrb/data/role.rb, line 174
def icon=(file)
  update_role_data(icon: file)
end
icon_url(format = 'webp') click to toggle source

@param format [‘webp’, ‘png’, ‘jpeg’] @return [String] URL to the icon on Discord’s CDN.

# File lib/discordrb/data/role.rb, line 180
def icon_url(format = 'webp')
  return nil unless @icon

  Discordrb::API.role_icon_url(@id, @icon, format)
end
inspect() click to toggle source

The inspect method is overwritten to give more useful output

# File lib/discordrb/data/role.rb, line 230
def inspect
  "<Role name=#{@name} permissions=#{@permissions.inspect} hoist=#{@hoist} colour=#{@colour.inspect} server=#{@server.inspect} position=#{@position} mentionable=#{@mentionable}>"
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/role.rb, line 119
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/role.rb, line 113
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/role.rb, line 162
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/role.rb, line 150
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 discord.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/role.rb, line 198
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, String, Integer, nil] The role, or its ID, 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/role.rb, line 207
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/role.rb, line 141
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/role.rb, line 128
def update_from(other)
  @permissions = other.permissions
  @name = other.name
  @hoist = other.hoist
  @colour = other.colour
  @position = other.position
  @managed = other.managed
  @icon = other.icon
end
users()
Alias for: members

Private Instance Methods

update_role_data(new_data) click to toggle source
# File lib/discordrb/data/role.rb, line 236
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,
                          nil,
                          new_data.key?(:icon) ? new_data[:icon] : :undef)
  update_data(new_data)
end