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!



321
322
323
324
 
# File 'lib/discordrb/data/role.rb', line 321

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.



257
258
259
 
# File 'lib/discordrb/data/role.rb', line 257

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.



264
265
266
267
268
269
270
271
272
273
274
275
 
# File 'lib/discordrb/data/role.rb', line 264

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.



285
286
287
 
# File 'lib/discordrb/data/role.rb', line 285

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

#holographic=(holographic) ⇒ Object

Sets whether the role colour should be a holographic style.



230
231
232
 
# File 'lib/discordrb/data/role.rb', line 230

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

#holographic? ⇒ true, false

Whether or not the role is of the holographic style.



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

def holographic?
  !@tertiary_colour.nil?
end

#icon_url(format = 'webp') ⇒ String 



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

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



410
411
412
 
# File 'lib/discordrb/data/role.rb', line 410

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

#move(bottom: nil, above: nil, below: nil, offset: 0, reason: nil) ⇒ Integer

Move the position of this role in the roles list.

Examples:

This will move the role 2 places above the @everyone role.

role.move(bottom: true, offset: 2)

This will move the role above the @muted role.

role.move(above: 257017090932867072)

This will move the role 3 spots below the No Images role.

roles.move(below: 254077236989132800, offset: -3)



341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
 
# File 'lib/discordrb/data/role.rb', line 341

def move(bottom: nil, above: nil, below: nil, offset: 0, reason: nil)
  # rubocop:disable Style/IfUnlessModifier
  if [bottom, above, below].count(&:itself) > 1
    raise ArgumentError, "'bottom', 'above', and 'below' are mutually exclusive"
  end

  if (above || below) && !(target = @server.role(above || below))
    raise ArgumentError, "The given 'above' or 'below' options are not valid"
  end

  if (below && target&.id == @server.id) || (@id == target&.id)
    raise ArgumentError, 'The target role that was provded is not valid'
  end

  # rubocop:enable Style/IfUnlessModifier
  roles = @server.roles.uniq.sort_by { |role| [role.position, role.id] }

  # Make sure we remove the current role.
  myself = roles.rindex(self).tap { |index| roles.delete_at(index) }

  index = if bottom
            1
          elsif below
            roles.rindex(target)
          elsif above
            roles.rindex(target) + 1
          else
            myself
          end

  roles.insert([index + (offset || 0), 1].max, self)

  roles = roles.map.with_index do |role, new_position|
    { id: role.resolve_id, position: new_position }
  end

  @server.update_role_positions(roles, reason: reason)
  @position
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



303
304
305
306
 
# File 'lib/discordrb/data/role.rb', line 303

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

Deprecated.

Please migrate to using #move with the above or below KWARGS.

Moves this role above another role in the list.



313
314
315
 
# File 'lib/discordrb/data/role.rb', line 313

def sort_above(other = nil)
  other ? move(above: other) : move(bottom: true)
end

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

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



388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
 
# File 'lib/discordrb/data/role.rb', line 388

def update_colours(primary: :undef, secondary: :undef, tertiary: :undef, holographic: :undef, reason: nil)
  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)

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