From 42a1bcdd99c2531f52157eeeb2571ffad915a287 Mon Sep 17 00:00:00 2001 From: kozmod Date: Tue, 10 Dec 2024 22:18:49 +0300 Subject: [PATCH] [#102] fist version of `lib`'s docs. --- Readme.md | 141 +++++++++++++++++++++++++++++---- internal/factory/chain_exec.go | 8 ++ pkg/core/entity.go | 5 ++ 3 files changed, 137 insertions(+), 17 deletions(-) diff --git a/Readme.md b/Readme.md index 222e30e..9613246 100644 --- a/Readme.md +++ b/Readme.md @@ -9,7 +9,7 @@ [![GitHub MIT license](https://img.shields.io/github/license/kozmod/progen)](https://github.com/kozmod/progen/blob/main/LICENSE) A flexible, language and frameworks agnostic tool that allows you to generate projects structure from templates based -on `yaml` configuration (generate directories, files and execute commands). +on `yaml` configuration (generate directories, files and execute commands) or use as library to build custom generator. ___ ### Installation @@ -23,27 +23,36 @@ go install github.com/kozmod/progen@latest ```shell make build ``` +### Use as `lib` [**ⓘ**](#lib_usage) +```go +module github.com/some/custom_gen + +go 1.22 + +require github.com/kozmod/progen v0.1.8 +``` ___ ### Flags -| Name | Type | Default | Description | -|:------------------------------------------------|:--------:|:------------:|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `-f`[**ⓘ**](#config_file) | string | `progen.yml` | specify configuration file path | -| `-v` | bool | `false` | verbose output | -| `-dr`[**ⓘ**](#dry_run) | bool | `false` | `dry run` mode
(to verbose output should be combine with`-v`) | -| `-awd`[**ⓘ**](#awd) | string | `.` | application working directory | -| `-printconf`[**ⓘ**](#print_config) | bool | `false` | output processed config | -| `-errtrace`[**ⓘ**](#print_err_trace) | bool | `false` | output errors stack trace | -| `-pf`[**ⓘ**](#files_preprocessing) | bool | `true` | `preprocessing files`: load and process all files
(all files `actions`[**ⓘ**](#files_actio_desk)) as [text/template](https://pkg.go.dev/text/template) before creating | -| `-tvar`[**ⓘ**](#tvar) | []string | `[ ]` | [text/template](https://pkg.go.dev/text/template) variables
(override config variables tree) | -| `-missingkey` | []string | `error` | set `missingkey`[text/template.Option](https://pkg.go.dev/text/template#Template.Option) execution option | -| `-skip`[**ⓘ**](#skip_actions) | []string | `[ ]` | skip any `action` tag
(regular expression) | -| `-gp`[**ⓘ**](#groups_of_actions) | []string | `[ ]` | set of the action's groups to execution | -| `-version` | bool | `false` | print version | -| `-help` | bool | `false` | show flags | - +| Name | Type | Default | Description | +|:----------------------------------------------------------------------|:--------:|:------------:|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `-f`[**ⓘ**](#config_file) **✱** | string | `progen.yml` | specify configuration file path | +| `-v` **✱** | bool | `false` | verbose output | +| `-dr`[**ⓘ**](#dry_run) **✱** | bool | `false` | `dry run` mode
(to verbose output should be combine with`-v`) | +| `-awd`[**ⓘ**](#awd) | string | `.` | application working directory | +| `-printconf`[**ⓘ**](#print_config) | bool | `false` | output processed config | +| `-errtrace`[**ⓘ**](#print_err_trace) **✱** | bool | `false` | output errors stack trace | +| `-pf`[**ⓘ**](#files_preprocessing) | bool | `true` | `preprocessing files`: load and process all files
(all files `actions`[**ⓘ**](#files_actio_desk)) as [text/template](https://pkg.go.dev/text/template) before creating | +| `-tvar`[**ⓘ**](#tvar) **✱** | []string | `[ ]` | [text/template](https://pkg.go.dev/text/template) variables
(override config variables tree) | +| `-missingkey` **✱** | []string | `error` | set `missingkey`[text/template.Option](https://pkg.go.dev/text/template#Template.Option) execution option | +| `-skip`[**ⓘ**](#skip_actions) | []string | `[ ]` | skip any `action` tag
(regular expression) | +| `-gp`[**ⓘ**](#groups_of_actions) | []string | `[ ]` | set of the action's groups to execution | +| `-version` | bool | `false` | print version | +| `-help` **✱** | bool | `false` | show flags | + +**✱** flags accessible in the `lib`. ___ ### Actions and tags @@ -765,6 +774,104 @@ rm: 2024-02-09 22:50:51 INFO execution time: 350.149µs ``` +--- + +### Lib + +To use `progen` for building custom generator based on `go` language, imports `pkg/core` package +and implements required algorithm: +```golang +package main + +import ( + "log" + "testing/fstest" + + "github.com/kozmod/progen/pkg/core" +) + +var fs = fstest.MapFS{ + "1": { + Data: []byte("aaaa"), + }, +} + +func main() { + // Parse default config base on flags + c, err := core.ParseFlags() + if err != nil { + log.Fatal(err) + } + + var e core.Engin + + // add actions + e.AddActions( + // create files actions + core.FilesAction( + "create_file", + core.File{Path: "./xx/1", Data: []byte("file_1")}, + core.File{Path: "./xx/2", Data: []byte("file_2")}, + core.File{Path: "./xx/rm_1", Data: []byte("file_rm")}, + ).WithPriority(1), + // rm actions + core.RmAction( + "rm", + "./rm_1", + ).WithPriority(2), + ) + e.AddActions( + // create file system action + core.FsSaveAction( + "fs_1", + core.TargetFs{ + TargetDir: "./xx/fs", + Fs: fs, // any [io/fs.FS] (from local system, embed, etc.) + }, + ).WithPriority(3), + + // cmd action + core.CmdAction( + "tree_1", + core.Cmd{ + Cmd: "tree", + Dir: "./xx", + }, + ).WithPriority(4), + ) + + err = e.Run(c) + if err != nil { + log.Fatal(err) + } +} + +``` +```console +% go build . +% ./tmp -v +2024-12-10 21:56:55 INFO action is going to be execute ('priopiry':'name')['1':'create_file','2':'rm','3':'fs_1','4':'tree_1'] +2024-12-10 21:56:55 INFO file saved: xx/1 +2024-12-10 21:56:55 INFO file saved: xx/2 +2024-12-10 21:56:55 INFO file saved: xx/rm_1 +2024-12-10 21:56:55 INFO rm: ./rm_1 +2024-12-10 21:56:55 INFO dir created: xx/fs +2024-12-10 21:56:55 INFO file saved: xx/fs/1 +2024-12-10 21:56:55 INFO execute [dir: ./xx]: tree +out: +. +├── 1 +├── 2 +├── fs +│   └── 1 +└── rm_1 + +1 directory, 4 files + +``` + + + --- ### Examples diff --git a/internal/factory/chain_exec.go b/internal/factory/chain_exec.go index ea15243..895111b 100644 --- a/internal/factory/chain_exec.go +++ b/internal/factory/chain_exec.go @@ -1,7 +1,9 @@ package factory import ( + "fmt" "sort" + "strings" "golang.org/x/xerrors" @@ -50,6 +52,12 @@ func (f ExecutorChainFactory) Create() (entity.Executor, error) { return allBuilders[i].Priority < allBuilders[j].Priority }) + actionNames := make([]string, len(allBuilders)) + for i, builder := range allBuilders { + actionNames[i] = fmt.Sprintf("'%d':'%s'", builder.Priority, builder.Action) + } + f.logger.Infof("action is going to be execute ('priopiry':'name')[%s]", strings.Join(actionNames, ",")) + executors := make([]entity.Executor, 0, len(allBuilders)) for _, builder := range allBuilders { e, err := builder.ProcFn() diff --git a/pkg/core/entity.go b/pkg/core/entity.go index 25f75c5..b9eddb9 100644 --- a/pkg/core/entity.go +++ b/pkg/core/entity.go @@ -37,6 +37,11 @@ func (c Files) add(e *Engin) { } } +func (c Files) WithPriority(priority int) Files { + c.Priority = priority + return c +} + func FilesAction(name string, files ...File) Files { return Files{ Name: name,