discorddgo

package module
v0.0.0-...-9575f2a Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 25, 2017 License: MIT Imports: 10 Imported by: 0

README

discord.go

discord.go is a wrapper for bwmarrin/discordgo to enable a few "oh that's neat" functions.

d.g is heavily context-based and focues on bot development.

The goal is that all functionality a bot might need is provided out of the box and can be used without having to think about the discord API.

How to create a bot

A bot is easily created with d.g

Here is an example:

package main

import ddg "go.rls.moe/d.g"

func main() {
    bot, err := ddg.NewBot("<your token>")
    if err != nil {
        println(err)
        return
    }

    bot.SetSink(ddg.NewSimpleMessageHandler(handler))

    bot.BlockForExit()
}

func handler(c ddg.Context, ch *ddg.Channel, m *ddg.Message) error {
    if m.FromMe() {
        return nil
    }

    if m.DisplayText() == "ping" {
        m.Respond("pong")
    }

    if m.DisplayText() == "exit" {
        c.RequestExit()
    }

    return nil
}

Refer to the godoc documentation for further information.

(The Documentation is still being worked on, the library is still under development)

Project Goals

This library aims to completely wrap discordgo.

The first step is to wrap some read-only functionality and some basic response methods to allow bots interacting with the chat.

The second step is to implement all management methods so that easy functions exist to assign roles, ban users or create channels.

The application using this library should not have to come in contact with any discordgo types but the library should also provide access to the underlying session so they can use the original discordgo package if needed.

Contributing

Please file issues if you find a bug or have a feature request.

At the moment this project lacks basic tests, which hopefully can be added at some point, but they are not a priority, pull requests for them are welcome however.

Code Mirrors

This repository originates on git.timschuster.info/tscs37/discord.go

There is a code mirror on Github

To go-get the code use go.rls.moe/d.g.

Thanks

To the GopherPit project for providing a go-gettable vanity service.

To bwmarrin for writting an excellent Discord API.

Documentation

Overview

discord.go is a wrapper for bwmarrin/discordgo to enable a few "oh that's neat" functions.

d.g is heavily context-based and focues on bot development.

The goal is that all functionality a bot might need is provided out of the box and can be used without having to think about the discord API.

To start a new bot, simply call NewBot with the token for your bot and you're basically good to go.

An example bot is provided in example/helloworld

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func EnableDebug 

func EnableDebug()

EnableDebug will call EnableLogging and then set the highest logging level. Use this to see what might go wrong under the hood.

func EnableLogging 

func EnableLogging()

EnableLogging enables default Level logging. The Logging Level is not reset

func ResetLogLevel 

func ResetLogLevel()

ResetLogLevel returns the logger to Warn messages or higher.

func SetLogOutput 

func SetLogOutput(output io.Writer)

SetLogOutput will set the log output to the given io.Writer. It will not enable logging and if it was already enabled, EnableLogging **MUST** be called again otherwise it will continue to output on the previous io.Writer.

Types

type Bot 

type Bot struct {
	// contains filtered or unexported fields
}

A bot is a running discord session intended for usage with a Bot-type Login

func NewBot 

func NewBot(token string) (*Bot, error)

NewBot uses the given token to log into discord and return a Bot-type session.

The "Bot " authorization string is automatically appended if not found.

func (*Bot) BlockForExit 

func (b *Bot) BlockForExit()

BlockForExit will block on the exit channel of the bot. Any code that has access to the application context can unblock this method, which usually means exiting the application. Exiting the entire application is not enforced, this function only blocks, so it may be used to restart the bot too.

func (*Bot) CurrentContext 

func (b *Bot) CurrentContext() Context

CurrentContext returns the current context pointer.

func (*Bot) GetDiscordgoSession 

func (b *Bot) GetDiscordgoSession() *discordgo.Session

GetDiscordgoSession returns the underlying session the bot instance is using. This is not recommended unless the functionality you want to use is not implemented on d.g yet.

func (*Bot) Me 

