“Task“ API: Simplified usage and “normalized“ naming scheme #49
Labels
Milestone
Comments
svengreb
changed the title
svengreb
added a commit
that referenced
this issue
Dec 7, 2020
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
added a commit
that referenced
this issue
Dec 7, 2020
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 Closes GH-49
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
With #14 the “abstract“ wand API was introduced with a naming scheme is inspired by the fantasy novel “Harry Potter“ 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, but in retrospect this is way too abstract and confusing.
The goal of this ticket is to…
New API Concept
The basic mindset of the API will remain partially the same, but it will be designed around the concept of tasks and the ways to run them.
Command Runner
🅸
task.Runneris a new base interface that runs a command with parameters in a specific environment. It can be compared to the current 🅸cast.Casterinterface, but provides a cleaner method set accepting the new 🅸task.Taskinterface.Handles() task.Kind— returns the supported task kind.Run(task.Task) error— runs a command.Validate() error— validates the runner.The new 🅸
task.RunnerExecinterface is a specializedtask.Runnerand serves as an abstract representation for a command or action, in most cases a (binary) executable of external commands or Go modulemainpackages, that provides corresponding information like the path to the executable. It can be compared to the currentBinaryCasterinterface, but also comes with a cleaner method set and a more appropriate name.FilePath() string— returns the path to the (binary) command executable.Tasks
🅸
task.Taskis the new interface that is scoped for Mage “target“ usage. It can be compared to the current 🅸spell.Incantationinterface, but provides a smaller method set withoutFormula() []string.Kind() task.Kind— returns the task kind.Options() task.Options— returns the task options.The new 🅸
task.Execinterface is a specializedtask.Taskand serves as an abstract task for an executable command. It can be compared to the currentBinaryinterface, but also comes with the newBuildParams() []stringmethod that enables a more flexible usage by exposing the parameters for command runner liketask.RunnerExecand also allows to compose with other tasks. See the Wikipedia page about the anatomy of a shell CLI for more details about parameters.BuildParams() []string— builds the parameters for a command runner where parameters can consist of options, flags and arguments.Env() map[string]string— returns the task specific environment.The new 🅸
task.GoModuleinterface is a specializedtask.Execfor a executable Go module command. It can be compared to the currentspell.GoModuleinterface and the method set has not changed except a renaming of theGoModuleID() *project.GoModuleIDto the more appropriate nameID() *project.GoModuleID. See the official Go module reference documentation for more details about Go modules.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 current API components can be mapped to the upcoming changes:
mainpackages. The current API component that can be compared to runners is 🅸cast.Casterand its specialized interfaces.spell.Incantationand its specialized interfaces.API Usage
Even though the API will be changed quite heavily, the basic usage almost won't change.
→ A
task.Taskcan only be run through atask.Runner!Currently a
spell.Incantationis passed to acast.Casterin order to run it, in most cases a (binary) executable of a command that uses theFormula() []stringmethod ofspell.Incantationto pass the result as parameters.The new API works the same: A
task.Taskis passed to atask.Runnerthat calls theBuildParams() []stringmethod when the runner is specialized for (binary) executable of commands.Improved Documentations
The current documentation is mainly scoped on the technical details, but lacks more user-friendly sections about topics like the way how to implement own API components, how to compose the “elder“ reference implementation or usage examples for single or monorepo project layouts
User Guide
Most of the current sections will be rewritten or removed entirely while new sections will provide more user-friendly guides about how to…
Usage Examples
Some examples will be added, that are linked and documented in the user guides described above, to show how to…
The text was updated successfully, but these errors were encountered: