state

package
v2.1.0 Latest Latest
Warning

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

Go to latest
Published: Jun 8, 2021 License: ISC Imports: 9 Imported by: 23

Documentation

Overview

Package state provides interfaces for a local or remote state, as well as abstractions around the REST API and Gateway events.

Index

Constants

This section is empty.

Variables

View Source
var (
	MaxFetchMembers uint = 1000
	MaxFetchGuilds  uint = 100
)

Functions

This section is empty.

Types

type GuildAvailableEvent

type GuildAvailableEvent struct {
	*gateway.GuildCreateEvent
}

GuildAvailableEvent gets fired when a guild becomes available again, after being previously declared unavailable through a GuildUnavailableEvent. This event will not be fired for guilds that were already unavailable when connecting to the gateway.

type GuildJoinEvent

type GuildJoinEvent struct {
	*gateway.GuildCreateEvent
}

GuildJoinEvent gets fired if the bot/user joins a guild.

type GuildLeaveEvent

type GuildLeaveEvent struct {
	*gateway.GuildDeleteEvent
}

GuildLeaveEvent gets fired if the bot/user left a guild, was removed or the owner deleted the guild.

type GuildReadyEvent

type GuildReadyEvent struct {
	*gateway.GuildCreateEvent
}

GuildReady gets fired for every guild the bot/user is in, as found in the Ready event.

Guilds that are unavailable when connecting, will not trigger a GuildReadyEvent, until they become available again.

type GuildUnavailableEvent

type GuildUnavailableEvent struct {
	*gateway.GuildDeleteEvent
}

GuildUnavailableEvent gets fired if a guild becomes unavailable.

type State

type State struct {
	*session.Session
	store.Cabinet

	// StateLog logs all errors that come from the state cache. This includes
	// not found errors. Defaults to a no-op, as state errors aren't that
	// important.
	StateLog func(error)

	// PreHandler is the manual hook that is executed before the State handler
	// is. This should only be used for low-level operations.
	// It's recommended to set Synchronous to true if you mutate the events.
	PreHandler *handler.Handler // default nil

	// Command handler with inherited methods. Ran after PreHandler. You should
	// most of the time use this instead of Session's, to avoid race conditions
	// with the State.
	*handler.Handler
	// contains filtered or unexported fields
}

State is the cache to store events coming from Discord as well as data from API calls.

Store

The state basically provides abstractions on top of the API and the state storage (Store). The state storage is effectively a set of interfaces which allow arbitrary backends to be implemented.

The default storage backend is a typical in-memory structure consisting of maps and slices. Custom backend implementations could embed this storage backend as an in-memory fallback. A good example of this would be embedding the default store for messages only, while handling everything else in Redis.

The package also provides a no-op store (NoopStore) that implementations could embed. This no-op store will always return an error, which makes the state fetch information from the API. The setters are all no-ops, so the fetched data won't be updated.

Handler

The state uses its own handler over session's to make all handlers run after the state updates itself. A PreHandler is exposed in any case the user needs the handlers to run before the state updates itself. Refer to that field's documentation.

The state also provides extra events and overrides to make up for Discord's inconsistencies in data. The following are known instances of such.

The Guild Create event is split up to make the state's Guild Available, Guild Ready and Guild Join events. Refer to these events' documentations for more information.

The Message Create and Message Update events with the Member field provided will have the User field copied from Author. This is because the User field will be empty, while the Member structure expects it to be there.

func New

func New(token string) (*State, error)

New creates a new state.

func NewFromSession

func NewFromSession(s *session.Session, cabinet store.Cabinet) *State

NewFromSession creates a new State from the passed Session and Cabinet.

func NewWithIntents

func NewWithIntents(token string, intents ...gateway.Intents) (*State, error)

NewWithIntents creates a new state with the given gateway intents. For more information, refer to gateway.Intents.

func NewWithStore

func NewWithStore(token string, cabinet store.Cabinet) (*State, error)

func (*State) AuthorColor

func (s *State) AuthorColor(message *gateway.MessageCreateEvent) (discord.Color, error)

func (*State) AuthorDisplayName

func (s *State) AuthorDisplayName(message *gateway.MessageCreateEvent) string

func (*State) Channel

func (s *State) Channel(id discord.ChannelID) (c *discord.Channel, err error)

func (*State) Channels

func (s *State) Channels(guildID discord.GuildID) (cs []discord.Channel, err error)

func (*State) CreatePrivateChannel

func (s *State) CreatePrivateChannel(recipient discord.UserID) (*discord.Channel, error)

func (*State) Emoji

func (s *State) Emoji(
	guildID discord.GuildID, emojiID discord.EmojiID) (e *discord.Emoji, err error)

func (*State) Emojis

func (s *State) Emojis(guildID discord.GuildID) (es []discord.Emoji, err error)

func (*State) Guild

func (s *State) Guild(id discord.GuildID) (*discord.Guild, error)

func (*State) Guilds

func (s *State) Guilds() (gs []discord.Guild, err error)

Guilds will only fill a maximum of 100 guilds from the API.

func (*State) Me

func (s *State) Me() (*discord.User, error)

func (*State) Member

func (s *State) Member(guildID discord.GuildID, userID discord.UserID) (*discord.Member, error)

func (*State) MemberColor

func (s *State) MemberColor(guildID discord.GuildID, userID discord.UserID) (discord.Color, error)

func (*State) MemberDisplayName

func (s *State) MemberDisplayName(guildID discord.GuildID, userID discord.UserID) (string, error)

func (*State) Members

func (s *State) Members(guildID discord.GuildID) (ms []discord.Member, err error)

func (*State) Message

func (s *State) Message(
	channelID discord.ChannelID, messageID discord.MessageID) (*discord.Message, error)

func (*State) Messages

func (s *State) Messages(channelID discord.ChannelID) ([]discord.Message, error)

Messages fetches maximum 100 messages from the API, if it has to. There is no limit if it's from the State storage.

func (*State) Permissions

func (s *State) Permissions(
	channelID discord.ChannelID, userID discord.UserID) (discord.Permissions, error)

Permissions gets the user's permissions in the given channel. If the channel is not in any guild, then an error is returned.

func (*State) Presence

func (s *State) Presence(gID discord.GuildID, uID discord.UserID) (*gateway.Presence, error)

Presence checks the state for user presences. If no guildID is given, it will look for the presence in all cached guilds.

func (*State) PrivateChannels

func (s *State) PrivateChannels() ([]discord.Channel, error)

PrivateChannels gets the direct messages of the user. This is not supported for bots.

func (*State) Ready

func (s *State) Ready() gateway.ReadyEvent

Ready returns a copy of the Ready event. Although this function is safe to call concurrently, its values should still not be changed, as certain types like slices are not concurrent-safe.

Note that if Ready events are not received yet, then the returned event will be a zero-value Ready instance.

func (*State) Role

func (s *State) Role(guildID discord.GuildID, roleID discord.RoleID) (target *discord.Role, err error)

func (*State) Roles

func (s *State) Roles(guildID discord.GuildID) ([]discord.Role, error)

func (*State) WithContext

func (s *State) WithContext(ctx context.Context) *State

WithContext returns a shallow copy of State with the context replaced in the API client. All methods called on the State will use this given context. This method is thread-safe.

Directories

Path Synopsis
Package store contains interfaces of the state's storage and its implementations.
Package store contains interfaces of the state's storage and its implementations.
defaultstore
Package defaultstore provides thread-safe store implementations that store state values in memory.
Package defaultstore provides thread-safe store implementations that store state values in memory.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL