"Task" API: Simplified usage and "normalized" naming scheme #51
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
With GH-14 [1] the "abstract" wand API was introduced with a naming scheme is inspired by the fantasy novel "Harry Potter" [2] that was used to to define interfaces. The main motivation was to create a matching naming to the overall "magic" topic and the actual target project Mage [3], but in retrospect this is way too abstract and confusing. The goal of this commit is to... - rewrite the API to make it way easier to use. - use a "normal" naming scheme. - improve all documentations to be more user-scoped and provide guides and examples. >>> New API Concept The basic mindset of the API remains partially the same, but it is designed around the concept of tasks and the ways to run them. >>>> Command Runner `task.Runner` [4] is a new base interface that runs a command with parameters in a specific environment. It can be compared to the current `cast.Caster` [5] interface, but provides a cleaner method set accepting the new `task.Task` [6] interface. - <M> `Handles() task.Kind` - returns the supported task kind [7]. - <M> `Run(task.Task) error` - runs a command. - <M> `Validate() error` - validates the runner. The new `task.RunnerExec` [8] interface is a specialized `task.Runner` and serves as an abstract representation for a command or action, in most cases a (binary) [executable][9] of external commands or Go module `main` packages, that provides corresponding information like the path to the executable. It can be compared to the previous `BinaryCaster` [10] interface, but also comes with a cleaner method set and a more appropriate name. - <M> `FilePath() string` - returns the path to the (binary) command executable. >>>> Tasks `task.Task` [6] is the new interface that is scoped for Mage "target" [11] usage. It can be compared to the previous `spell.Incantation` [12] interface, but provides a smaller method set without `Formula() []string`. - <M> `Kind() task.Kind` - returns the task kind [7]. - <M> `Options() task.Options` - returns the task options [13]. The new `task.Exec` [14] interface is a specialized `task.Task` and serves as an abstract task for an executable command. It can be compared to the previous `Binary` [15] interface, but also comes with the new `BuildParams() []string` method that enables a more flexible usage by exposing the parameters for command runner like `task.RunnerExec` and also allows to compose with other tasks. See the Wikipedia page about the "anatomy of a shell CLI" [16] for more details about parameters. - <M> `BuildParams() []string` - builds the parameters for a command runner where parameters can consist of options, flags and arguments. - <M> `Env() map[string]string` - returns the task specific environment. The new `task.GoModule` [17] interface is a specialized `task.Exec` for a executable Go module command. It can be compared to the previous `spell.GoModule` [18] interface and the method set has not changed except a renaming of the `GoModuleID() *project.GoModuleID` to the more appropriate name `ID() *project.GoModuleID`. See the official "Go module reference documentation" [19] for more details about Go modules. - <M> `ID() *project.GoModuleID` - returns the identifier of a Go module. >>> New API Naming Scheme The following listing shows the new name concept and how the previous API components can be mapped to the upcoming changes: 1. Runner - A component that runs a command with parameters in a specific environment, in most cases a (binary) executable [9] of external commands or Go module `main` packages. The previous API component that can be compared to runners is `cast.Caster` [5] and its specialized interfaces. 2. Tasks - A component that is scoped for Mage "target" [11] usage in order to run a action. The previous API component that can be compared to tasks is`spell.Incantation` [12] and its specialized interfaces. >>> API Usage Even though the API has been changed quite heavily, the basic usage has almost not changed. -> A `task.Task` can only be run through a `task.Runner`! Before a `spell.Incantation` was passed to a `cast.Caster` in order to run it, in most cases a (binary) executable of a command that uses the `Formula() []string` method of `spell.Incantation` to pass the result a parameters. The new API works the same: A `task.Task` is passed to a `task.Runner` that calls the `BuildParams() []string` method when the runner is specialized for (binary) executable of commands. >>> Improved Documentations Before the documentation was mainly scoped on the technical details, but lacked more user-friendly sections about topics like the way how to implement own API components, how to compose the "elder" reference implementation [20] or usage examples for single or monorepo [21] project layouts. >>>> User Guide Most of the current sections have been rewritten or removed entirely while new sections now provide more user-friendly guides about how to... - use or compose the "elder" reference implementation [20]. - build own tasks and runners using the new API. - structure repositories independent of the layout, single or "monorepo". >>>> Usage Examples Some examples have been added, that are linked and documented in the user guides described above, to show how to... - use or compose the "elder" reference implementation [20]. - build own tasks and runners using the new API. - structure repositories independent of the layout, single or "monorepo". [1]: #14 [2]: https://en.wikipedia.org/wiki/Harry_Potter [3]: https://magefile.org [4]: https://pkg.go.dev/github.com/svengreb/wand/pkg/task#Runner [5]: https://pkg.go.dev/github.com/svengreb/wand/pkg/cast#Caster [6]: https://pkg.go.dev/github.com/svengreb/wand/pkg/task#Task [7]: https://pkg.go.dev/github.com/svengreb/wand/pkg/task#Kind [8]: https://pkg.go.dev/github.com/svengreb/wand/pkg/task#RunnerExec [9]: https://en.wikipedia.org/wiki/Executable [10]: https://pkg.go.dev/github.com/svengreb/wand/pkg/cast#BinaryCaster [11]: https://magefile.org/targets [12]: https://pkg.go.dev/github.com/svengreb/wand/pkg/spell#Incantation [13]: https://pkg.go.dev/github.com/svengreb/wand/pkg/task#Options [14]: https://pkg.go.dev/github.com/svengreb/wand/pkg/task#Exec [15]: https://pkg.go.dev/github.com/svengreb/wand/pkg/spell#Binary [16]: https://en.wikipedia.org/wiki/Command-line_interface#Anatomy_of_a_shell_CLI [17]: https://pkg.go.dev/github.com/svengreb/wand/pkg/task#GoModule [18]: https://pkg.go.dev/github.com/svengreb/wand/pkg/spell#GoModule [19]: https://golang.org/ref/mod [20]: https://pkg.go.dev/github.com/svengreb/wand/pkg/elder [21]: https://trunkbaseddevelopment.com/monorepos GH-49
svengreb
deleted the
feature/gh-49-“task-api-simpler-use-normal-naming
branch
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Resolves #49