Abstract "task" API: spell incantation, kind and caster

[svengreb]

The wand API is inspired by the fantasy novel “Harry Potter“ and uses an abstract view to define interfaces. The main motivation to create a matching naming to the overall “magic“ topic and the actual target project Mage. This might be too abstract for some, but is kept understandable insofar as it should allow everyone to use the "task" API and to derive their own tasks from it.

• 🅸 cast.Caster — A interface type that casts a spell.Incantation using a command for a specific spell.Kind:
  • Cast(spell.Incantation) error — casts a spell incantation.
  • Handles() spell.Kind — returns the spell kind that can be casted.
  • Validate() error — validates the caster command.
• 🅸 cast.BinaryCaster — A interface type that composes cast.Caster to run commands using a binary executable:
  • GetExec() string — returns the path to the binary executable of the command.
• 🅸 spell.Incantation — A interface type that is the abstract representation of parameters for a command or action:
  • Formula() []string — returns all parameters of a spell.
  • Kind() Kind — returns the Kind of a spell.
  • Options() interface{} — return the options of a spell.
• 🅸 cast.Binary — A interface type that composes cast.Caster for commands which are using a binary executable:
  • Env() map[string]string — returns additional environment variables.
• 🅸 cast.GoCode — A interface type that composes cast.Caster for actions that can be casted without a cast.Caster:
  • Cast() (interface{}, error) — casts itself.
• 🅸 cast.GoModule — A interface type that composes cast.Binary for commands that are compiled from a Go module:
  • GoModuleID() *project.GoModuleID — returns the identifier of a Go module.
• 🆃 spell.Kind — A struct type that defines the kind of a spell.

The API components can be roughly translated to their purpose:

• cast.Caster → a executable command
  It validates the command and defines which spell.Kind can be handled by this caster. It could be executed without parameters (spell.Incantation), but in most cases needs at least one parameter.
  • cast.BinaryCaster → a composed cast.Caster to run commands using a binary executable.
    It ensures that the executable file exists and stores information like the path. It could also be executed without parameters (spell.Incantation), but would not have any effect im many cases.
• spell.Incantation → the parameters of a executable command
  It assemble all parameters based on the given options and ensures the they are correctly formatted for the execution in a shell environment. Except for special incantations like spell.GoCode a incantation cannot be used alone but must be passed to a cast.Caster that is able to handle the spell.Kind of this incantation.
  • spell.Binary → a composed spell.Incantation to run commands that are using binary executable.
    It can inject or override environment variables in the shell environment in which the the command will be run.
  • spell.GoCode → a composed spell.Incantation for pure Go code instead of a (binary) executable command.
    It can “cast itself“, e.g. to simply delete a directory using packages like os from the Go standard library. It has been designed this way to also allow such tasks to be handled by the incantation API.
  • spell.GoModule → a composed spell.Binary to run binary commands managed by a Go module, in other words executables installed in GOBIN or received via go get.
    It requires the module identifier (path@version) in order to download and run the executable.