task

Documentation

Overview

Package task provides tasks and runner for Mage.

Index

• Constants
• type ErrRunner
  • func (e *ErrRunner) Error() string
  • func (e *ErrRunner) Is(err error) bool
  • func (e *ErrRunner) Unwrap() error
• type ErrTask
  • func (e *ErrTask) Error() string
  • func (e *ErrTask) Is(err error) bool
  • func (e *ErrTask) Unwrap() error
• type Exec
• type GoModule
• type Kind
  • func ParseKind(name string) (Kind, error)
  • func (k Kind) MarshalText() ([]byte, error)
  • func (k Kind) String() string
  • func (k *Kind) UnmarshalText(text []byte) error
• type Mixin
• type Options
• type Runner
• type RunnerExec
• type Task

Constants

const (
	// ErrIncompatibleRunner indicates that a command runner is not compatible for a task.
	ErrIncompatibleRunner = wErr.ErrString("incompatible command runner")

	// ErrInvalidRunnerOpts indicates invalid command runner options.
	ErrInvalidRunnerOpts = wErr.ErrString("invalid options")

	// ErrInvalidTaskOpts indicates invalid task options.
	ErrInvalidTaskOpts = wErr.ErrString("invalid options")

	// ErrRun indicates that a runner failed to run.
	ErrRun = wErr.ErrString("failed to run")

	// ErrRunnerValidation indicates that a command runner validation failed.
	ErrRunnerValidation = wErr.ErrString("validation failed")

	// ErrTaskValidation indicates that a task validation failed.
	ErrTaskValidation = wErr.ErrString("validation failed")

	// ErrUnsupportedTaskKind indicates that a task kind is not supported.
	ErrUnsupportedTaskKind = wErr.ErrString("unsupported task kind")

	// ErrUnsupportedTaskOptions indicates that the task options are not supported.
	ErrUnsupportedTaskOptions = wErr.ErrString("unsupported task kind")
)

const (
	// KindNameBase is the kind name for base tasks.
	KindNameBase = "base"
	// KindNameExec is the kind name for executable file tasks.
	KindNameExec = "executable"
	// KindNameGoModule is the kind name for Go module tasks.
	KindNameGoModule = "go.module"
	// KindNameUnknown is the name for a unknown task kind.
	KindNameUnknown = "unknown"
)

Types

type ErrRunner

type ErrRunner struct {
	// Err is a wrapped error.
	Err error
	// Kind is the error kind.
	Kind error
}

ErrRunner represents a runner error.

func (*ErrRunner) Error

func (e *ErrRunner) Error() string

func (*ErrRunner) Is

func (e *ErrRunner) Is(err error) bool

Is enables usage of errors.Is() to determine the kind of error that occurred.

func (*ErrRunner) Unwrap

func (e *ErrRunner) Unwrap() error

Unwrap returns the underlying error for usage with errors.Unwrap().

type ErrTask

type ErrTask struct {
	// Err is a wrapped error.
	Err error
	// Kind is the error kind.
	Kind error
}

ErrTask represents a task error.

func (*ErrTask) Error

func (e *ErrTask) Error() string

func (*ErrTask) Is

func (e *ErrTask) Is(err error) bool

Is enables usage of errors.Is() to determine the kind of error that occurred.

func (*ErrTask) Unwrap

func (e *ErrTask) Unwrap() error

Unwrap returns the underlying error for usage with errors.Unwrap().

type Exec

type Exec interface {
	Task

	// BuildParams builds the parameters for a command runner.
	// Parameters consist of options, flags and arguments.
	// The separation of parameters from commands enables a flexible usage, e.g. when parameters can be reused for
	// different tasks.
	//
	// References
	//
	//   (1) https://en.wikipedia.org/wiki/Command-line_interface#Anatomy_of_a_shell_CLI
	BuildParams() []string

	// Env returns the task specific environment.
	Env() map[string]string
}

Exec is a task for a executable command.

type GoModule

type GoModule interface {
	Exec

	// ID returns the identifier of a Go module.
	ID() *project.GoModuleID
}

GoModule is a task for a Go module command.

See https://golang.org/ref/mod for more details about Go modules.

type Kind

type Kind uint32

Kind defines the kind of tasks.

const (
	// KindBase is the kind for base tasks.
	KindBase Kind = iota
	// KindExec is the kind for executable file tasks.
	KindExec
	// KindGoModule is the kind for Go module tasks.
	KindGoModule
)

func ParseKind

func ParseKind(name string) (Kind, error)

ParseKind takes a kind name and returns the Kind constant.

func (Kind) MarshalText

func (k Kind) MarshalText() ([]byte, error)

MarshalText returns the textual representation of itself.

func (Kind) String

func (k Kind) String() string

func (*Kind) UnmarshalText

func (k *Kind) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler to unmarshal a textual representation of itself.

type Mixin

type Mixin interface {
	// Apply applies the mixin to task options.
	Apply(Options) (Options, error)
}

Mixin allows to compose functions that process task options.

type Options

type Options interface{}

Options is a generic representation for task options.

type Runner

type Runner interface {
	// Handles returns the supported task kind.
	Handles() Kind

	// Run runs a command.
	Run(Task) error

	// RunOut runs a command and returns its output.
	RunOut(Task) (string, error)

	// Validate validates the runner.
	Validate() error
}

Runner runs a command with parameters in a specific environment.

type RunnerExec

type RunnerExec interface {
	Runner

	// FilePath returns the path to the (binary) command executable.
	FilePath() string
}

RunnerExec is a runner for a (binary) command executable.

type Task

type Task interface {
	// Kind returns the task kind.
	Kind() Kind

	// Name returns the task name.
	Name() string

	// Options returns the task options.
	Options() Options
}

Task is a wand task for Mage.

See https://magefile.org/targets for more details about Mage targets.