EDA.Role (EDA v0.4.0)

@type t() :: %EDA.Role{
  color: integer() | nil,
  colors: EDA.Role.Colors.t() | nil,
  hoist: boolean() | nil,
  icon: String.t() | nil,
  id: String.t() | nil,
  managed: boolean() | nil,
  mentionable: boolean() | nil,
  name: String.t() | nil,
  permissions: String.t() | nil,
  position: integer() | nil,
  tags: map() | nil,
  unicode_emoji: String.t() | nil
}

Functions

apply_changeset(guild_id, changeset, opts \\ [])

@spec apply_changeset(String.t() | integer(), EDA.Entity.Changeset.t(), keyword()) ::
  {:ok, t()} | {:error, term()}

Applies a changeset to a role. No-op if the changeset has no changes.

Requires guild_id since roles are guild-scoped.

Options

:reason - Audit log reason

change(cs, key, value)

@spec change(EDA.Entity.Changeset.t(), atom(), term()) :: EDA.Entity.Changeset.t()

Adds a change to an existing changeset for this entity.

changeset(entity)

@spec changeset(t()) :: EDA.Entity.Changeset.t()

Creates a changeset for batching mutations to this entity.

create(guild_id, params \\ [], opts \\ [])

@spec create(String.t() | integer(), keyword() | map(), keyword()) ::
  {:ok, t()} | {:error, term()}

Creates a role in a guild.

Options

:reason - Audit log reason

default?(role)

@spec default?(t()) :: boolean()

Returns true when the role has no colour of its own.

Examples

iex> EDA.Role.default?(%EDA.Role{colors: %EDA.Role.Colors{primary_color: 0}})
true

iex> EDA.Role.default?(%EDA.Role{colors: %EDA.Role.Colors{primary_color: 1}})
false

delete(guild_id, role, opts \\ [])

@spec delete(String.t() | integer(), t() | String.t() | integer(), keyword()) ::
  :ok | {:error, term()}

Deletes a guild role.

Options

:reason - Audit log reason

fetch_role(guild_id, role_id)

@spec fetch_role(String.t() | integer(), String.t() | integer()) ::
  {:ok, t()} | {:error, term()}

Fetches a role by guild ID and role ID. Checks cache first, falls back to REST.

from_raw(raw)

@spec from_raw(map()) :: t()

gradient?(role)

@spec gradient?(t()) :: boolean()

Returns true when the role uses a two-colour gradient.

Not true for holographic roles — use holographic?/1 for those. Discord treats the two as distinct styles, as do JDA and discord.js.

Examples

iex> EDA.Role.gradient?(%EDA.Role{colors: %EDA.Role.Colors{primary_color: 1, secondary_color: 2}})
true

iex> EDA.Role.gradient?(%EDA.Role{colors: EDA.Role.Colors.holographic()})
false

iex> EDA.Role.gradient?(%EDA.Role{color: 1})
false

holographic?(role)

@spec holographic?(t()) :: boolean()

Returns true when the role uses the holographic style.

Examples

iex> EDA.Role.holographic?(%EDA.Role{colors: EDA.Role.Colors.holographic()})
true

iex> EDA.Role.holographic?(%EDA.Role{color: 1})
false

mention(role)

@spec mention(t()) :: String.t()

Returns a mention string like <@&id>.

modify(guild_id, role, payload, opts \\ [])

@spec modify(String.t() | integer(), t() | String.t() | integer(), map(), keyword()) ::
  {:ok, t()} | {:error, term()}

Modifies a guild role.

Options

:reason - Audit log reason

primary_color(role)

@spec primary_color(t()) :: integer() | nil

The role's primary colour, preferring the newer colors object.

Discord deprecated the single color field in favour of colors; on a real guild the two agreed, but colors.primary_color is the field to trust. Falls back to color when colors is absent.

Examples

iex> EDA.Role.primary_color(%EDA.Role{color: 1, colors: %EDA.Role.Colors{primary_color: 2}})
2

iex> EDA.Role.primary_color(%EDA.Role{color: 1})
1

set_colors(guild_id, role, colors, opts \\ [])

@spec set_colors(
  String.t() | integer(),
  t() | String.t() | integer(),
  EDA.Role.Colors.t() | map(),
  keyword()
) :: {:ok, t()} | {:error, term()}

Sets this role's colours, returning the updated %EDA.Role{}.

Accepts a role struct or a role ID, like modify/4.

Options

:reason — audit log reason

Examples

EDA.Role.set_colors(guild_id, role, EDA.Role.Colors.gradient(0xFF0000, 0x00FF00))
EDA.Role.set_colors(guild_id, role_id, EDA.Role.Colors.holographic())

style(role)

@spec style(t()) :: EDA.Role.Colors.style()

The role's colour style: :default, :solid, :gradient or :holographic.

A role with no colour of its own is :default, not :solid — 39% of roles on real guilds are in that state. See EDA.Role.Colors.

Examples

iex> EDA.Role.style(%EDA.Role{colors: %EDA.Role.Colors{primary_color: 1, secondary_color: 2}})
:gradient

iex> EDA.Role.style(%EDA.Role{colors: %EDA.Role.Colors{primary_color: 1}})
:solid

iex> EDA.Role.style(%EDA.Role{color: 1})
:default