Class: Discordrb::Role
- Inherits:
-
Object
- Object
- Discordrb::Role
- 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
-
#colour ⇒ ColourRGB
(also: #color)
The primary colour of this role.
-
#flags ⇒ Integer
readonly
The flags for this role.
-
#hoist ⇒ true, false
(also: #hoist?)
Whether or not this role should be displayed separately from other users.
-
#icon ⇒ String?
The icon hash for this role.
-
#managed ⇒ true, false
(also: #managed?)
readonly
Whether or not this role is managed by an integration or a bot.
-
#mentionable ⇒ true, false
(also: #mentionable?)
Whether this role can be mentioned using a role mention.
-
#name ⇒ String
This role's name ("new role" if it hasn't been changed).
-
#permissions ⇒ Permissions
readonly
This role's permissions.
-
#position ⇒ Integer
readonly
The position of this role in the hierarchy.
-
#secondary_colour ⇒ ColourRGB?
(also: #secondary_color)
The secondary colour of this role.
-
#server ⇒ Server
readonly
The server this role belongs to.
-
#tags ⇒ Tags?
readonly
The role tags.
-
#tertiary_colour ⇒ ColourRGB?
(also: #tertiary_color)
The tertiary colour of this role.
-
#unicode_emoji ⇒ String?
The unicode emoji of this role, or nil.
Attributes included from IDObject
Instance Method Summary collapse
-
#delete(reason = nil) ⇒ Object
Deletes this role.
-
#display_icon ⇒ String?
Get the icon that a role has displayed.
-
#display_icon=(icon) ⇒ Object
Set the icon this role is displaying.
-
#gradient? ⇒ true, false
Whether or not the role has a two-point gradient.
-
#holographic=(holographic) ⇒ Object
Sets whether the role colour should be a holographic style.
-
#holographic? ⇒ true, false
Whether or not the role is of the holographic style.
-
#icon_url(format = 'webp') ⇒ String
URL to the icon on Discord's CDN.
-
#inspect ⇒ Object
The inspect method is overwritten to give more useful output.
-
#members ⇒ Array<Member>
(also: #users)
An array of members who have this role.
-
#mention ⇒ String
A string that will mention this role, if it is mentionable.
-
#packed=(packed, update_perms = true) ⇒ Object
Changes this role's permissions to a fixed bitfield.
-
#sort_above(other = nil) ⇒ Integer
(also: #move_above)
Moves this role above another role in the list.
-
#update_colours(primary: :undef, secondary: :undef, tertiary: :undef, holographic: :undef) ⇒ Object
(also: #update_colors)
A rich interface designed to make working with role colours simple.
Methods included from IDObject
#==, #creation_time, synthesise
Instance Attribute Details
#colour ⇒ ColourRGB Also known as: color
Returns 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.
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.
18 19 20 |
# File 'lib/discordrb/data/role.rb', line 18 def hoist @hoist end |
#icon ⇒ String?
Returns 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.
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.
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).
12 13 14 |
# File 'lib/discordrb/data/role.rb', line 12 def name @name end |
#permissions ⇒ Permissions (readonly)
Returns this role's permissions.
9 10 11 |
# File 'lib/discordrb/data/role.rb', line 9 def @permissions end |
#position ⇒ Integer (readonly)
Returns 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.
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.
15 16 17 |
# File 'lib/discordrb/data/role.rb', line 15 def server @server end |
#tags ⇒ Tags? (readonly)
Returns The role tags.
40 41 42 |
# File 'lib/discordrb/data/role.rb', line 40 def @tags end |
#tertiary_colour ⇒ ColourRGB? Also known as: tertiary_color
Returns 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.
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?
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
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
Returns 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 |
#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
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
Returns 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.
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 |