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: 21

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.

Source Files

View all Source files

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
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.