func (b *Bot) Me() (*User, error)

Me returns the current bot user (using @me) or an error.

func (*Bot) SetAvatarFromFile 

func (b *Bot) SetAvatarFromFile(file string) error

SetAvatarFromFile will read the file and set it as avatar

func (*Bot) SetAvatarFromReader 

func (b *Bot) SetAvatarFromReader(image io.Reader) error

SetAvatarFromReader will read the given io.Reader and set the content as avatar

Remember to close the reader after use if applicable.

func (*Bot) SetAvatarFromURI 

func (b *Bot) SetAvatarFromURI(uri string) error

SetAvatarFromURI will download the URI data and set it as avatar

func (*Bot) SetSink 

func (b *Bot) SetSink(ev EventSink)

SetSink sets the EventSink to be used by D.G

func (*Bot) Sink 

func (b *Bot) Sink() EventSink

Sink returns the current EventSink

This may be used by plugins to dispatch custom events.

type Channel 

type Channel struct {
	// contains filtered or unexported fields
}

Channel wraps a channel with context

func (*Channel) Guild 

func (c *Channel) Guild() (*Guild, error)

Guild returns the Discord Guild the channel belongs to

func (*Channel) ID 

func (c *Channel) ID() string

ID returns the Guild ID

func (*Channel) MessageFromId 

func (c *Channel) MessageFromId(id string) (*Message, error)

func (*Channel) Write 

func (c *Channel) Write(message string) (*Message, error)

Write sends the message string to a channel

type Context 

type Context struct {
	// contains filtered or unexported fields
}

Context represents a particular Discord Session. It is available to all objects it spawns. If operating a user, it will usually contain a context and give all objects it creates the context too. This allows to access the DiscordSession from everywhere, thus allowing to use any method of a type in any code context.

An example would be to ban a user that has a mention in a message received. Simply retrieve the mention, get the user object from this mention and call the Ban() method on the user.

func (Context) ChannelFromID 

func (c Context) ChannelFromID(id string) (*Channel, error)

ChannelFromID converts a ChannelID to a Channel instance or returns an error

func (Context) GuildFromID 

func (c Context) GuildFromID(id string) (*Guild, error)

GuildFromID converts a GuildID to a Guild instance or return an error

func (Context) InviteFromID 

func (c Context) InviteFromID(id string) (*Invite, error)

InviteFromID converts a InviteID to an Invite instance or returns an error

func (Context) RequestExit 

func (c Context) RequestExit()

RequestExit will send a value to the exit channel. If your bot is blocking on BlockForExit() it will return from this function. Beware that this function will block if the bot is not waiting on it.

func (Context) RoleFromID 

func (c Context) RoleFromID(gid, id string) (*Role, error)

func (Context) Self 

func (c Context) Self() *User

Self returns the Context user. If the context has no user, it panics.

func (Context) UserFromID 

func (c Context) UserFromID(id string) (*User, error)

UserFromID converts a UserID to a User instance or returns an error

type Emoji 

type Emoji struct {
	// contains filtered or unexported fields
}

func (*Emoji) Managed 

func (e *Emoji) Managed() bool

func (*Emoji) Name 

func (e *Emoji) Name() string

func (*Emoji) String 

func (e *Emoji) String() string

type Event 

type Event interface {
	Name() string
	Context() Context
}

type EventMessageUpdate 

type EventMessageUpdate struct {
	// contains filtered or unexported fields
}

func (*EventMessageUpdate) Channel 

func (n *EventMessageUpdate) Channel() (*Channel, error)

func (EventMessageUpdate) Context 

func (n EventMessageUpdate) Context() Context

func (EventMessageUpdate) Message 

func (n EventMessageUpdate) Message() *Message

func (EventMessageUpdate) Name 

func (n EventMessageUpdate) Name() string

type EventNewMessage 

type EventNewMessage struct {
	// contains filtered or unexported fields
}

func (*EventNewMessage) Channel 

func (n *EventNewMessage) Channel() (*Channel, error)

