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 primary colour of this role.

Returns:

  • (ColourRGB) —

    the primary colour of this role.



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

def colour
  @colour
end

#flags ⇒ Integer (readonly)

Returns The flags for this role.

Returns:

  • (Integer) —

    The flags for this role.



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

def flags
  @flags
end

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

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.



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

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



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

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



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

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



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

def position
  @position
end

#secondary_colour ⇒ ColourRGB? Also known as: secondary_color

Returns the secondary colour of this role.

Returns:

  • (ColourRGB, nil) —

    the secondary colour of this role.



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

def secondary_colour
  @secondary_colour
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.



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

def tags
  @tags
end

#tertiary_colour ⇒ ColourRGB? Also known as: tertiary_color

Returns the tertiary colour of this role.

Returns:

  • (ColourRGB, nil) —

    the tertiary colour of this role.



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

def tertiary_colour
  @tertiary_colour
end

#unicode_emoji ⇒ String?

Returns The unicode emoji of this role, or nil.

Returns:

  • (String, nil) —

    The unicode emoji of this role, or nil.



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!

Parameters:

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

    the reason for this role's deletion



290
291
292
293
 
# File 'lib/discordrb/data/role.rb', line 290

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.



236
237
238
 
# File 'lib/discordrb/data/role.rb', line 236

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.



243
244
245
 
# File 'lib/discordrb/data/role.rb', line 243

def display_icon=(icon)
  modify(display_icon: icon)
end

#gradient? ⇒ true, false

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

Returns:

  • (true, false) 


255
256
257
 
# File 'lib/discordrb/data/role.rb', line 255

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

#holographic=(holographic) ⇒ Object

Sets whether the role colour should be a holographic style.

Parameters:

  • holographic (true, false) —

    whether the role colour should be a holographic style.



211
212
213
 
# File 'lib/discordrb/data/role.rb', line 211

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

#holographic? ⇒ true, false

Whether or not the role is of the holographic style.

Returns:

  • (true, false) 


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

def holographic?
  !@tertiary_colour.nil?
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.



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

def icon_url(format = 'webp')
  API.role_icon_url(@id, @icon, format) if @icon
end

#inspect ⇒ Object

The inspect method is overwritten to give more useful output



445
446
447
 
# File 'lib/discordrb/data/role.rb', line 445

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.



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

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.



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

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

#modify(name: :undef, mentionable: :undef, hoist: :undef, unicode_emoji: :undef, icon: :undef, display_icon: :undef, color: :undef, colour: :undef, secondary_color: :undef, secondary_colour: :undef, tertiary_color: :undef, tertiary_colour: :undef, permissions: :undef, reason: nil) {|builder| ... } ⇒ nil

Modify the properties of the role.

