The highest tagged major version is
README
¶
arikawa
A Golang library for the Discord API.
Examples
Simple
Simple bot example without any state. All it does is logging messages sent into
the console. Run with BOT_TOKEN="TOKEN" go run .
Undeleter
A slightly more complicated example. This bot uses a local state to cache everything, including messages. It detects when someone deletes a message, logging the content into the console.
This example demonstrates the PreHandler feature of this library. PreHandler calls all handlers that are registered (separately from session), calling them before the state is updated.
Advanced Bot
A pretty complicated example demonstrating the reflect-based command router that's built-in. The router turns exported struct methods into commands, its arguments into command arguments, and more.
The library has a pretty detailed documentation available in GoDoc Reference.
Comparison: Why not discordgo?
Discordgo is great. It's the first library that I used when I was learning Go. Though there are some things that I disagree on. Here are some ways that this library is different:
- Better package structure: this library divides the Discord library up into smaller packages.
- Cleaner API/Gateway structure separation: this library separates fields that would only appear in Gateway events, so to not cause confusion.
- Automatic un-pagination: this library automatically un-paginates endpoints that would otherwise not return everything fully.
- Flexible underlying abstractions: this library allows plugging in different JSON and Websocket implementations, as well as direct access to the HTTP client.
- Flexible API abstractions: because packages are separated, the developer could
choose to use a lower level package (such as
gateway) or a higher level package (such asstate). - Pre-handlers in the state: this allows the developers to access items from the state storage before they're removed.
- Pluggable state storages: although only having a default state storage in the library, it is abstracted with an interface, making it possible to implement a custom remote or local state storage.
- REST-updated state: this library will call the REST API if it can't find things in the state, which is useful for keeping it updated.
- No code generation: just so the library is a lot easier to maintain.
Testing
The package includes integration tests that require $BOT_TOKEN. To run these
tests, do
export BOT_TOKEN="<BOT_TOKEN>"
go test -tags integration ./...
Documentation
¶
Overview ¶
Package arikawa contains a set of modular packages that allows you to make a Discord bot or any type of session (OAuth unsupported).
Session ¶
Package session is the most simple abstraction, which combines the API package and the Gateway websocket package together into one. This could be used for minimal bots that only use gateway events and such.
State ¶
Package state abstracts on top of session and provides a local cache of API calls and events. Bots that either don't need a command router or already has its own should use this package.
Bot ¶
Package bot abstracts on top of state and provides a command router based on Go code. This is similar to discord.py's API, only it's Go and there's no optional arguments (yet, although it could be worked around). Most bots are recommended to use this package, as it's the easiest way to make a bot.
Voice ¶
Package voice provides an abstraction on top of State and adds voice support. This allows bots to join voice channels and talk. The package uses an io.Writer approach rather than a channel, contrary to other Discord libraries.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
_example
|
|
|
Package api provides an interface to interact with the Discord REST API.
|
Package api provides an interface to interact with the Discord REST API. |
|
extras/infer
Package infer implements reflect functions that package bot uses.
|
Package infer implements reflect functions that package bot uses. |
|
Package discord provides common structures that the whole repository uses.
|
Package discord provides common structures that the whole repository uses. |
|
Package gateway handles the Discord gateway (or Websocket) connection, its events, and everything related to it.
|
Package gateway handles the Discord gateway (or Websocket) connection, its events, and everything related to it. |
|
Package handler handles incoming Gateway events.
|
Package handler handles incoming Gateway events. |
|
Package session abstracts around the REST API and the Gateway, managing both at once.
|
Package session abstracts around the REST API and the Gateway, managing both at once. |
|
Package state provides interfaces for a local or remote state, as well as abstractions around the REST API and Gateway events.
|
Package state provides interfaces for a local or remote state, as well as abstractions around the REST API and Gateway events. |
|
utils
|
|
|
heart
Package heart implements a general purpose pacemaker.
|
Package heart implements a general purpose pacemaker. |
|
httputil
Package httputil provides abstractions around the common needs of HTTP.
|
Package httputil provides abstractions around the common needs of HTTP. |
|
httputil/httpdriver
Package httpdriver provides interfaces and implementations of a simple HTTP client.
|
Package httpdriver provides interfaces and implementations of a simple HTTP client. |
|
json
Package json allows for different implementations of JSON serializing, as well as extra optional types needed.
|
Package json allows for different implementations of JSON serializing, as well as extra optional types needed. |
|
json/option
Package option provides the ability to create omittable primitives.
|
Package option provides the ability to create omittable primitives. |
|
wsutil
Package wsutil provides abstractions around the Websocket, including rate limits.
|
Package wsutil provides abstractions around the Websocket, including rate limits. |
|
zlib
Package zlib provides abstractions on top of compress/zlib to work with Discord's method of compressing websocket packets.
|
Package zlib provides abstractions on top of compress/zlib to work with Discord's method of compressing websocket packets. |
|
Package voice handles the Discord voice gateway and UDP connections, as well as managing and keeping track of multiple voice sessions.
|
Package voice handles the Discord voice gateway and UDP connections, as well as managing and keeping track of multiple voice sessions. |