twicmd

Documentation

Overview

Package twicmd provides a command parsing and dispatching framework for Twipi. The most simple implementation of it is slashparser.

Index

• func MapArguments(arguments []*twicmdproto.CommandArgument) map[string]string
• func StatusResponse(status string) *twicmdproto.ExecuteResponse
• func TextResponse(text string) *twicmdproto.ExecuteResponse
• type CommandParser
• type ConfigurableService
• type Manager
  • func (s *Manager) Start(ctx context.Context) error
• type ResolvedService
• type Service
• type ServiceCommandTuple
• type ServiceLookup
  • func NewServiceLookup() *ServiceLookup
  • func (l *ServiceLookup) AllServices() []Service
  • func (l *ServiceLookup) Lookup(ctx context.Context, serviceName string) (*ResolvedService, error)
  • func (l *ServiceLookup) LookupCommand(ctx context.Context, serviceName, commandName string) (*ServiceCommandTuple, error)
  • func (l *ServiceLookup) Register(service Service)
  • func (l *ServiceLookup) ResolveAllServices(ctx context.Context) xiter.Seq2[*ResolvedService, error]
  • func (l *ServiceLookup) Service(name string) (Service, bool)
• type StartOpts

Functions

func MapArguments

func MapArguments(arguments []*twicmdproto.CommandArgument) map[string]string

MapArguments maps the given list of command arguments to a map of key-value pairs.

func StatusResponse

func StatusResponse(status string) *twicmdproto.ExecuteResponse

StatusResponse creates a new twicmdproto.ExecuteResponse with the given status.

func TextResponse

func TextResponse(text string) *twicmdproto.ExecuteResponse

TextResponse creates a new twicmdproto.ExecuteResponse with the given text.

Types

type CommandParser

type CommandParser interface {
	// Name returns the name of the parser.
	// This name is only used internally.
	Name() string
	// Parse parses the given message body and returns the parsed command.
	// It may return (nil, nil) if the message body is not applicable to the
	// parser.
	Parse(context.Context, *ServiceLookup, *twismsproto.MessageBody) (*twicmdproto.Command, error)
}

CommandParser describes a message body parser that returns a command. A CommandParser must be thread-safe.

type ConfigurableService

type ConfigurableService interface {
	Service
	// ConfigurationValues returns the current vluaes of the options.
	ConfigurationValues(context.Context, *twicmdcfgpb.OptionsRequest) (*twicmdcfgpb.OptionsResponse, error)
	// ApplyConfigurationValues applies the values of the options.
	// Only the values given in the values list should be changed.
	ApplyConfigurationValues(context.Context, *twicmdcfgpb.ApplyRequest) (*twicmdcfgpb.ApplyResponse, error)
}

ConfigurableService describes a command service that can be configured. It extends Service with configuration management for the user.

Note that in order for a service to be configurable by the user, it needs to:

1. Implement this interface, and
2. Have the twicmdpb.Service.options_schema field set.

type Manager

type Manager struct {
	SMS      twisms.MessageService
	Parsers  []CommandParser
	Services *ServiceLookup
	Logger   *slog.Logger
	Opts     StartOpts
}

Manager handles the command parsing and dispatching framework. It is in charge of reading incoming messages from the channel and dispatching them to the appropriate command parsers.

func (*Manager) Start

func (s *Manager) Start(ctx context.Context) error

Start starts the manager.

type ResolvedService

type ResolvedService struct {
	Service     Service
	Description *twicmdproto.Service
}

ResolvedService is a tuple of a service and its description.

type Service

type Service interface {
	// Name returns the name of the service. This name must be constant and must
	// match what is returned by [Service.Service].Name.
	Name() string
	// Service returns the service blob that describes the command service.
	// It is expected to return the same service for the lifetime of the
	// executor.
	Service(ctx context.Context) (*twicmdproto.Service, error)
	// Execute executes the given command and returns the message body
	// to be replied back to the sender.
	Execute(context.Context, *twicmdproto.ExecuteRequest) (*twicmdproto.ExecuteResponse, error)

	twisms.MessageSubscriber
}

Service describes a command service capable of executing parsed commands using [Service.Execute] that comply to its own definition returned by [Service.Service].

type ServiceCommandTuple

type ServiceCommandTuple struct {
	ResolvedService
	Command *twicmdproto.CommandDescription
}

ServiceCommandTuple is a tuple of a service and a command.

type ServiceLookup

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

ServiceLookup provides ways to lookup services, which can be arbitrarily removed and added.

func NewServiceLookup

func NewServiceLookup() *ServiceLookup

NewServiceLookup creates a new empty ServiceLookup instance.

func (*ServiceLookup) AllServices

func (l *ServiceLookup) AllServices() []Service

AllServices returns all registered services.

func (*ServiceLookup) Lookup

func (l *ServiceLookup) Lookup(ctx context.Context, serviceName string) (*ResolvedService, error)

Lookup looks up a service by its name If the service is not found, nil on each or both is returned.

func (*ServiceLookup) LookupCommand

func (l *ServiceLookup) LookupCommand(ctx context.Context, serviceName, commandName string) (*ServiceCommandTuple, error)

LookupCommand looks up a command by its name.

func (*ServiceLookup) Register

func (l *ServiceLookup) Register(service Service)

Register registers a service for the command parser. If the service already exists, it will be replaced.

func (*ServiceLookup) ResolveAllServices

func (l *ServiceLookup) ResolveAllServices(ctx context.Context) xiter.Seq2[*ResolvedService, error]

ResolveAllServices resolves and returns all registered services. The iterator will be valid for as long as the context is valid.

func (*ServiceLookup) Service

func (l *ServiceLookup) Service(name string) (Service, bool)

Service returns a service by its name.

type StartOpts

type StartOpts struct {
	// Filters is the list of message filters to apply.
	// This parameter is optional.
	Filters *twismsproto.MessageFilters
}

StartOpts describes the optional options for starting the command parsing and dispatching framework. All fields are optional.