cmd

package
Version: v0.6.2 Latest Latest
Warning

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

Go to latest
Published: Apr 21, 2022 License: MIT Imports: 11 Imported by: 52

Documentation

Overview

Package cmd implements a Minecraft specific command system, which may be used simply by 'plugging' it in and sending commands registered in an AvailableCommandsPacket.

The cmd package handles commands in a specific way: It requires a struct to be passed to the cmd.New() function, which implements the Runnable interface. For every exported field in the struct, executing the command will result in the parsing of the arguments using the types of the fields of the struct, in the order that they appear in.

A Runnable may have exported fields only of the following types: int8, int16, int32, int64, int, uint8, uint16, uint32, uint64, uint, float32, float64, string, bool, mgl64.Vec3, Varargs, []Target or a type that implements the cmd.Parameter, cmd.Enum or cmd.SubCommand interface. cmd.Enum implementations must be of the type string. Fields in the Runnable struct may have the `optional:""` struct tag to mark them as an optional parameter, the `suffix:"$suffix"` struct tag to add a suffix to the parameter in the usage, and the `name:"name"` tag to specify a name different from the field name for the parameter.

Commands may be registered using the cmd.Register() method. By itself, this method will not ensure that the client will be able to use the command: The user of the cmd package must handle commands itself and run the appropriate one using the cmd.ByAlias function.

Index

Constants

This section is empty.

Variables

View Source
var ErrInsufficientArgs = errors.New("not enough arguments for command")

ErrInsufficientArgs is returned by argument parsing functions if it does not have sufficient arguments passed and is not optional.

Functions

func AddTargetFunc

func AddTargetFunc(f TargetFunc)

AddTargetFunc adds a TargetFunc to the list of functions used to find targets that may be targeted by a Source.

func Commands

func Commands() map[string]Command

Commands returns a map of all registered commands indexed by the alias they were registered with.

func Register

func Register(command Command)

Register registers a command with its name and all aliases that it has. Any command with the same name or aliases will be overwritten.

Types

type Allower

type Allower interface {
	// Allow checks if the Source passed is allowed to execute the command. True is returned if the Source is
	// allowed to execute the command.
	Allow(s Source) bool
}

Allower may be implemented by a type also implementing Runnable to limit the sources that may run the command.

type Command

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

Command is a wrapper around a Runnable. It provides additional identity and utility methods for the actual runnable command so that it may be identified more easily.

func ByAlias

func ByAlias(alias string) (Command, bool)

ByAlias looks up a command by an alias. If found, the command and true are returned. If not, the returned command is nil and the bool is false.

func New

func New(name, description string, aliases []string, r ...Runnable) Command

New returns a new Command using the name and description passed. The Runnable passed must be a (pointer to a) struct, with its fields representing the parameters of the command. When the command is run, the Run method of the Runnable will be called, after all fields have their values from the parsed command set. If r is not a struct or a pointer to a struct, New panics.

func (Command) Aliases

func (cmd Command) Aliases() []string

Aliases returns a list of aliases for the command. In addition to the name of the command, the command may be called using one of these aliases.

func (Command) Description

func (cmd Command) Description() string

Description returns the description of the command. The description is shown in the /help list, and provides information on the functionality of a command.

func (Command) Execute

func (cmd Command) Execute(args string, source Source)

Execute executes the Command as a source with the args passed. The args are parsed assuming they do not start with the command name. Execute will attempt to parse and execute one Runnable at a time. If one of the Runnable was able to parse args correctly, it will be executed and no more Runnables will be attempted to be run. If parsing of all Runnables was unsuccessful, a command output with an error message is sent to the Source passed, and the Run method of the Runnables are not called. The Source passed must not be nil. The method will panic if a nil Source is passed.

func (Command) Name

func (cmd Command) Name() string

Name returns the name of the command. The name is guaranteed to be lowercase and will never have spaces in it. This name is used to call the command, and is shown in the /help list.

func (Command) Params

func (cmd Command) Params(src Source) [][]ParamInfo

Params returns a list of all parameters of the runnables. No assumptions should be done on the values that they hold: Only the types are guaranteed to be consistent.

func (Command) Runnables added in v0.4.1

func (cmd Command) Runnables(src Source) map[int]Runnable

Runnables returns a map of all Runnable implementations of the Command that a Source can execute.

func (Command) String

func (cmd Command) String() string

String returns the usage of the command. The usage will be roughly equal to the one showed by the client in-game.

func (Command) Usage

func (cmd Command) Usage() string

Usage returns the usage of the command. The usage will be roughly equal to the one showed by the client in-game.

type Enum

type Enum interface {
	// Type returns the type of the enum. This type shows up client-side in the command usage, in the spot
	// where parameter types otherwise are.
	// Type names returned are used as an identifier for this enum type. Different Enum implementations must
	// return a different string in the Type method.
	Type() string
	// Options should return a list of options that show up on the client side. The command will ensure that
	// the argument passed to the enum parameter will be equal to one of these options. The provided Source
	// can also be used to change the enums for each player.
	Options(source Source) []string
}

Enum is an interface for enum-type parameters. Users may have types as command parameters that implement this parameter in order to allow a specific set of options only. Enum implementations must be of the type string, for example:

type GameMode string
func (GameMode) Type() string { return "GameMode" }
func (GameMode) Options(Source) []string { return []string{"survival", "creative"} }