func (EventNewMessage) Context 

func (n EventNewMessage) Context() Context

func (*EventNewMessage) Message 

func (n *EventNewMessage) Message() *Message

func (EventNewMessage) Name 

func (n EventNewMessage) Name() string

type EventSink 

type EventSink interface {
	Dispatch(event Event) error
}

EventSink is a target for sending events

func NewSimpleMessageHandler 

func NewSimpleMessageHandler(f func(Context, *Channel, *Message) error) EventSink

NewSimpleMessageHandler accepts a simple message handler and returns an EventSink

type EventUserTyping 

type EventUserTyping struct {
	// contains filtered or unexported fields
}

func (EventUserTyping) Channel 

func (n EventUserTyping) Channel() (*Channel, error)

func (EventUserTyping) Context 

func (n EventUserTyping) Context() Context

func (EventUserTyping) Name 

func (n EventUserTyping) Name() string

func (EventUserTyping) User 

func (n EventUserTyping) User() (*User, error)

type Guild 

type Guild struct {
	// contains filtered or unexported fields
}

func (*Guild) Channels 

func (g *Guild) Channels() []*Channel

func (*Guild) ID 

func (g *Guild) ID() string

func (*Guild) Icon 

func (g *Guild) Icon() string

func (*Guild) Members 

func (g *Guild) Members() []*Member

func (*Guild) Roles 

func (g *Guild) Roles() []*Role

type Invite 

type Invite struct {
	// contains filtered or unexported fields
}

func (*Invite) Accept 

func (i *Invite) Accept() error

func (*Invite) Channel 

func (i *Invite) Channel() *Channel

func (*Invite) Guild 

func (i *Invite) Guild() *Guild

type Member 

type Member struct {
	// contains filtered or unexported fields
}

func (*Member) Ban 

func (m *Member) Ban() error

Ban will create a ban for a member or return an error

func (*Member) BanAndDeleteMessages 

func (m *Member) BanAndDeleteMessages(days int) error

BanAndDeleteMessages will create a ban and also delete messages of the past days, specified by the days parameter, or return an error.

func (*Member) Guild 

func (m *Member) Guild() (*Guild, error)

Guild returns the Guild the member belongs to or an error

func (*Member) HasRole 

func (m *Member) HasRole(r *Role) bool

func (*Member) Nick 

func (m *Member) Nick() string

Nick returns the Nickname of a member

func (*Member) SetNick 

func (m *Member) SetNick(nick string) error

SetNick sets the nickname of a user. If the user is the currently logged in user it will default to using @me/nick instead of the user id.

func (*Member) User 

func (m *Member) User() *User

User returns the user of a Member

type Message 

type Message struct {
	// contains filtered or unexported fields
}

Message wraps the message type with context

func (*Message) Author 

func (m *Message) Author() (*Member, error)

Author returns the Member that sent a message

func (*Message) AuthorUser 

func (m *Message) AuthorUser() *User

AuthorUser returns the user that sent the message

func (*Message) Channel 

func (m *Message) Channel() (*Channel, error)

Channel returns the channel in which the message was sent or an error.

func (*Message) DisplayText 

func (m *Message) DisplayText() string

DisplayText returns the text of a message with mentions replaced.

func (*Message) Edit 

func (m *Message) Edit(newText string) (*Message, error)

Edit edits the message and returns the new, edited message and an error if one occured.

func (*Message) EditedTimestamp 

func (m *Message) EditedTimestamp() (time.Time, error)

EditedTimestamp returns the timestamp of a message when it was edited

func (*Message) FromMe 

func (m *Message) FromMe() bool

FromMe returns true if the message is from the current user.

func (*Message) Guild 

func (m *Message) Guild() (*Guild, error)

Guild returns the guild the message was send in. It returns an error if the lookup fails, for example if it's a private message channel.

func (*Message) ID 

func (m *Message) ID() string

ID returns the Message ID

func (*Message) Mentioned 