Parameters:

  • name (String, nil) (defaults to: :undef) —

    The new 1-100 character name of the role.

  • mentionable (true, false, nil) (defaults to: :undef) —

    Whether or not anyone should be able to ping the role.

  • hoist (true, false, nil) (defaults to: :undef) —

    Whether or not members who have the role should be shown seperately in the sidebar.

  • unicode_emoji (String, nil) (defaults to: :undef) —

    The new unicode emoji to set as the role's icon.

  • icon (#read, File, nil) (defaults to: :undef) —

    The new custom icon of the role. Must be a file-like object that responds to #read.

  • display_icon (String, #read, File, nil) (defaults to: :undef) —

    The new display icon of the role. Mutually exclusive with icon: and unicode_emoji:.

  • colour (ColourRGB, Integer, nil) (defaults to: :undef) —

    The new primary colour of the role. Can also be passed as color:.

  • secondary_colour (ColourRGB, Integer, nil) (defaults to: :undef) —

    The new secondary colour of the role. Can also be passed as secondary_color:.

  • tertiary_colour (ColourRGB, Integer, nil) (defaults to: :undef) —

    The new tertiary colour of the role. Can also be passed as tertiary_color:.

  • permissions (String, Integer, nil) (defaults to: :undef) —

    The new permissions to set for the role.

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

    The reason to show in the server's audit log for modifying the role.

Yield Parameters:

  • builder (Permissions) —

    An optional permissions builder. Arguments passed to the method overwrite builder data.

Returns:

  • (nil) 


390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
 
# File 'lib/discordrb/data/role.rb', line 390

def modify(
  name: :undef, mentionable: :undef, hoist: :undef, unicode_emoji: :undef, icon: :undef,
  display_icon: :undef, color: :undef, colour: :undef, secondary_color: :undef,
  secondary_colour: :undef, tertiary_color: :undef, tertiary_colour: :undef,
  permissions: :undef, reason: nil
)
  if display_icon != :undef
    if icon != :undef || unicode_emoji != :undef
      raise ArgumentError, "'display_icon' is mutually exclusive with 'icon' and 'unicode_emoji'"
    end

    if display_icon.nil?
      icon = nil
      unicode_emoji = nil
    elsif display_icon.is_a?(String)
      icon = nil
      unicode_emoji = display_icon
    elsif display_icon.respond_to?(:read)
      icon = display_icon
      unicode_emoji = nil
    end
  end

  if block_given? && permissions == :undef
    yield((builder = Permissions.new(@permissions.bits)))
    permissions = builder.bits
  end

  data = {
    name: name,
    mentionable: mentionable,
    hoist: hoist,
    unicode_emoji: unicode_emoji,
    icon: icon.respond_to?(:read) ? Discordrb.encode64(icon) : icon,
    permissions: permissions == :undef ? permissions : permissions&.to_s,
    reason: reason
  }

  color = (colour == :undef ? color : colour)
  tertiary = (tertiary_colour == :undef ? tertiary_color : tertiary_colour)
  secondary = (secondary_colour == :undef ? secondary_color : secondary_colour)

  if color != :undef || secondary != :undef || tertiary != :undef
    data[:colors] = {
      primary_color: (color == :undef ? @colour : color)&.to_i,
      tertiary_color: (tertiary == :undef ? @tertiary_colour : tertiary)&.to_i,
      secondary_color: (secondary == :undef ? @secondary_colour : secondary)&.to_i
    }
  end

  update_data(JSON.parse(API::Server.update_role!(@bot.token, @server.id, @id, **data)))
  nil
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 @moderator role.

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

Parameters:

  • bottom (true, false, nil) (defaults to: nil) —

    Whether to move the roles to the bottom of the role list.

  • above (Integer, String, Role, nil) (defaults to: nil) —

    The role that this role should be moved above.

  • below (Integer, String, Role, nil) (defaults to: nil) —

    The role that this role should be moved below.

  • offset (Integer, nil) (defaults to: 0) —

    The number of roles to offset the new position by. A positive number will move the role above, and a negative number will move the role below. This parameter is relative and calculated after the bottom, above, and below parameters.

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

    The audit log reason to show for moving the role.

Returns:

  • (Integer) —

    The new position of the role.



310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
 
# File 'lib/discordrb/data/role.rb', line 310

def move(bottom: nil, above: nil, below: nil, offset: 0, reason: nil)
  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

  roles = @server.roles.sort_by { |role| [role.position, role.id] }

  # Make sure we remove the current role.
  myself = roles.rindex(@id).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=(permissions, _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:

  • permissions (Integer, nil) —

    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. This is deprecated and no longer functional. Permissions data is always updated.



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

def packed=(permissions, _update_perms = true)
  modify(permissions: permissions)
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.

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



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

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.

Parameters:

  • primary (ColourRGB, Integer, nil) (defaults to: :undef) —

    The new primary/base colour of this role, or nil to clear the primary colour.

  • secondary (ColourRGB, Integer, nil) (defaults to: :undef) —

    The new secondary colour of this role, or nil to clear the secondary colour.

  • tertiary (ColourRGB, Integer, nil) (defaults to: :undef) —

    The new tertiary colour of this role, or nil to clear the tertiary colour.

  • holographic (true, false) (defaults to: :undef) —

    Whether to apply or remove the holographic style to the role colour, overriding any other arguments that were passed. Using this argument is recommended over passing individual colours.

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

    The audit log reason to show for updating the role's colours.



355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
 
# File 'lib/discordrb/data/role.rb', line 355

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

  modify(reason: reason, **(holographic ? holographic_colours : colours))
end