alchemy

v0.6.0

alchemy v0.6.0 Alchemy.Embed

A module containing structs and functions relative to Embeds.

Embeds allow you to format messages in a structured, and quite pretty way; much more than can be done with simple text. For a basic idea of how embeds work, check this link.

Example Usage

Cogs.def embed do
  %Embed{}
  |> title("The BEST embed")
  |> description("the best description")
  |> image("http://i.imgur.com/4AiXzf8.jpg")
  |> Embed.send
end

Note that this is equivalent to:

Cogs.def embed do
  %Embed{title: "The BEST embed",
         description: "the best description",
         image: "http://i.imgur.com/4AiXzf8.jpg"}
  |> Embed.send
end

File Attachments

The fields that take urls can also take a special “attachment” url referencing files uploaded alongside the embed.

Cogs.def foo do
  %Embed{}
  |> image("attachment://foo.png")
  |> Embed.send("", file: "foo.png")
end

Summary

Types

attachment()

Represents a file attached to an embed

author()

Represents the author of an embed

field()

Represents a field in an embed

footer()

Represents an Embed footer

image()

Represents the image of an embed

provider()

Represents the provider of an embed

t()
thumbnail()

Represents the thumnail of an embed

url()
video()

Represents a video attached to an embed

Functions

author(embed, author)

Adds author information to an embed

color(embed, integer)

Sets the color of an embed

description(embed, string)

Adds a description to an embed

field(embed, name, value, options \\ [])

Adds a field to an embed

footer(embed, footer)

Adds a footer to an embed

image(embed, url)

Sets the main image of the embed

thumbnail(embed, url)

Adds a thumbnail to an embed

timestamp(embed, time)

Adds a timestamp to an embed

title(embed, string)

Adds a title to an embed.

Examples

Cogs.def title(string) do
  %Embed{}
  |> title(string)
  |> Embed.send
end
url(embed, url)

Sets the url for an embed

Macros

send(embed, content \\ "", options \\ [])

Sends an embed to the same channel as the message triggering a command

Types 

attachment :: %Alchemy.Attachment{filename: String.t, height: Integer | nil, id: String.t, proxy_url: url, size: Integer, url: url, width: Integer | nil}

Represents a file attached to an embed.

  • id

    The attachment id

  • filename

    The name of the file attached

  • size

    The size of the file attached

  • url

    The source url of a file

  • proxy_url

    A proxied url of a file

  • height

    The height of the file, if it’s an image

  • width

    The width of a file, if it’s an image

author :: %Alchemy.Embed.Author{icon_url: url, name: String.t, proxy_icon_url: url, url: url}

Represents the author of an embed.

  • name

    The name of the author

  • url

    The author’s url

  • icon_url

    A link to the author’s icon image

  • proxy_icon_url

    A proxied url for the author’s icon image

field :: %Alchemy.Embed.Field{inline: Boolean, name: String.t, value: String.t}

Represents a field in an embed.

  • name

    The title of the field

  • value

    The text of the field

  • inline

    Whether or not the field should be aligned with other inline fields.

footer :: %Alchemy.Embed.Footer{icon_url: url, proxy_icon_url: url, text: String.t}

Represents an Embed footer.

  • text

    The text of the footer

  • icon_url

    The url of the image in the footer

  • proxy_icon_url

    The proxied url of the footer’s icon. Setting this when sending an embed serves no purpose.

image :: %Alchemy.Embed.Image{height: Integer, proxy_url: url, url: url, width: Integer}

Represents the image of an embed.

  • url

    A link to this image

The following parameters shouldn’t be set when sending embeds:

  • proxy_url

    A proxied url of the image

  • height

    The height of the image.

  • width

    The width of the image.

provider :: %Alchemy.Embed.Provider{name: String.t, url: url}

Represents the provider of an embed.

This is usually comes from a linked resource (youtube video, etc.)

  • name

    The name of the provider

  • url

    The source of the provider

t :: %Alchemy.Embed{author: author, color: Integer, description: String.t, fields: [field], footer: footer, image: image, provider: provider, thumbnail: thumbnail, timestamp: String.t, title: String.t, type: String.t, url: String.t, video: video}
thumbnail :: %Alchemy.Embed.Thumbnail{height: Integer, proxy_url: url, url: url, width: Integer}

Represents the thumnail of an embed.

  • url

    A link to the thumbnail image.

  • proxy_url

    A proxied link to the thumbnail image

  • height

    The height of the thumbnail

  • width

    The width of the thumbnail

