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 



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

def colour
  @colour
end

#flags ⇒ Integer (readonly) 



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

def flags
  @flags
end

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



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

def hoist
  @hoist
end

#icon ⇒ String? 



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

def icon
  @icon
end

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



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

def managed
  @managed
end

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



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

def mentionable
  @mentionable
end

#name ⇒ String 



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

def name
  @name
end

#permissions ⇒ Permissions (readonly) 



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

def permissions
  @permissions
end

#position ⇒ Integer (readonly) 



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

def position
  @position
end

#secondary_colour ⇒ ColourRGB? Also known as: secondary_color 



49
50
51
 
# File 'lib/discordrb/data/role.rb', line 49

def secondary_colour
  @secondary_colour
end

#server ⇒ Server (readonly) 



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

def server
  @server
end

#tags ⇒ Tags? (readonly) 



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

def tags
  @tags
end

#tertiary_colour ⇒ ColourRGB? Also known as: tertiary_color 



53
54
55
 
# File 'lib/discordrb/data/role.rb', line 53

def tertiary_colour
  @tertiary_colour
end

#unicode_emoji ⇒ String? 



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

def unicode_emoji
  @unicode_emoji
end

Instance Method Details

#delete(reason = nil) ⇒ Object

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



325
326
327
328
 
# File 'lib/discordrb/data/role.rb', line 325

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.



253
254
255
 
# File 'lib/discordrb/data/role.rb', line 253

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.



260
261
262
263
264
265
266
267
268
269
270
271
 
# File 'lib/discordrb/data/role.rb', line 260

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

#gradient? ⇒ true, false

Whether or not the role has a two-point gradient.



281
282
283
 
# File 'lib/discordrb/data/role.rb', line 281

def gradient?
  !@secondary_colour.nil? && @tertiary_colour.nil?
end

#holographic=(holographic) ⇒ Object

Sets whether the role colour should be a holographic style.



226
227
228
 
# File 'lib/discordrb/data/role.rb', line 226

def holographic=(holographic)
  update_colours(holographic: holographic)
end

#holographic? ⇒ true, false

Whether or not the role is of the holographic style.



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

def holographic?
  !@tertiary_colour.nil?
end

#icon_url(format = 'webp') ⇒ String 



244
245
246
247
248
 
# File 'lib/discordrb/data/role.rb', line 244

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



358
359
360
 
# File 'lib/discordrb/data/role.rb', line 358

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.



147
148
149
 
# File 'lib/discordrb/data/role.rb', line 147

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

#mention ⇒ String 



141
142
143
 
# File 'lib/discordrb/data/role.rb', line 141

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


299
300
301
302
 
# File 'lib/discordrb/data/role.rb', line 299

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.



308
309
310
311
312
313
314
315
316
317
318
319
 
# File 'lib/discordrb/data/role.rb', line 308

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

#update_colours(primary: :undef, secondary: :undef, tertiary: :undef, holographic: :undef) ⇒ Object Also known as: update_colors

A rich interface designed to make working with role colours simple.



336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
 
# File 'lib/discordrb/data/role.rb', line 336

def update_colours(primary: :undef, secondary: :undef, tertiary: :undef, holographic: :undef)
  colours = {
    primary_color: (primary == :undef ? @colour : primary)&.to_i,
    tertiary_color: (tertiary == :undef ? @tertiary_colour : tertiary)&.to_i,
    secondary_color: (secondary == :undef ? @secondary_colour : secondary)&.to_i
  }

  holographic_colours = {
    primary_color: 11_127_295,
    tertiary_color: 16_761_760,
    secondary_color: 16_759_788
  }

  # Only set the tertiary_color to `nil` if holographic is explicitly set to false.
  colours[:tertiary_color] = nil if holographic.is_a?(FalseClass) && holographic?

  update_role_data(colours: holographic == true ? holographic_colours : colours)
end