diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..db7ba3f --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +**/*.md whitespace=space-before-tab diff --git a/README.md b/README.md index d8f457c..2045d26 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,12 @@ -# YAMPL +# Yampl -YAMPL (yaml + tmpl) is a simple templating tool that can template yaml values based on line-comments. +[![Go](https://github.com/clevyr/go-yampl/actions/workflows/go.yml/badge.svg)](https://github.com/clevyr/go-yampl/actions/workflows/go.yml) + +Yampl (yaml + tmpl) is a simple tool to template yaml values based on line-comments. ## Installation -YAMPL is available in brew or as a Docker container. +Yampl is available in brew or as a Docker container. #### Brew @@ -18,14 +20,8 @@ brew install clevyr/tap/yampl docker pull ghcr.io/clevyr/yampl ``` -## Usage - -[View the help docs for usage information.](docs/yampl.md) - ## Templating - - ### Functions All [Sprig functions](https://masterminds.github.io/sprig/) are available in templates, along with some extra functions: @@ -48,12 +44,25 @@ The above produces `stable-alpine` ### Variables -All variables passed in with the `-v` flag are available during templating. -For example, a variable given as `-v tag=latest` can be used as `{{ .tag }}`. +All variables passed in with the `-v` flag are available during templating. +For example, the variable `-v tag=latest` can be used as `{{ .tag }}`. The previous value is always available via `.Value` (`.Val` or `.V` if you're feeling lazy). -### Example +### Examples + +## Simple Examples + +```shell +$ echo 'name: Clevyr #yampl {{ .name }}' | yampl -v name='Clevyr Inc.' +name: Clevyr Inc. #yampl {{ .name }} +$ echo 'name: Clevyr #yampl {{ upper .Value }}' | yampl +name: CLEVYR #yampl {{ upper .Value }} +$ echo 'image: nginx:stable-alpine #yampl {{ repo .Value }}:{{ .tag }}' | yampl -v tag=stable +image: nginx:stable #yampl {{ repo .Value }}:{{ .tag }} +``` + +## Full Example Here is a simple Kubernetes nginx Deployment: @@ -115,3 +124,7 @@ image: nginx:1.21.6 #yampl {{ repo .Value }}:{{ .tag }} This would generate the same output, but I didn't have to type `nginx` twice. This becomes more useful when using custom Docker registries where repo names can get quite long. + +## Usage + +[View the generated docs for usage information.](docs/yampl.md) diff --git a/cmd/cmd.go b/cmd/cmd.go index 0d6dcb2..5260646 100644 --- a/cmd/cmd.go +++ b/cmd/cmd.go @@ -2,6 +2,7 @@ package cmd import ( "bytes" + _ "embed" "errors" "fmt" "github.com/clevyr/go-yampl/internal/config" @@ -14,9 +15,13 @@ import ( "strings" ) +//go:embed description.md +var description string + var Command = &cobra.Command{ Use: "yampl [-i] [-p prefix] [-v key=value ...] [file ...]", Short: "Inline YAML templating via line-comments", + Long: description, DisableFlagsInUseLine: true, DisableAutoGenTag: true, ValidArgsFunction: validArgs, @@ -28,10 +33,10 @@ var Command = &cobra.Command{ var conf config.Config func init() { - Command.Flags().BoolVarP(&conf.Inline, "inline", "i", false, "Edit files in-place") - Command.Flags().StringVarP(&conf.Prefix, "prefix", "p", "#yampl", "Template prefix. Must begin with '#'") - Command.Flags().StringVar(&conf.LeftDelim, "left-delim", "{{", "Override the default left delimiter") - Command.Flags().StringVar(&conf.RightDelim, "right-delim", "}}", "Override the default right delimiter") + Command.Flags().BoolVarP(&conf.Inline, "inline", "i", false, "Edit files in-place instead of printing to stdout") + Command.Flags().StringVarP(&conf.Prefix, "prefix", "p", "#yampl", "Line-comments are ignored unless this prefix is found. Prefix must begin with '#'") + Command.Flags().StringVar(&conf.LeftDelim, "left-delim", "{{", "Override the left delimiter") + Command.Flags().StringVar(&conf.RightDelim, "right-delim", "}}", "Override the right delimiter") } func validArgs(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) { diff --git a/cmd/description.md b/cmd/description.md new file mode 100644 index 0000000..e5d429f --- /dev/null +++ b/cmd/description.md @@ -0,0 +1,24 @@ +Yampl (yaml + tmpl) is a simple tool to template yaml values based on line-comments. + +This command can work on stdin/stdout or on files similarly to GNU sed: + - If not positional args are given, it will listen for input on stdin. + - It will continue to read input until EOF is encountered. + - By default, it will print to stdout. + - The `-i` flag will make it update files in-place. + - Multiple files can be given, and they will all be templated. + +Simple Examples (Full example at https://github.com/clevyr/go-yampl#examples): + + $ echo 'name: Clevyr #yampl {{ .name }}' | yampl -v name='Clevyr Inc.' + name: Clevyr Inc. #yampl {{ .name }} + $ echo 'name: Clevyr #yampl {{ upper .Value }}' | yampl + name: CLEVYR #yampl {{ upper .Value }} + $ echo 'image: nginx:stable-alpine #yampl {{ repo .Value }}:{{ .tag }}' | yampl -v tag=stable + image: nginx:stable #yampl {{ repo .Value }}:{{ .tag }} + +Template Function Reference: + - https://github.com/clevyr/go-yampl#functions + - https://masterminds.github.io/sprig/ + +Template Variable Reference: + - https://github.com/clevyr/go-yampl#variables diff --git a/cmd/flag_values.go b/cmd/flag_values.go index ef39e06..dcd7bac 100644 --- a/cmd/flag_values.go +++ b/cmd/flag_values.go @@ -16,7 +16,7 @@ import ( ) func init() { - Command.Flags().StringToStringVarP((*map[string]string)(&conf.Values), "value", "v", map[string]string{}, "Define a template variable") + Command.Flags().StringToStringVarP((*map[string]string)(&conf.Values), "value", "v", map[string]string{}, "Define a template variable. Can be used more than once.") err := Command.RegisterFlagCompletionFunc("value", valueCompletion) if err != nil { panic(err) diff --git a/docs/yampl.md b/docs/yampl.md index 204271e..8459785 100644 --- a/docs/yampl.md +++ b/docs/yampl.md @@ -2,6 +2,34 @@ Inline YAML templating via line-comments +### Synopsis + +Yampl (yaml + tmpl) is a simple tool to template yaml values based on line-comments. + +This command can work on stdin/stdout or on files similarly to GNU sed: + - If not positional args are given, it will listen for input on stdin. + - It will continue to read input until EOF is encountered. + - By default, it will print to stdout. + - The `-i` flag will make it update files in-place. + - Multiple files can be given, and they will all be templated. + +Simple Examples (Full example at https://github.com/clevyr/go-yampl#examples): + + $ echo 'name: Clevyr #yampl {{ .name }}' | yampl -v name='Clevyr Inc.' + name: Clevyr Inc. #yampl {{ .name }} + $ echo 'name: Clevyr #yampl {{ upper .Value }}' | yampl + name: CLEVYR #yampl {{ upper .Value }} + $ echo 'image: nginx:stable-alpine #yampl {{ repo .Value }}:{{ .tag }}' | yampl -v tag=stable + image: nginx:stable #yampl {{ repo .Value }}:{{ .tag }} + +Template Function Reference: + - https://github.com/clevyr/go-yampl#functions + - https://masterminds.github.io/sprig/ + +Template Variable Reference: + - https://github.com/clevyr/go-yampl#variables + + ``` yampl [-i] [-p prefix] [-v key=value ...] [file ...] ``` @@ -10,12 +38,11 @@ yampl [-i] [-p prefix] [-v key=value ...] [file ...] ``` --completion string Output command-line completion code for the specified shell. Can be 'bash', 'zsh', 'fish', or 'powershell'. - -C, --directory string dir to hold the generated config (default "./docs") -h, --help help for yampl - -i, --inline Edit files in-place - --left-delim string Override the default left delimiter (default "{{") - -p, --prefix string Template prefix. Must begin with '#' (default "#yampl") - --right-delim string Override the default right delimiter (default "}}") - -v, --value stringToString Define a template variable (default []) + -i, --inline Edit files in-place instead of printing to stdout + --left-delim string Override the left delimiter (default "{{") + -p, --prefix string Line-comments are ignored unless this prefix is found. Prefix must begin with '#' (default "#yampl") + --right-delim string Override the right delimiter (default "}}") + -v, --value stringToString Define a template variable. Can be used more than once. (default []) ```