video :: %Alchemy.Embed.Video{height: Integer, url: url, width: Integer}

Represents a video attached to an embed.

Users can’t set this themselves.

  • url

    The source of the video

  • height

    The height of the video

  • width

    The width of the video

Functions

author(embed, author)

Specs

author(Alchemy.Embed.t, [name: String.t, url: url, icon_url: url] | Alchemy.Embed.Author.t) :: Alchemy.Embed.t

Adds author information to an embed.

Note that the proxy_icon_url, height, and width fields have no effect, when using a pre-made Author struct.

Options

  • name

    The name of the author.

  • url

    The url of the author.

  • icon_url

    The url of the icon to display.

Examples

Cogs.def embed do
  %Embed{}
  |> author(name: "John",
            url: "https://discordapp.com/developers"
            icon_url: "http://i.imgur.com/3nuwWCB.jpg")
  |> Embed.send
end
color(embed, integer)

Specs

color(Alchemy.Embed.t, Integer) :: Alchemy.Embed.t

Sets the color of an embed

Color should be 3 byte integer, with each byte representing a single color component; i.e. 0xRrGgBb

Examples

Cogs.def embed do
  {:ok, message} =
    %Embed{description: "the best embed"}
    |> color(0xc13261)
    |> Embed.send
  Process.sleep(2000)
  Client.edit_embed(message, embed |> color(0x5aa4d4))
end
description(embed, string)

Specs

description(Alchemy.Embed.t, String.t) :: Alchemy.Embed.t

Adds a description to an embed.

Cogs.def embed(description) do
  %Embed{}
  |> title("generic title")
  |> description(description)
  |> Embed.send
end
field(embed, name, value, options \\ [])

Adds a field to an embed.

Fields are appended when using this method, so the order you pipe them in, is the order they’ll end up when sent. The name and value must be non empty strings. You can have a maximum of 25 fields.

Parameters

  • name

    The title of the embed.

  • value

    The text of the field

Options

  • inline

    When setting this to true, up to 3 fields can appear side by side, given they are all inlined.

Examples

%Embed{}
|> field("Field1", "the best field!")
|> field("Inline1", "look a field ->")
|> field("Inline2", "<- look a field")
footer(embed, footer)

Specs

footer(Alchemy.Embed.t, [text: String.t, icon_url: url] | Alchemy.Embed.Footer.t) :: Alchemy.Embed.t

Adds a footer to an embed.

Note that the proxy_icon_url field has no effect, when using a pre-made Footer struct.

Options

  • text

    The content of the footer.

  • icon_url

    The icon the footer should have

Examples

Cogs.def you do
  %Embed{}
  |> footer(text: "<- this is you",
            icon_url: message.author |> User.avatar_url)
  |> Embed.send
end
image(embed, url)

Specs

image(Alchemy.Embed.t, url) :: Alchemy.Embed.t

Sets the main image of the embed.

Examples

%Embed{}
|> image("http://i.imgur.com/4AiXzf8.jpg")
thumbnail(embed, url)

Specs

thumbnail(Alchemy.Embed.t, url) :: Alchemy.Embed.t

Adds a thumbnail to an embed.

Examples

%Embed{}
|> thumbnail("http://i.imgur.com/4AiXzf8.jpg")
timestamp(embed, time)

Specs

timestamp(Alchemy.Embed.t, DateTime.t) :: DateTime.t

Adds a timestamp to an embed.

Note that the Datetime object will get converted to an iso8601 formatted string.

Examples

%Embed{} |> timestamp(DateTime.utc_now())

title(embed, string)

Specs

title(Alchemy.Embed.t, String.t) :: Alchemy.Embed.t

Adds a title to an embed.

Examples

Cogs.def title(string) do
  %Embed{}
  |> title(string)
  |> Embed.send
end
url(embed, url)

Specs

url(Alchemy.Embed.t, url) :: Alchemy.Embed.t

Sets the url for an embed.

Examples

Cogs.def embed(url) do
  %Embed{}
  |> url(url)
  |> Embed.send
end

Macros

send(embed, content \\ "", options \\ [])

Sends an embed to the same channel as the message triggering a command.

This macro can’t be used outside of Alchemy.Cogs commands.

See Alchemy.Client.send_message/3 for a list of options that can be passed to this macro.

Examples

Cogs.def blue do
  %Embed{}
  |> color(0x1d3ad1)
  |> description("Hello!")
  |> Embed.send("Here's an embed, and a file", file: "foo.txt")
end