pluginx

Documentation

Overview

Package pluginx provides helper functions to simplify working it Botkube plugins. The 'x' in the package name stand for 'extension'. It is added to reduce possible conflicts with core plugin package named 'plugin'.

Example (ExecuteCommand)

out, err := ExecuteCommand(context.Background(), `echo "hakuna matata"`)
if err != nil {
	panic(err)
}

fmt.Println(out)

Output:

hakuna matata

Example (ExecuteCommandWithEnv)

out, err := ExecuteCommandWithEnvs(context.Background(), `sh -c "echo ${CUSTOM_ENV}"`, map[string]string{
	"CUSTOM_ENV": "magic-value",
})
if err != nil {
	panic(err)
}

fmt.Println(out)

Output:

magic-value

Example (ParseCommand)

type (
	CommitCmd struct {
		All     bool   `arg:"-a"`
		Message string `arg:"-m"`
	}
	Commands struct {
		Commit *CommitCmd `arg:"subcommand:commit"`
		Quiet  bool       `arg:"-q"` // this flag is global to all subcommands
	}
)

rawCommand := "./example commit -m 'hakuna matata' -a -q"

var cmd Commands
err := ParseCommand("./example", rawCommand, &cmd)
if err != nil {
	panic(err)
}

switch {
case cmd.Commit != nil:
	fmt.Println(heredoc.Docf(`
			global quiet flag: %v
			commit message: %v
			commit all flag: %v
		`, cmd.Commit.All, cmd.Commit.Message, cmd.Quiet))
}

Output:

global quiet flag: true
commit message: hakuna matata
commit all flag: true

Index

• func DownloadDependencies(in map[string]api.Dependency) error
• func ExecuteCommand(ctx context.Context, rawCmd string) (string, error)
• func ExecuteCommandWithEnvs(ctx context.Context, rawCmd string, envs map[string]string) (string, error)
• func MergeExecutorConfigs(in []*executor.Config, dest any) error
• func MergeExecutorConfigsWithDefaults(defaults any, in []*executor.Config, dest any) error
• func MergeSourceConfigs(in []*source.Config, dest any) error
• func MergeSourceConfigsWithDefaults(defaults any, in []*source.Config, dest any) error
• func ParseCommand(pluginName, command string, destination any) error

Examples

• Package (ExecuteCommand)
• Package (ExecuteCommandWithEnv)
• Package (ParseCommand)

Functions

func DownloadDependencies

func DownloadDependencies(in map[string]api.Dependency) error

DownloadDependencies downloads input dependencies into plugins directory. Deprecated: Since 0.18, plugin's dependency are downloaded automatically by Botkube. This method will be removed after releasing 0.18 version.

Migration path:

The syntax for defining plugin dependency remains the same:
   var depsDownloadLinks = map[string]api.Dependency{
   	"gh": {
   		URLs: map[string]string{
   			"darwin/amd64": "https://github.com/cli/cli/releases/download/v2.21.2/gh_2.21.2_macOS_amd64.tar.gz//gh_2.21.2_macOS_amd64/bin",
   			"linux/amd64":  "https://github.com/cli/cli/releases/download/v2.21.2/gh_2.21.2_linux_amd64.tar.gz//gh_2.21.2_linux_amd64/bin",
   		},
   	},
   }

however, instead of calling download method:
  pluginx.DownloadDependencies(depsDownloadLinks)

move the `depsDownloadLinks` object under `MetadataOutput.Dependencies`:
  Metadata(context.Context) (api.MetadataOutput, error) {
  	return api.MetadataOutput{
  		// ...
  		Dependencies: depsDownloadLinks,
  	}, nil
  }

func ExecuteCommand

func ExecuteCommand(ctx context.Context, rawCmd string) (string, error)

ExecuteCommand is a simple wrapper around exec.CommandContext to simplify running a given command.

func ExecuteCommandWithEnvs

func ExecuteCommandWithEnvs(ctx context.Context, rawCmd string, envs map[string]string) (string, error)

ExecuteCommandWithEnvs is a simple wrapper around exec.CommandContext to simplify running a given command.

func MergeExecutorConfigs

func MergeExecutorConfigs(in []*executor.Config, dest any) error

MergeExecutorConfigs merges input configuration into a given destination. Rules: - Destination MUST be a pointer to a struct. - if `yaml:"omitempty"` tag is not specified, then empty fields are take into account, and resets previous value. - Merging strategy can be found here https://github.com/knadh/koanf#merge-behavior.

func MergeExecutorConfigsWithDefaults

func MergeExecutorConfigsWithDefaults(defaults any, in []*executor.Config, dest any) error

MergeExecutorConfigsWithDefaults merges input configuration into a given destination. Rules: - Destination MUST be a pointer to a struct. - Default MUST be a Go object with the `yaml` tag. - if `yaml:"omitempty"` tag is not specified, then empty fields are take into account, and resets previous value. - Merging strategy can be found here https://github.com/knadh/koanf#merge-behavior.

func MergeSourceConfigs

func MergeSourceConfigs(in []*source.Config, dest any) error

MergeSourceConfigs merges input configuration into a given destination. Rules: - Destination MUST be a pointer to a struct. - if `yaml:"omitempty"` tag is not specified, then empty fields are take into account, and resets previous value. - Merging strategy can be found here https://github.com/knadh/koanf#merge-behavior.

func MergeSourceConfigsWithDefaults

func MergeSourceConfigsWithDefaults(defaults any, in []*source.Config, dest any) error

MergeSourceConfigsWithDefaults merges input configuration into a given destination. Rules: - Destination MUST be a pointer to a struct. - Default MUST be a Go object with the `yaml` tag. - if `yaml:"omitempty"` tag is not specified, then empty fields are take into account, and resets previous value. - Merging strategy can be found here https://github.com/knadh/koanf#merge-behavior.

func ParseCommand

func ParseCommand(pluginName, command string, destination any) error

ParseCommand processes a given command string and stores the result in a given destination. Destination MUST be a pointer to a struct.

If `-h,--help` flag was specified, arg.ErrHelp is returned and command might be not fully parsed.

To support flags, positional arguments, and subcommands add dedicated `arg:` tag. To learn more, visit github.com/alexflint/go-arg