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



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.

Returns:

  • (String, nil) —

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



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.

Parameters:

  • icon (File, String, nil) —

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



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.

Returns:

  • (true, false) 


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.

Parameters:

  • holographic (true, false) —

    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.

Returns:

  • (true, false) 


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

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.



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.

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

#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)

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.



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

Parameters:

  • packed (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.



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.

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



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.

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.



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