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

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

#flagsInteger (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

#hoisttrue, 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

#iconString?

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

#managedtrue, 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

#mentionabletrue, 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

#nameString

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

#permissionsPermissions (readonly)

Returns this role's permissions.

Returns:



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

def permissions
  @permissions
end

#positionInteger (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_colourColourRGB? 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

#serverServer (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

#tagsTags? (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_colourColourRGB? 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_emojiString?

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



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_iconString?

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.



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.

Parameters:

  • icon (File, String, nil)

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



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.

Returns:

  • (true, false)


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.

Parameters:

  • holographic (true, false)

    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.

Returns:

  • (true, false)


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

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.



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

#inspectObject

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

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

#mentionString

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

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



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.

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



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.

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.



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