657 lines
17 KiB
Markdown
657 lines
17 KiB
Markdown
# What is SprigX?
|
|
|
|
SprigX are extensions to [the `sprig`
|
|
library](https://masterminds.github.io/sprig/) ([Go
|
|
docs](https://pkg.go.dev/github.com/Masterminds/sprig/v3)).
|
|
|
|
They provide functions that offer more enriched use cases and
|
|
domain-specific data.
|
|
|
|
# How do I Use SprigX?
|
|
|
|
package main
|
|
|
|
import (
|
|
htmlTplLib "html/template"
|
|
txtTplLib "text/template"
|
|
|
|
"r00t2.io/goutils/tplx/sprigx"
|
|
)
|
|
|
|
var (
|
|
txtTpl *txtTplLib.Template = txtTplLib.
|
|
New("").
|
|
Funcs(
|
|
sprigx.TxtFuncMap(),
|
|
)
|
|
htmlTpl *htmlTplLib.Template = htmlTplLib.
|
|
New("").
|
|
Funcs(
|
|
sprigx.HtmlFuncMap(),
|
|
)
|
|
)
|
|
|
|
package main
|
|
|
|
import (
|
|
"text/template"
|
|
|
|
"github.com/Masterminds/sprig/v3"
|
|
"r00t2.io/goutils/tplx/sprigx"
|
|
)
|
|
|
|
var txtTpl *template.Template = template.
|
|
New("").
|
|
Funcs(
|
|
sprigx.TxtFuncMap(),
|
|
).
|
|
Funcs(
|
|
sprig.TxtFuncMap(),
|
|
)
|
|
// Or:
|
|
/*
|
|
var txtTpl *template.Template = template.
|
|
New("").
|
|
Funcs(
|
|
sprig.TxtFuncMap(),
|
|
).
|
|
Funcs(
|
|
sprigx.TxtFuncMap(),
|
|
)
|
|
*/
|
|
|
|
If a `<template>.FuncMap` is added via `.Funcs()` **after** template
|
|
parsing, it will override any functions of the same name of a
|
|
`<template>.FuncMap` **before** parsing.
|
|
|
|
For example, if both `sprig` and `sprigx` provide a function `foo`:
|
|
|
|
package main
|
|
|
|
import (
|
|
"text/template"
|
|
|
|
"github.com/Masterminds/sprig/v3"
|
|
"r00t2.io/goutils/tplx/sprigx"
|
|
)
|
|
|
|
const (
|
|
myTpl string = `{{ "This is an example template string." | foo }}`
|
|
)
|
|
|
|
var (
|
|
tpl *template.Template = template.Must(
|
|
template.
|
|
New("").
|
|
Funcs(sprig.TxtFuncMap()).
|
|
Parse(myTpl),
|
|
).
|
|
Funcs(sprigx.TxtFuncMap())
|
|
)
|
|
|
|
whereas
|
|
|
|
package main
|
|
|
|
import (
|
|
"text/template"
|
|
|
|
"github.com/Masterminds/sprig/v3"
|
|
"r00t2.io/goutils/tplx/sprigx"
|
|
)
|
|
|
|
const (
|
|
myTpl string = `{{ "This is an example template string." | foo }}`
|
|
)
|
|
|
|
var (
|
|
tpl *template.Template = template.Must(
|
|
template.
|
|
New("").
|
|
Funcs(sprigx.TxtFuncMap()).
|
|
Parse(myTpl),
|
|
).
|
|
Funcs(sprig.TxtFuncMap())
|
|
)
|
|
|
|
and a function can even be
|
|
|
|
This would override a function `foo` and `foo2` in `sprigx` from `foo`
|
|
and `foo2` from `sprig`, but leave all other `sprig` functions
|
|
untouched.
|
|
|
|
package main
|
|
|
|
import (
|
|
"text/template"
|
|
|
|
"github.com/Masterminds/sprig/v3"
|
|
"r00t2.io/goutils/tplx/sprigx"
|
|
)
|
|
|
|
const (
|
|
myTpl string = `{{ "This is an example template string." | foo }}`
|
|
)
|
|
|
|
var (
|
|
overrideFuncs template.FuncMap = sprig.TxtFuncMap()
|
|
tpl *template.Template = template.Must(
|
|
template.
|
|
New("").
|
|
Funcs(sprigx.TxtFuncMap()).
|
|
Parse(myTpl),
|
|
).
|
|
Funcs(
|
|
template.FuncMap(
|
|
map[string]any{
|
|
"foo": overrideFuncs["foo"],
|
|
"foo2": overrideFuncs["foo2"],
|
|
},
|
|
),
|
|
)
|
|
)
|
|
|
|
# Functions
|
|
|
|
Expect this list to grow over time, and potentially more frequently than
|
|
the `sprigx` functions.
|
|
|
|
## System/OS/Platform
|
|
|
|
### `sysArch`
|
|
|
|
Returns the [`runtime.GOARCH`](https://pkg.go.dev/runtime#GOARCH)
|
|
constant.
|
|
|
|
### `sysNumCpu`
|
|
|
|
Returns the value from
|
|
[`runtime.NumCPU`](https://pkg.go.dev/runtime#NumCPU).
|
|
|
|
### `sysOsName`
|
|
|
|
Returns the [`runtime.GOOS`](https://pkg.go.dev/runtime#GOOS) constant.
|
|
|
|
### `sysRuntime`
|
|
|
|
This function returns a `map[string]string` of various information from
|
|
the [`runtime` stdlib library](https://pkg.go.dev/runtime).
|
|
|
|
Specifically, the following are returned.
|
|
|
|
The value type is a direct link to the `runtime` documentation providing
|
|
more detail about the associated value.
|
|
|
|
Because all values are mapped as strings, they can be converted back to
|
|
their native type via e.g. the [Sprig conversion
|
|
functions](https://masterminds.github.io/sprig/conversion.html) if
|
|
necessary.
|
|
|
|
<table>
|
|
<caption><code>sysRuntime</code> Values</caption>
|
|
<colgroup>
|
|
<col style="width: 50%" />
|
|
<col style="width: 50%" />
|
|
</colgroup>
|
|
<thead>
|
|
<tr>
|
|
<th style="text-align: center;">Key</th>
|
|
<th style="text-align: center;">Value Type</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td style="text-align: center;"><p><code>compiler</code></p></td>
|
|
<td style="text-align: center;"><p><a
|
|
href="https://pkg.go.dev/runtime#Compiler">string</a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="text-align: center;"><p><code>arch</code></p></td>
|
|
<td style="text-align: center;"><p><a
|
|
href="https://pkg.go.dev/runtime#GOARCH">string</a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="text-align: center;"><p><code>os</code></p></td>
|
|
<td style="text-align: center;"><p><a
|
|
href="https://pkg.go.dev/runtime#GOOS">string</a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="text-align: center;"><p><code>maxprocs</code></p></td>
|
|
<td style="text-align: center;"><p><a
|
|
href="https://pkg.go.dev/runtime#GOMAXPROCS">int</a> <a href="#fn1"
|
|
class="footnote-ref" id="fnref1"
|
|
role="doc-noteref"><sup>1</sup></a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="text-align: center;"><p><code>cpu_cnt</code></p></td>
|
|
<td style="text-align: center;"><p><a
|
|
href="https://pkg.go.dev/runtime#NumCPU">int</a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="text-align: center;"><p><code>num_cgo</code></p></td>
|
|
<td style="text-align: center;"><p><a
|
|
href="https://pkg.go.dev/runtime#NumCgoCall">int</a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="text-align: center;"><p><code>num_go</code></p></td>
|
|
<td style="text-align: center;"><p><a
|
|
href="https://pkg.go.dev/runtime#NumGoroutine">int</a></p></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="text-align: center;"><p><code>go_ver</code></p></td>
|
|
<td style="text-align: center;"><p><a
|
|
href="https://pkg.go.dev/runtime#Version">string</a></p></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<section id="footnotes" class="footnotes footnotes-end-of-document"
|
|
role="doc-endnotes">
|
|
<hr />
|
|
<ol>
|
|
<li id="fn1"><p>For safety concerns, <code>sprigx</code> does not allow
|
|
<strong>setting</strong> <code>GOMAXPROCS</code>, this value only
|
|
contains the <strong>current</strong> <code>GOMAXPROCS</code> value.<a
|
|
href="#fnref1" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
|
|
</ol>
|
|
</section>
|
|
|
|
As a convenience, some of these values also have their own dedicated
|
|
functions as well:
|
|
|
|
- [](#fn_sys_arch)
|
|
|
|
- [](#fn_sys_numcpu)
|
|
|
|
- [](#fn_sys_os)
|
|
|
|
## Paths
|
|
|
|
### Generic
|
|
|
|
These operate similar to [the `path` stdlib
|
|
library](https://pkg.go.dev/path) and use a fixed `/` path separator.
|
|
|
|
#### `pathJoin`
|
|
|
|
`pathJoin` operates **exactly** like
|
|
[`path.Join`](https://pkg.go.dev/path#Join) in stdlib.
|
|
|
|
If you are joining paths in a pipeline, you almost assuredly want
|
|
[](#fn_path_gnrc_ppj) or [](#fn_path_gnrc_pspj) instead.
|
|
|
|
{{- pathJoin "a" "b" "c" }}
|
|
{{- pathJoin "/" "a" "b" "c" }}
|
|
{{- pathJoin "/a/b" "c" }}
|
|
|
|
renders as:
|
|
|
|
a/b/c
|
|
/a/b/c
|
|
/a/b/c
|
|
|
|
#### `pathPipeJoin`
|
|
|
|
`pathPipeJoin` operates like [](#fn_path_gnrc_pj) with one deviation:
|
|
the root/base path is expected to be **last** in the arguments.
|
|
|
|
This makes it much more suitable for use in template pipelines, as the
|
|
previous value in a pipeline is passed in as the last element to the
|
|
next pipe function.
|
|
|
|
{{- $myBase := "/a" -}}
|
|
{{- pathPipeJoin "b" "c" "a" }}
|
|
{{- pathPipeJoin "a" "b" "c" "/" }}
|
|
{{- $myBase | pathPipeJoin "b" "c" }}
|
|
|
|
renders as:
|
|
|
|
a/b/c
|
|
/a/b/c
|
|
/a/b/c
|
|
|
|
#### `pathSliceJoin`
|
|
|
|
`pathSliceJoin` joins a slice of path segment strings (`[]string`)
|
|
instead of a variadic sequence of strings.
|
|
|
|
The `splitList` function shown below is from the [`sprig` string slice
|
|
functions](https://masterminds.github.io/sprig/string_slice.html).
|
|
|
|
{{- $myList := "a,b,c" | splitList "," -}}
|
|
{{- $myList | pathSliceJoin }}
|
|
{{- ("a,b,c" | splitList ",") | pathSliceJoin }}
|
|
{{- ("/,a,b,c" | splitList ",") | pathSliceJoin }}
|
|
|
|
renders as:
|
|
|
|
a/b/c
|
|
a/b/c
|
|
/a/b/c
|
|
|
|
#### `pathSlicePipeJoin`
|
|
|
|
`pathSlicePipeJoin` operates like [](#fn_path_gnrc_ppj) in that it is
|
|
suitable for pipeline use in which the root/base path is passed in from
|
|
the pipeline, but it is like [](#fn_path_gnrc_psj) in that it then also
|
|
accepts a slice of path segments (`[]string`) to append to that base
|
|
path.
|
|
|
|
The `splitList` function shown below is from the [`sprig` string slice
|
|
functions](https://masterminds.github.io/sprig/string_slice.html).
|
|
|
|
{{- $myBase := "/a" -}}
|
|
{{- $myList := "b,c,d" | splitList "." -}}
|
|
{{- pathSlicePipeJoin $myList $myBase }}
|
|
{{- $myBase | pathSlicePipeJoin $myList }}
|
|
|
|
renders as:
|
|
|
|
/a/b/c
|
|
/a/b/c
|
|
|
|
#### `pathSubJoin`
|
|
|
|
`pathSubJoin` operates like [](#fn_path_gnrc_pj) but it expects an
|
|
explicit root/base path.
|
|
|
|
The pipeline-friendly equivalent of this is [](#fn_path_gnrc_ppj).
|
|
|
|
{{- pathSubJoin "/a/b" "c" }}
|
|
{{- pathSubJoin "/" "a" "b" "c" }}
|
|
{{- "c" | pathSubJoin "/" "a" "b" }}
|
|
|
|
renders as:
|
|
|
|
/a/b/c
|
|
/a/b/c
|
|
/a/b/c
|
|
|
|
### OS/Platform-Tailored
|
|
|
|
These operate similar to [the `path/filepath` stdlib
|
|
library](https://pkg.go.dev/path/filepath), and use the OS-specific
|
|
[`os.PathSeparator`](https://pkg.go.dev/os#PathSeparator).
|
|
|
|
Take special note of the oddness around specifying Windows paths and
|
|
drive letters in e.g. [](#fn_path_os_pj)!
|
|
|
|
It is recommended to make use of [](#fn_sys_os) to conditionally format
|
|
path bases/roots if needed.
|
|
|
|
#### `osPathJoin`
|
|
|
|
`osPathJoin` operates **exactly** like
|
|
[`path/filepath.Join`](https://pkg.go.dev/path/filepath#Join) in stdlib.
|
|
|
|
If you are joining paths in a pipeline, you almost assuredly want
|
|
[](#fn_path_os_ppj) or [](#fn_path_os_pspj) instead.
|
|
|
|
{{- osPathJoin "a" "b" "c" }}
|
|
{{- osPathJoin "/" "a" "b" "c" }}
|
|
{{- osPathJoin "C:\\" "a" "b" "c" }}
|
|
{{- osPathJoin "C:" "a" "b" "c" }}
|
|
|
|
renders as:
|
|
|
|
<table>
|
|
<colgroup>
|
|
<col style="width: 33%" />
|
|
<col style="width: 66%" />
|
|
</colgroup>
|
|
<thead>
|
|
<tr>
|
|
<th style="text-align: center;">OS</th>
|
|
<th style="text-align: center;">Result</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td style="text-align: center;"><p>Windows</p></td>
|
|
<td style="text-align: left;"><pre class="text"><code>a\b\c
|
|
\a\b\c
|
|
\a\b\c
|
|
C:\a\b\c
|
|
C:a\b\c</code></pre></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="text-align: center;"><p>Others (e.g. Linux, macOS)</p></td>
|
|
<td style="text-align: left;"><pre class="text"><code>a/b/c
|
|
/a/b/c
|
|
C:\/a/b/c
|
|
C:/a/b/c</code></pre></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
#### `osPathPipeJoin`
|
|
|
|
`osPathPipeJoin` operates like [](#fn_path_gnrc_ppj) (except using
|
|
OS-specific path separators).
|
|
|
|
This makes it much more suitable for use in template pipelines, as the
|
|
previous value in a pipeline is passed in as the last element to the
|
|
next pipe function.
|
|
|
|
{{- $myBase := "/a" -}}
|
|
{{- osPathPipeJoin "b" "c" "a" }}
|
|
{{- osPathPipeJoin "a" "b" "c" "/" }}
|
|
{{- $myBase | osPathPipeJoin "b" "c" }}
|
|
|
|
renders as:
|
|
|
|
<table>
|
|
<colgroup>
|
|
<col style="width: 33%" />
|
|
<col style="width: 66%" />
|
|
</colgroup>
|
|
<thead>
|
|
<tr>
|
|
<th style="text-align: center;">OS</th>
|
|
<th style="text-align: center;">Result</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td style="text-align: center;"><p>Windows</p></td>
|
|
<td style="text-align: left;"><pre class="text"><code>a\b\c
|
|
\a\b\c
|
|
\a\b\c</code></pre></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="text-align: center;"><p>Others (e.g. Linux, macOS)</p></td>
|
|
<td style="text-align: left;"><pre class="text"><code>a/b/c
|
|
/a/b/c
|
|
/a/b/c</code></pre></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
#### `osPathSep`
|
|
|
|
`osPathSep` returns the
|
|
[`os.PathSeparator`](https://pkg.go.dev/os#PathSeparator) for this OS.
|
|
|
|
{{- osPathSep }}
|
|
|
|
renders as:
|
|
|
|
<table>
|
|
<colgroup>
|
|
<col style="width: 33%" />
|
|
<col style="width: 66%" />
|
|
</colgroup>
|
|
<thead>
|
|
<tr>
|
|
<th style="text-align: center;">OS</th>
|
|
<th style="text-align: center;">Result</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td style="text-align: center;"><p>Windows</p></td>
|
|
<td style="text-align: left;"><pre class="text"><code>\</code></pre></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="text-align: center;"><p>Others (e.g. Linux, macOS)</p></td>
|
|
<td style="text-align: left;"><pre class="text"><code>/</code></pre></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
#### `osPathSliceJoin`
|
|
|
|
`osPathSliceJoin` operates like [](#fn_path_gnrc_psj) but with
|
|
OS-specific path separators.
|
|
|
|
The `splitList` function shown below is from the [`sprig` string slice
|
|
functions](https://masterminds.github.io/sprig/string_slice.html).
|
|
|
|
{{- $myList := "a,b,c" | splitList "," -}}
|
|
{{- $myList | osPathSliceJoin }}
|
|
{{- ("a,b,c" | splitList ",") | osPathSliceJoin }}
|
|
{{- ("/,a,b,c" | splitList ",") | osPathSliceJoin }}
|
|
|
|
renders as:
|
|
|
|
<table>
|
|
<colgroup>
|
|
<col style="width: 33%" />
|
|
<col style="width: 66%" />
|
|
</colgroup>
|
|
<thead>
|
|
<tr>
|
|
<th style="text-align: center;">OS</th>
|
|
<th style="text-align: center;">Result</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td style="text-align: center;"><p>Windows</p></td>
|
|
<td style="text-align: left;"><pre class="text"><code>a\b\c
|
|
a\b\c
|
|
\a\b\c</code></pre></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="text-align: center;"><p>Others (e.g. Linux, macOS)</p></td>
|
|
<td style="text-align: left;"><pre class="text"><code>a/b/c
|
|
a/b/c
|
|
/a/b/c</code></pre></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
#### `osPathSlicePipeJoin`
|
|
|
|
`osPathSlicePipeJoin` operates like [](#fn_path_gnrc_pspj) but with
|
|
OS-specific separators.
|
|
|
|
The `splitList` function shown below is from the [`sprig` string slice
|
|
functions](https://masterminds.github.io/sprig/string_slice.html).
|
|
|
|
{{- $myBase := "/a" -}}
|
|
{{- $myList := "b,c,d" | splitList "." -}}
|
|
{{- osPathSlicePipeJoin $myList $myBase }}
|
|
{{- $myBase | osPathSlicePipeJoin $myList }}
|
|
|
|
renders as:
|
|
|
|
<table>
|
|
<colgroup>
|
|
<col style="width: 33%" />
|
|
<col style="width: 66%" />
|
|
</colgroup>
|
|
<thead>
|
|
<tr>
|
|
<th style="text-align: center;">OS</th>
|
|
<th style="text-align: center;">Result</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td style="text-align: center;"><p>Windows</p></td>
|
|
<td style="text-align: left;"><pre class="text"><code>\a\b\c\d
|
|
\a\b\c\d</code></pre></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="text-align: center;"><p>Others (e.g. Linux, macOS)</p></td>
|
|
<td style="text-align: left;"><pre class="text"><code>/a/b/c/d
|
|
/a/b/c/d</code></pre></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
#### `osPathSubJoin`
|
|
|
|
`osPathSubJoin` operates like [](#fn_path_gnrc_psubj) but with
|
|
OS-specific separators.
|
|
|
|
The pipeline-friendly equivalent of this is [](#fn_path_os_ppj).
|
|
|
|
{{- osPathSubJoin "/a/b" "c" }}
|
|
{{- osPathSubJoin "/" "a" "b" "c" }}
|
|
{{- "c" | osPathSubJoin "/" "a" "b" }}
|
|
|
|
renders as:
|
|
|
|
<table>
|
|
<colgroup>
|
|
<col style="width: 33%" />
|
|
<col style="width: 66%" />
|
|
</colgroup>
|
|
<thead>
|
|
<tr>
|
|
<th style="text-align: center;">OS</th>
|
|
<th style="text-align: center;">Result</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td style="text-align: center;"><p>Windows</p></td>
|
|
<td style="text-align: left;"><pre class="text"><code>\a\b\c
|
|
\a\b\c
|
|
\a\b\c</code></pre></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="text-align: center;"><p>Others (e.g. Linux, macOS)</p></td>
|
|
<td style="text-align: left;"><pre class="text"><code>/a/b/c
|
|
/a/b/c
|
|
/a/b/c</code></pre></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
## Strings
|
|
|
|
### `extIndent`
|
|
|
|
`extIndent` allows for a MUCH more flexible indenter than the `sprig`
|
|
`indent` function.
|
|
|
|
It works with both Windows (`\r\n`) and POSIX (`\n`) linebreaks.
|
|
|
|
It has quite a few arguments, however:
|
|
|
|
{{ extIndent <levels> <skipFirst> <skipEmpty> <skipWhitespace> <indentString> <input> }}
|
|
|
|
Where:
|
|
|
|
- `<levels>`: The level of indentation for the text. If less than or
|
|
equal to `0`, `extIndent` just returns `<input>` as-is and NO-OPs
|
|
otherwise.
|
|
|
|
- `<skipFirst>`: If true, skip indenting the first line. This is
|
|
particularly handy if you like to visually align your function calls
|
|
in your templates.
|
|
|
|
- `<skipEmpty>`: If true, do not add an indent to **empty** lines
|
|
(where an "empty line" means "only has a linebreak").
|
|
|
|
- `<skipWhitespace>`: If true, do not add an indent to lines that
|
|
**only** consist of whitespace (spaces, tabs, etc.) and a linebreak.
|
|
|
|
- `<indentString>`: The string to use as the "indent character". This
|
|
can be any string, such as `" "`, `"\t"`, `"."`, `"|"`, `"=="` etc.
|
|
|
|
- `<input>`: The text to be indented. Because it is the last argument,
|
|
`extIndent` works with pipelined text as well.
|