func (m *Message) Mentioned(u *User) bool

Mentioned returns true if the given user was mentioned. Note that it will not check against roles. Use MentionedMember for this.

func (*Message) MentionedMe 

func (m *Message) MentionedMe() (bool, error)

MentionedMe returns true if the current context user was mentioned. It might return an error in which case it will also return false.

func (*Message) MentionedMember 

func (m *Message) MentionedMember(member *Member) (bool, error)

MentionedMember returns true if the specified member was mentioned. It might return an error in which case it will also return false.

func (*Message) Respond 

func (m *Message) Respond(text string) (*Message, error)

Respond writes a message in the same channel the message originated from.

func (*Message) Text 

func (m *Message) Text() string

Text returns the text of a message with mentions unreplaced.

func (*Message) Timestamp 

func (m *Message) Timestamp() (time.Time, error)

Timestamp returns the timestamp of a message

type Role 

type Role struct {
	// contains filtered or unexported fields
}

func (*Role) Color 

func (r *Role) Color() (byte, byte, byte)

Color returns the color of a role split up into the three bytes that make it up.

func (*Role) Hoist 

func (r *Role) Hoist() bool

func (*Role) ID 

func (r *Role) ID() string

func (*Role) Managed 

func (r *Role) Managed() bool

func (*Role) Name 

func (r *Role) Name() string

func (*Role) Position 

func (r *Role) Position() int

type SimpleMessageHandler 

type SimpleMessageHandler struct {
	// contains filtered or unexported fields
}

SimpleMessageHandler is a very simple event dispatcher meant for simple hello-world type bots.

It is recommended to write your own EventHandler that fits your need. This is much safer in terms of typesafety and simplicity.

func (SimpleMessageHandler) Dispatch 

func (s SimpleMessageHandler) Dispatch(ev Event) error

type User 

type User struct {
	// contains filtered or unexported fields
}

func (*User) Avatar 

func (u *User) Avatar() string

func (*User) ID 

func (u *User) ID() string

func (*User) IsBot 

func (u *User) IsBot() bool

func (*User) IsSelf 

func (u *User) IsSelf() bool

func (*User) Member 

func (u *User) Member(g *Guild) (*Member, error)

func (*User) Username 

func (u *User) Username() string

type UserSession 

type UserSession struct {
	// contains filtered or unexported fields
}

A bot is a running discord session intended for usage with a Bot-type Login

func NewUser 

func NewUser(token string) (*UserSession, error)

NewUser uses the given token to log into discord and return a User-type session.

func (*UserSession) CurrentContext 

func (b *UserSession) CurrentContext() Context

CurrentContext returns the current context pointer.

func (*UserSession) GetDiscordgoSession 

func (b *UserSession) GetDiscordgoSession() *discordgo.Session

GetDiscordgoSession returns the underlying session the bot instance is using. This is not recommended unless the functionality you want to use is not implemented on d.g yet.

func (*UserSession) Me 

func (b *UserSession) Me() (*User, error)

Me returns the current bot user (using @me) or an error.

func (*UserSession) SetAvatarFromFile 

func (b *UserSession) SetAvatarFromFile(file string) error

SetAvatarFromFile will read the file and set it as avatar

func (*UserSession) SetAvatarFromReader 

func (b *UserSession) SetAvatarFromReader(image io.Reader) error

SetAvatarFromReader will read the given io.Reader and set the content as avatar

Remember to close the reader after use if applicable.

func (*UserSession) SetAvatarFromURI 

func (b *UserSession) SetAvatarFromURI(uri string) error

SetAvatarFromURI will download the URI data and set it as avatar

func (*UserSession) SetSink 

func (b *UserSession) SetSink(ev EventSink)

SetSink sets the EventSink to be used by D.G

func (*UserSession) Sink 

func (b *UserSession) Sink() EventSink

Sink returns the current EventSink

This may be used by plugins to dispatch custom events.

Source Files

View all Source files

Directories

Path Synopsis
example
helloworld

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.