Their values will then automatically be set to whichever option returned in Enum.Options is selected by the user.

type Line

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

Line represents a command line holding command arguments that were passed upon the execution of the command. It is a convenience wrapper around a string slice.

func (*Line) Leftover

func (line *Line) Leftover() []string

Leftover takes the leftover arguments from the command line.

func (*Line) Len

func (line *Line) Len() int

Len returns the leftover length of the arguments in the command line.

func (*Line) Next

func (line *Line) Next() (string, bool)

Next reads the next argument from the command line and returns it. If there were no more arguments to consume, false is returned.

func (*Line) NextN

func (line *Line) NextN(n int) ([]string, bool)

NextN reads the next N arguments from the command line and returns them. If there were not enough arguments (n arguments), false is returned.

func (*Line) RemoveN

func (line *Line) RemoveN(n int)

RemoveN consumes the next N arguments from the command line.

func (*Line) RemoveNext

func (line *Line) RemoveNext()

RemoveNext consumes the next argument from the command line.

type Output

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

Output holds the output of a command execution. It holds success messages and error messages, which the source of a command execution gets sent.

func (*Output) Error

func (o *Output) Error(a ...any)

Error formats an error message and adds it to the command output.

func (*Output) ErrorCount

func (o *Output) ErrorCount() int

ErrorCount returns the count of errors that the command output has.

func (*Output) Errorf

func (o *Output) Errorf(format string, a ...any)

Errorf formats an error message and adds it to the command output.

func (*Output) Errors

func (o *Output) Errors() []error

Errors returns a list of all errors added to the command output. Usually only one error message is set: After one error message, execution of a command typically terminates.

func (*Output) MessageCount

func (o *Output) MessageCount() int

MessageCount returns the count of (success) messages that the command output has.

func (*Output) Messages

func (o *Output) Messages() []string

Messages returns a list of all messages added to the command output. The amount of messages present depends on the command called.

func (*Output) Print

func (o *Output) Print(a ...any)

Print formats a (success) message and adds it to the command output.

func (*Output) Printf

func (o *Output) Printf(format string, a ...any)

Printf formats a (success) message and adds it to the command output.

type ParamInfo

type ParamInfo struct {
	Name     string
	Value    any
	Optional bool
	Suffix   string
}

ParamInfo holds the information of a parameter in a Runnable. Information of a parameter may be obtained by calling Command.Params().

type Parameter

type Parameter interface {
	// Parse takes an arbitrary amount of arguments from the command Line passed and parses it, so that it can
	// store it to value v. If the arguments cannot be parsed from the Line, an error should be returned.
	Parse(line *Line, v reflect.Value) error
	// Type returns the type of the parameter. It will show up in the usage of the command, and, if one of the
	// known type names, will also show up client-side.
	Type() string
}

Parameter is an interface for a generic parameters. Users may have types as command parameters that implement this parameter.

type Runnable

type Runnable interface {
	// Run runs the Command, using the arguments passed to the Command. The source is passed to the method,
	// which is the source of the execution of the Command, and the output is passed, to which messages may be
	// added which get sent to the source.
	Run(source Source, output *Output)
}

Runnable represents a Command that may be run by a Command source. The Command must be a struct type and its fields represent the parameters of the Command. When the Run method is called, these fields are set and may be used for behaviour in the Command. A Runnable may have exported fields only of the following types: int8, int16, int32, int64, int, uint8, uint16, uint32, uint64, uint, float32, float64, string, bool, mgl64.Vec3, Varargs, []Target or a type that implements the cmd.Parameter, cmd.Enum or cmd.SubCommand interface. cmd.Enum implementations must be of the type string. Fields in the Runnable struct may have the `optional:""` struct tag to mark them as an optional parameter, the `suffix:"$suffix"` struct tag to add a suffix to the parameter in the usage, and the `name:"name"` tag to specify a name different from the field name for the parameter.

type Source

type Source interface {
	Target
	// SendCommandOutput sends a command output to the source. The way the output is applied, depends on what
	// kind of source it is.
	// SendCommandOutput is called by a Command automatically after being run.
	SendCommandOutput(output *Output)
	// World returns the world that the Source is in.
	World() *world.World
}

Source represents a source of a command execution. Commands may limit the sources that can run them by implementing the Allower interface. Source implements Target. A Source must always be able to target itself.

type SubCommand

type SubCommand interface {
	// SubName returns the value that must be entered by the user when executing the subcommand, such as
	// 'kill' for a command such as /entity kill <target>.
	SubName() string
}

SubCommand represents a subcommand that may be added as a static value that must be written. Adding multiple Runnable implementations to the command in New with different SubCommand implementations as the first parameter allows for commands with subcommands.

type Target

type Target interface {
	// Name returns a name of the Target. Note that this name needs not to be and is not unique for a Target.
	Name() string
	// Position returns the position of the Target as an mgl64.Vec3.
	Position() mgl64.Vec3
}

Target represents the target of a command. A single Target or a []Target may be used as command parameter types to allow passing targets to the command.

type TargetFunc

type TargetFunc func(src Source) (entities, players []Target)

TargetFunc is a function used to find Targets eligible for a command executed by a given Source. Multiple functions may be added by using AddTargetFunc.

type Varargs

type Varargs string

Varargs is an argument type that may be used to capture all arguments that follow. This is useful for, for example, messages and names.

Jump to

Keyboard shortcuts

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