Class: Discordrb::Role

Inherits:
Object
  • Object
show all
Includes:
IDObject
Defined in:
lib/discordrb/data.rb

Overview

A Discord role that contains permissions and applies to certain users

Defined Under Namespace

Classes: RoleWriter

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 role colour.

Returns:


908
909
910
# File 'lib/discordrb/data.rb', line 908

def colour
  @colour
end

#hoisttrue, false

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


897
898
899
# File 'lib/discordrb/data.rb', line 897

def hoist
  @hoist
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


900
901
902
# File 'lib/discordrb/data.rb', line 900

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


904
905
906
# File 'lib/discordrb/data.rb', line 904

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)


891
892
893
# File 'lib/discordrb/data.rb', line 891

def name
  @name
end

#permissionsPermissions (readonly)

Returns this role's permissions.

Returns:


888
889
890
# File 'lib/discordrb/data.rb', line 888

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


912
913
914
# File 'lib/discordrb/data.rb', line 912

def position
  @position
end

#serverServer (readonly)

Returns the server this role belongs to.

Returns:

  • (Server)

    the server this role belongs to


894
895
896
# File 'lib/discordrb/data.rb', line 894

def server
  @server
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


1048
1049
1050
1051
# File 'lib/discordrb/data.rb', line 1048

def delete(reason = nil)
  API::Server.delete_role(@bot.token, @server.id, @id, reason)
  @server.delete_role(@id)
end

#inspectObject

The inspect method is overwritten to give more useful output


1054
1055
1056
# File 'lib/discordrb/data.rb', line 1054

def inspect
  "<Role name=#{@name} permissions=#{@permissions.inspect} hoist=#{@hoist} colour=#{@colour.inspect} server=#{@server.inspect}>"
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.


958
959
960
# File 'lib/discordrb/data.rb', line 958

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.


952
953
954
# File 'lib/discordrb/data.rb', line 952

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://discordapp.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.


1022
1023
1024
1025
# File 'lib/discordrb/data.rb', line 1022

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, #resolve_id, nil) (defaults to: nil)

    The role 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


1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
# File 'lib/discordrb/data.rb', line 1031

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