Class: Discordrb::Role

Inherits:
Object
  • Object
show all
Includes:
IDObject
Defined in:
lib/discordrb/data/role.rb

Overview

A Discord role that contains permissions and applies to certain users

Defined Under Namespace

Classes: RoleWriter, Tags

Instance Attribute Summary collapse

Attributes included from IDObject

#id

Instance Method Summary collapse

Methods included from IDObject

#==, #creation_time, synthesise

Instance Attribute Details

#colour ⇒ ColourRGB Also known as: color

Returns the role colour.

Returns:



29
30
31
 
# File 'lib/discordrb/data/role.rb', line 29

def colour
  @colour
end

#flags ⇒ Integer (readonly)

Returns The flags for this role.

Returns:

  • (Integer) —

    The flags for this role.



42
43
44
 
# File 'lib/discordrb/data/role.rb', line 42

def flags
  @flags
end

#hoist ⇒ true, false

Returns whether or not this role should be displayed separately from other users.

Returns:

  • (true, false) —

    whether or not this role should be displayed separately from other users



18
19
20
 
# File 'lib/discordrb/data/role.rb', line 18

def hoist
  @hoist
end

#icon ⇒ String?

Returns The icon hash for this role.

Returns:

  • (String, nil) —

    The icon hash for this role.



36
37
38
 
# File 'lib/discordrb/data/role.rb', line 36

def icon
  @icon
end

#managed ⇒ true, false (readonly) Also known as: managed?

Returns whether or not this role is managed by an integration or a bot.

Returns:

  • (true, false) —

    whether or not this role is managed by an integration or a bot



21
22
23
 
# File 'lib/discordrb/data/role.rb', line 21

def managed
  @managed
end

#mentionable ⇒ true, false Also known as: mentionable?

Returns whether this role can be mentioned using a role mention.

Returns:

  • (true, false) —

    whether this role can be mentioned using a role mention



25
26
27
 
# File 'lib/discordrb/data/role.rb', line 25

def mentionable
  @mentionable
end

#name ⇒ String

Returns this role's name ("new role" if it hasn't been changed).

Returns:

  • (String) —

    this role's name ("new role" if it hasn't been changed)



12
13
14
 
# File 'lib/discordrb/data/role.rb', line 12

def name
  @name
end

#permissions ⇒ Permissions (readonly)

Returns this role's permissions.

Returns:



9
10
11
 
# File 'lib/discordrb/data/role.rb', line 9

def permissions
  @permissions
end

#position ⇒ Integer (readonly)

Returns the position of this role in the hierarchy.

Returns:

  • (Integer) —

    the position of this role in the hierarchy



33
34
35
 
# File 'lib/discordrb/data/role.rb', line 33

def position
  @position
end

#server ⇒ Server (readonly)

Returns the server this role belongs to.

Returns:

  • (Server) —

    the server this role belongs to



15
16
17
 
# File 'lib/discordrb/data/role.rb', line 15

def server
  @server
end

#tags ⇒ Tags? (readonly)

Returns The role tags.

Returns:

  • (Tags, nil) —

    The role tags.



39
40
41
 
# File 'lib/discordrb/data/role.rb', line 39

def tags
  @tags
end

#unicode_emoji ⇒ String?

Returns The unicode emoji of this role, or nil.

Returns:

  • (String, nil) —

    The unicode emoji of this role, or nil.



45
46
47
 
# File 'lib/discordrb/data/role.rb', line 45

def unicode_emoji
  @unicode_emoji
end

Instance Method Details

#delete(reason = nil) ⇒ Object

Deletes this role. This cannot be undone without recreating the role!

Parameters:

  • reason (String) (defaults to: nil) —

    the reason for this role's deletion



273
274
275
276
 
# File 'lib/discordrb/data/role.rb', line 273

def delete(reason = nil)
  API::Server.delete_role(@bot.token, @server.id, @id, reason)
  @server.delete_role(@id)
end

#display_icon ⇒ String?

Note:

A role can have a unicode emoji, and an icon, but only the icon will be shown in the UI.

Get the icon that a role has displayed.

Returns:

  • (String, nil) —

    Icon URL, the unicode emoji, or nil if this role doesn't have any icon.



215
216
217
 
# File 'lib/discordrb/data/role.rb', line 215

def display_icon
  icon_url || unicode_emoji
end

#display_icon=(icon) ⇒ Object

Note:

Setting the icon to nil will remove the unicode emoji and the custom icon.

Set the icon this role is displaying.

Parameters:

  • icon (File, String, nil) —

    File like object that responds to #read, unicode emoji, or nil.



222
223
224
225
226
227
228
229
230
231
232
233
 
# File 'lib/discordrb/data/role.rb', line 222

def display_icon=(icon)
  if icon.nil?
    update_role_data(unicode_emoji: nil, icon: nil)
    return
  end

  if icon.respond_to?(:read)
    update_role_data(unicode_emoji: nil, icon: icon)
  else
    update_role_data(unicode_emoji: icon, icon: nil)
  end
end

#icon_url(format = 'webp') ⇒ String

Returns URL to the icon on Discord's CDN.

Parameters:

  • format ('webp', 'png', 'jpeg') (defaults to: 'webp')

Returns:

  • (String) —

    URL to the icon on Discord's CDN.



206
207
208
209
210
 
# File 'lib/discordrb/data/role.rb', line 206

def icon_url(format = 'webp')
  return nil unless @icon

  Discordrb::API.role_icon_url(@id, @icon, format)
end

#inspect ⇒ Object

The inspect method is overwritten to give more useful output



279
280
281
 
# File 'lib/discordrb/data/role.rb', line 279

def inspect
  "<Role name=#{@name} permissions=#{@permissions.inspect} hoist=#{@hoist} colour=#{@colour.inspect} server=#{@server.inspect} position=#{@position} mentionable=#{@mentionable} unicode_emoji=#{@unicode_emoji} flags=#{@flags}>"
end

#members ⇒ Array<Member> Also known as: users

Note:

This requests a member chunk if it hasn't for the server before, which may be slow initially

Returns an array of members who have this role.

Returns:

  • (Array<Member>) —

    an array of members who have this role.



134
135
136
 
# File 'lib/discordrb/data/role.rb', line 134

def members
  @server.members.select { |m| m.role? self }
end

#mention ⇒ String

Returns a string that will mention this role, if it is mentionable.

Returns:

  • (String) —

    a string that will mention this role, if it is mentionable.



128
129
130
 
# File 'lib/discordrb/data/role.rb', line 128

def mention
  "<@&#{@id}>"
end

#packed=(packed, update_perms = true) ⇒ Object

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 https://discord.com/developers/docs/topics/permissions.

Examples:

Remove all permissions from a role

role.packed = 0

Parameters:

  • packed (Integer) —

    A bitfield with the desired permissions value.

  • update_perms (true, false) (defaults to: true) —

    Whether the internal data should also be updated. This should always be true when calling externally.



247
248
249
250
 
# File 'lib/discordrb/data/role.rb', line 247

def packed=(packed, update_perms = true)
  update_role_data(permissions: packed)
  @permissions.bits = packed if update_perms
end

#sort_above(other = nil) ⇒ Integer Also known as: move_above

Moves this role above another role in the list.

Parameters:

  • other (Role, String, Integer, nil) (defaults to: 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.

Returns:

  • (Integer) —

    the new position of this role



256
257
258
259
260
261
262
263
264
265
266
267
 
# File 'lib/discordrb/data/role.rb', line 256

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