## 1. What is SprigX?
SprigX is a suite of extensions to
the
sprig library
(Go docs).
They provide functions that offer more enriched use cases and
domain-specific data.
Tip
|
If you are reading this README on the Go Module Directory documentation (https://pkg.go.dev/r00t2.io/goutils/tplx/sprigx) or the directory landing page (https://git.r00t2.io/r00t2/go_goutils/src/branch/master/tplx/sprigx), it may not render correctly. Be sure to view it at properly via the AsciiDoc rendering or by downloading and viewing the HTML version and/or PDF version. |
## 2. How do I Use SprigX?
The same way you would `sprig`!
Like this.
``` rouge
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(),
)
)
```
They can even be combined/used together.
Like this.
``` rouge
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(),
)
*/
```
Or, as a convenience, you can simply use the
[`sprigx.CombinedTxtFuncMap`](#lib_cmbtfmap) and/or
[`sprigx.CombinedHtmlFuncMap`](#lib_cmbhfmap) functions.
If a `.FuncMap` is added via `.Funcs()` **after** template
parsing, it will override any functions of the same name of a
`.FuncMap` **before** parsing.
For example, if both `sprig` and `sprigx` provide a function `foo`:
this will use `foo` from `sprigx`
(show)
``` rouge
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 this will use `foo` from `sprig`
(show)
``` rouge
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 explicitly
overridden.
(show)
This would override a function `foo` and `foo2` in `sprigx` from `foo`
and `foo2` from `sprig`, but leave all other `sprig` functions
untouched.
``` rouge
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"],
},
),
)
)
```
## 3. Library Functions
These are generally intended to be used **outside** the template in the
actual Go code.
### 3.1.
CombinedFuncMap
Function Signature
``` rouge
func CombinedFuncMap(preferSprigX bool) (fmap map[string]any)
```
This function returns a generic function map (like
[`FuncMap`](#lib_fmap)) combined with
github.com/Masterminds/sprig/v3.GenericFuncMap.
If `preferSprigx` is true, SprigX function names will override Sprig
functions with the same name. If false, Sprig functions will override
conflicting SprigX functions with the same name.
You probably want [`CombinedTxtFuncMap`](#lib_cmbtfmap) or
[`CombinedHtmlFuncMap`](#lib_cmbhfmap) instead, as they wrap this with
the appropriate type.
### 3.2.
CombinedHtmlFuncMap
Function Signature
``` rouge
func CombinedHtmlFuncMap(preferSprigX bool) (fmap template.FuncMap)
```
This function returns an
[`html/template.FuncMap`](https://pkg.go.dev/html/template#FuncMap)
function map (like [`HtmlFuncMap`](#lib_hfmap)) combined with
github.com/Masterminds/sprig/v3.HtmlFuncMap.
If `preferSprigx` is true, SprigX function names will override Sprig
functions with the same name. If false, Sprig functions will override
conflicting SprigX functions with the same name.
### 3.3.
CombinedTxtFuncMap
Function Signature
``` rouge
func CombinedTxtFuncMap(preferSprigX bool) (fmap template.FuncMap)
```
This function returns a
[`text/template.FuncMap`](https://pkg.go.dev/text/template#FuncMap)
function map (like [`TxtFuncMap`](#lib_tfmap)) combined with
github.com/Masterminds/sprig/v3.TxtFuncMap.
If `preferSprigx` is true, SprigX function names will override Sprig
functions with the same name. If false, Sprig functions will override
conflicting SprigX functions with the same name.
### 3.4.
FuncMap
Function Signature
``` rouge
func FuncMap() (fmap map[string]any)
```
This function returns a generic SprigX function map.
You probably want [`TxtFuncMap`](#lib_tfmap) or
[`HtmlFuncMap`](#lib_hfmap) instead, as they wrap this with the
appropriate type.
### 3.5.
HtmlFuncMap
Function Signature
``` rouge
func HtmlFuncMap() (fmap template.FuncMap)
```
This function returns a SprigX
html/template.FuncMap.
### 3.6.
Nop
Function Signature
``` rouge
func Nop(obj ...any) (s string)
```
`Nop` is a NO-OP function that one can use in an [override
map](#override) to explicitly disable certain Sprig/SprigX functions
that may be deemed "unsafe" and/or to sanitize templates from untrusted
input.
It will **never** error or panic, and `s` is **always** an empty string.
### 3.7.
TxtFuncMap
Function Signature
``` rouge
func TxtFuncMap() (fmap template.FuncMap)
```
This function returns a SprigX
text/template.FuncMap.
## 4. Template Functions
Expect this list to grow over time, and potentially more frequently than
the `sprigx` functions.
Each function includes its ***Function Signature*** to indicate what
arguments/parameters it accepts, their type(s), what it returns, and the
returned value(s) type(s).
Because Go template functions can only return either:
- a single value of any type, or
- a value of any type and an `error` (in that order)
you can easily determine whether a function can return an error or not
by simply referring to the Function Signature.
### 4.1. Debugging
#### 4.1.1.
dump
Function Signature
``` rouge
func dump(a ...interface{}) (out string)
```
The `dump` function directly calls
github.com/davecgh/go-spew/spew.Sdump
for whatever object(s) is/are passed to it.
### 4.2. "Meta"/Template Helpers
#### 4.2.1.
metaIsNil
Function Signature
``` rouge
func metaIsNil(obj any) (isNil bool)
```
`metaIsNil` returns `true` if `obj` is explicitly nil, otherwise it
returns false.
This function fills in the gap that
text/template.IsTrue and
html/template.IsTrue (expressed in
templates as `{{ if … }}`) leaves, as those functions/expressions return
false for e.g. `false` booleans AND nils.
### 4.3. Networking
These template functions use capabilities from:
- [`net`](#fn_net)
- [`net/netip`](#fn_netip)
- [`go4.org/netipx`](#fn_netipx)
The function prefix is used to indicate which module/package a function
is added from.
#### 4.3.1.
net
These template functions contain capabilities from
net.
##### 4.3.1.1.
netCidrMask
Function Signature
``` rouge
func netCidrMask(ones, bits int) (mask net.IPMask)
```
`netCidrMask` directly calls
net.CIDRMask.
##### 4.3.1.2.
netExtractAddr
Function Signature
``` rouge
func netExtractAddr(s string) (addr net.IP, err error)
```
`netExtractAddr` wraps
net.ParseCIDR and returns the
net.IP component.
##### 4.3.1.3.
netExtractHost
Function Signature
``` rouge
func netExtractHost(hostPort string) (host string, err error)
```
`netExtractHost` wraps
net.SplitHostPort and returns the host
component (as a string).
##### 4.3.1.4.
netExtractIpnet
Function Signature
``` rouge
func netExtractIpnet(s string) (ipNet *net.IPNet, err error)
```
`netExtractIpnet` wraps
net.ParseCIDR and returns the
net.IPNet component.
##### 4.3.1.5.
netExtractPort
Function Signature
``` rouge
func netExtractPort(hostPort string) (port uint16, err error)
```
`netExtractPort` wraps
net.SplitHostPort and returns the port
component (as a uint16).
##### 4.3.1.6.
netIfaces
Function Signature
``` rouge
func netIfaces() (ifaces []net.Interface, err error)
```
`netIfaces` directly calls
net.Interfaces.
##### 4.3.1.7.
netIp4Mask
Function Signature
``` rouge
func netIp4Mask(a, b, c, d any) (mask net.IPMask, err error)
```
`netIp4Mask` wraps
net.IPv4Mask.
It is wrapped so that `a`, `b`, `c`, and `d` may be a string:
``` rouge
{{- $mask := netIp4Mask "198" "51" "100" "10" -}}
```
or integers/other numeric:
``` rouge
{{- $mask := netIp4Mask 198 51 100 10 -}}
```
or bytes:
``` rouge
{{- $mask := netIp4Mask 0xc6 0x33 0x64 0x0a -}}
```
or even a mix:
``` rouge
{{- $mask := netIp4Mask "198" 51 "100" 0x0a -}}
```
##### 4.3.1.8.
netJoinHostPort
Function Signature
``` rouge
func netJoinHostPort(host, port string) (out string)
```
`netJoinHostPort` directly calls
net.JoinHostPort.
##### 4.3.1.9.
netParseIP
Function Signature
``` rouge
func netParseIP(s string) (ip net.IP)
```
`netParseIP` directly calls
net.ParseIP.
#### 4.3.2.
net/netip
These template functions contain capabilities from
net/netip.
##### 4.3.2.1.
netipAddrPort
Function Signature
``` rouge
func netipAddrPort(ip netip.Addr, port uint16) (addrPort netip.AddrPort)
```
`netipAddrPort` directly calls
net/netip.AddrPortFrom.
##### 4.3.2.2.
netipParseAddr
Function Signature
``` rouge
func netipParseAddr(s string) (addr netip.Addr, err error)
```
`netipParseAddr` directly calls
net/netip.ParseAddr.
##### 4.3.2.3.
netipParseAddrPort
Function Signature
``` rouge
func netipParseAddrPort(s string) (addrPort netip.AddrPort, err error)
```
`netipParseAddrPort` directly calls
net/netip.ParseAddrPort.
##### 4.3.2.4.
netipParsePrefix
Function Signature
``` rouge
func netipParsePrefix(s string) (pfx netip.Prefix, err error)
```
`netipParsePrefix` directly calls
net/netip.ParsePrefix.
##### 4.3.2.5.
netipPrefix
Function Signature
``` rouge
func netipPrefix(ip netip.Addr, bits int) (pfx netip.Prefix)
```
`netipPrefix` directly calls
net/netip.PrefixFrom.
#### 4.3.3.
go4.org/netipx
These template functions contain capabilities from
go4.org/netipx.
##### 4.3.3.1.
netipxAddrIpNet
Function Signature
``` rouge
func netipxAddrIpNet(addr netip.Addr) (ipNet *net.IPNet)
```
`netipxAddrIpNet` directly calls
go4.org/netipx.AddrIPNet.
##### 4.3.3.2.
netipxCmpPfx
Function Signature
``` rouge
func netipxCmpPfx(a, b netip.Prefix) (cmp int)
```
`netipxCmpPfx` directly calls
go4.org/netipx.ComparePrefix.
##### 4.3.3.3.
netipxFromStdAddr
Function Signature
``` rouge
func netipxFromStdAddr(ip net.IP, port int, zone string) (addrPort netip.AddrPort, err error)
```
`netipxFromStdAddr` wraps
go4.org/netipx.FromStdAddr. Instead of
returning a boolean as the second value, it will instead be an error if
the wrapped boolean is false.
##### 4.3.3.4.
netipxFromIp
Function Signature
``` rouge
func netipxFromIp(ip net.IP) (addr netip.Addr, err error)
```
`netipxFromIp` wraps
go4.org/netipx.FromStdIP. Instead of
returning a boolean as the second value, it will instead be an error if
the wrapped boolean is false.
##### 4.3.3.5.
netipxFromIpNet
Function Signature
``` rouge
func netipxFromIpNet(ipNet *net.IPNet) (pfx netip.Prefix, err error)
```
`netipxFromIpNet` wraps
go4.org/netipx.FromStdIPNet. Instead of
returning a boolean as the second value, it will instead be an error if
the wrapped boolean is false.
##### 4.3.3.6.
netipxParseRange
Function Signature
``` rouge
func netipxParseRange(s string) (ipRange netipx.IPRange, err error)
```
`netipxRange` directly calls
go4.org/netipx.ParseIPRange.
##### 4.3.3.7.
netipxPfxAddr
Function Signature
``` rouge
func netipxPfxAddr(s string) (addr netip.Addr, err error)
```
`netipxPfxAddr` directly calls
go4.org/netipx.ParsePrefixOrAddr.
##### 4.3.3.8.
netipxPfxIpNet
Function Signature
``` rouge
func netipxPfxIpNet(pfx netip.Prefix) (ipNet *net.IPNet)
```
`netipxPfxIpNet` directly calls
go4.org/netipx.PrefixIPNet.
##### 4.3.3.9.
netipxPfxLast
Function Signature
``` rouge
func netipxPfxLast(pfx netip.Prefix) (addr netip.Addr)
```
`netipxPfxLast` directly calls
go4.org/netipx.PrefixLastIP.
##### 4.3.3.10.
netipxPfxRange
Function Signature
``` rouge
func netipxPfxRange(pfx netip.Prefix) (ipRange netipx.IPRange)
```
`netipxPfxRange` directly calls
go4.org/netipx.RangeOfPrefix.
##### 4.3.3.11.
netipxRange
Function Signature
``` rouge
func netipxRange(from, to netip.Addr) (ipRange netipx.IPRange)
```
`netipxRange` directly calls
go4.org/netipx.IPRangeFrom.
### 4.4. Numbers/Math
#### 4.4.1.
numFloat32Str
Function Signature
``` rouge
func numFloat32Str(f float32) (s string)
```
`numFloat32Str` returns a **complete** non-truncated non-right-padded
string representation of a `float32`.
#### 4.4.2.
numFloat64
Function Signature
``` rouge
func numFloat64(val any) (f float64, err error)
```
`numFloat64` returns any string representation of a numeric value or any
type of numeric value to a `float64`.
#### 4.4.3.
numFloat64Str
Function Signature
``` rouge
func numFloat64Str(f float64) (s string)
```
`numFloat64Str` returns a **complete** non-truncated non-right-padded
string representation of a `float64`.
#### 4.4.4.
numFloatStr
Function Signature
``` rouge
func numFloatStr(val any) (s string, err error)
```
`numFloatStr` wraps [`numFloat32Str`](#fn_num_f32s) and
[`numFloat64Str`](#fn_num_f64s).
`val` can be a string representation of any numeric value or any type of
numeric value.
### 4.5. Operating System
#### 4.5.1.
osFQDN
Function Signature
``` rouge
func osFQDN() (fqdn string, err error)
```
`osFQDN` currently just directly calls
os.Hostname.
As such, it comes with the same caveats — namely that it isn’t
guaranteed to be an FQDN, it will be precisely/exactly whatever the
kernel/OS hostname is set as.
In the future, it may be extended to support a more diligent effort to
determine an actual FQDN, and return an error if it is unable to be
derived.
To (relatively) predictably get the "short hostname", use
[`osHost`](#fn_os_hst). To directly/predictably use
os.Hostname, use
[`osHostname`](#fn_os_hstnm).
#### 4.5.2.
osGroupById
Function Signature
``` rouge
func osGroupById[T string | int](gid T) (g *user.Group, err error)
```
`osGroupById` returns an
os/user.Group from a given group ID/GID.
It more or less behaves exactly like
os/user.LookupGroupId, except it will
accept either a `string` **or** an `int` as the GID.
#### 4.5.3.
osGroupByName
Function Signature
``` rouge
func osGroupByName(grpNm string) (g *user.Group, err error)
```
`osGroupByName` returns an
os/user.Group from a given group name.
It behaves exactly like
os/user.LookupGroup.
#### 4.5.4.
osHost
Function Signature
``` rouge
func osHost() (out string, err error)
```
`osHost` returns the "short hostname" by calling
os.Hostname and returning the first
"host label" (as RFCs refer to it). This is commonly/colloquially called
the "hostname" or "hostname without the domain part".
e.g.:
``` rouge
{{- $fqdn := osFQDN -}}
{{- $h := osHost -}}
{{- $cmp := index ($fqdn | splitList ".") 0 -}}
osHost {{ $h }} should be equal to first label of FQDN {{ $cmp }}.
```
Tip
|
The |
To (try to) get the FQDN, use [`osFQDN`](#fn_os_fqdn). To directly use
os.Hostname, use
[`osHostname`](#fn_os_hstnm).
#### 4.5.5.
osHostname
Function Signature
``` rouge
func osHostname() (out string, err error)
```
`osHostname` directly calls
os.Hostname.
#### 4.5.6.
osIdState
Function Signature
``` rouge
func osIdState() (idst sysutils.IDState)
```
`osIdState` returns the current runtime process'
r00t2.io/sysutils.IDState.
It directly calls
r00t2.io/sysutils.GetIDState.
Warning
|
This is more or less useless on Windows; it returns only a dummy struct for cross-platform compatibility. |
#### 4.5.7.
osUser
Function Signature
``` rouge
func osUser() (u *user.User, err error)
```
`osUser` returns the current runtime process'
os/user.User.
It directly calls
os/user.Current.
#### 4.5.8.
osUserById
Function Signature
``` rouge
func osUserById[T string | int](uid T) (u *user.User, err error)
```
`osUserById` returns an
os/user.User from a given user ID/UID.
It more or less behaves exactly like
os/user.LookupId, except it will accept
either a `string` **or** an `int` as the UID.
#### 4.5.9.
osUserByName
Function Signature
``` rouge
func osUserByName(userNm string) (u *user.User, err error)
```
`osUserByName` returns an
os/user.User from a given username.
It directly calls
os/user.Lookup.
### 4.6. Paths
#### 4.6.1. Generic
These operate similar to
the
path stdlib library and use a fixed `/` path separator.
##### 4.6.1.1.
pathJoin
Function Signature
``` rouge
func pathJoin(elem ...string) (out string)
```
`pathJoin` directly calls
path.Join.
Warning
|
If you are joining paths in a pipeline, you almost assuredly want |
``` rouge
{{- pathJoin "a" "b" "c" }}
{{- pathJoin "/" "a" "b" "c" }}
{{- pathJoin "/a/b" "c" }}
```
renders as:
``` rouge
a/b/c
/a/b/c
/a/b/c
```
##### 4.6.1.2.
pathPipeJoin
Function Signature
``` rouge
func pathPipeJoin(elems ...string) (out string)
```
`pathPipeJoin` operates like [`pathJoin`](#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.
``` rouge
{{- $myBase := "/a" -}}
{{- pathPipeJoin "b" "c" "a" }}
{{- pathPipeJoin "a" "b" "c" "/" }}
{{- $myBase | pathPipeJoin "b" "c" }}
```
renders as:
``` rouge
a/b/c
/a/b/c
/a/b/c
```
##### 4.6.1.3.
pathSliceJoin
Function Signature
``` rouge
func pathSliceJoin(sl []string) (out string)
```
`pathSliceJoin` joins a slice of path segment strings (`[]string`)
instead of a variadic sequence of strings.
Tip
|
The |
``` rouge
{{- $myList := "a,b,c" | splitList "," -}}
{{- $myList | pathSliceJoin }}
{{- ("a,b,c" | splitList ",") | pathSliceJoin }}
{{- ("/,a,b,c" | splitList ",") | pathSliceJoin }}
```
renders as:
``` rouge
a/b/c
a/b/c
/a/b/c
```
##### 4.6.1.4.
pathSlicePipeJoin
Function Signature
``` rouge
func pathSlicePipeJoin(sl []string, root string) (out string)
```
`pathSlicePipeJoin` operates like [`pathPipeJoin`](#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
[`pathSliceJoin`](#fn_path_gnrc_psj) in that it then also accepts a
slice of path segments (`[]string`) to append to that base path.
Tip
|
The |
``` rouge
{{- $myBase := "/a" -}}
{{- $myList := "b,c,d" | splitList "." -}}
{{- pathSlicePipeJoin $myList $myBase }}
{{- $myBase | pathSlicePipeJoin $myList }}
```
renders as:
``` rouge
/a/b/c
/a/b/c
```
##### 4.6.1.5.
pathSubJoin
Function Signature
``` rouge
func pathSubJoin(root string, elems ...string) (out string)
```
`pathSubJoin` operates like [`pathJoin`](#fn_path_gnrc_pj) but it
expects an explicit root/base path.
The pipeline-friendly equivalent of this is
[`pathPipeJoin`](#fn_path_gnrc_ppj).
``` rouge
{{- pathSubJoin "/a/b" "c" }}
{{- pathSubJoin "/" "a" "b" "c" }}
{{- "c" | pathSubJoin "/" "a" "b" }}
```
renders as:
``` rouge
/a/b/c
/a/b/c
/a/b/c
```
#### 4.6.2. OS/Platform-Tailored
These operate similar to
the
path/filepath stdlib library, and
use the OS-specific
os.PathSeparator.
Warning
|
Take special note of the oddness around specifying Windows paths and
drive letters in e.g. It is recommended to make use of |
##### 4.6.2.1.
osPathJoin
Function Signature
``` rouge
func osPathJoin(elem ...string) (out string)
```
`osPathJoin` directly calls
path/filepath.Join.
Warning
|
If you are joining paths in a pipeline, you almost assuredly want |
``` rouge
{{- osPathJoin "a" "b" "c" }}
{{- osPathJoin "/" "a" "b" "c" }}
{{- osPathJoin "C:\\" "a" "b" "c" }}
{{- osPathJoin "C:" "a" "b" "c" }}
```
renders as:
| OS | Result |
|---|---|
Windows |
|
Others (e.g. Linux, macOS) |
|
##### 4.6.2.2.
osPathPipeJoin
Function Signature
``` rouge
func osPathPipeJoin(elems ...string) (out string)
```
`osPathPipeJoin` operates like [`pathPipeJoin`](#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 argument to the
next pipe function.
``` rouge
{{- $myBase := "/a" -}}
{{- osPathPipeJoin "b" "c" "a" }}
{{- osPathPipeJoin "a" "b" "c" "/" }}
{{- $myBase | osPathPipeJoin "b" "c" }}
```
renders as:
| OS | Result |
|---|---|
Windows |
|
Others (e.g. Linux, macOS) |
|
##### 4.6.2.3.
osPathSep
Function Signature
``` rouge
func osPathSep() (out string)
```
`osPathSep` returns the
os.PathSeparator for this OS.
``` rouge
{{- osPathSep }}
```
renders as:
| OS | Result |
|---|---|
Windows |
|
Others (e.g. Linux, macOS) |
|
##### 4.6.2.4.
osPathSliceJoin
Function Signature
``` rouge
func osPathSliceJoin(sl []string) (out string)
```
`osPathSliceJoin` operates like [`pathSliceJoin`](#fn_path_gnrc_psj) but
with OS-specific path separators.
Tip
|
The |
``` rouge
{{- $myList := "a,b,c" | splitList "," -}}
{{- $myList | osPathSliceJoin }}
{{- ("a,b,c" | splitList ",") | osPathSliceJoin }}
{{- ("/,a,b,c" | splitList ",") | osPathSliceJoin }}
```
renders as:
| OS | Result |
|---|---|
Windows |
|
Others (e.g. Linux, macOS) |
|
##### 4.6.2.5.
osPathSlicePipeJoin
Function Signature
``` rouge
func osPathSlicePipeJoin(sl []string, root string) (out string)
```
`osPathSlicePipeJoin` operates like
[`pathSlicePipeJoin`](#fn_path_gnrc_pspj) but with OS-specific
separators.
Tip
|
The |
``` rouge
{{- $myBase := "/a" -}}
{{- $myList := "b,c,d" | splitList "." -}}
{{- osPathSlicePipeJoin $myList $myBase }}
{{- $myBase | osPathSlicePipeJoin $myList }}
```
renders as:
| OS | Result |
|---|---|
Windows |
|
Others (e.g. Linux, macOS) |
|
##### 4.6.2.6.
osPathSubJoin
Function Signature
``` rouge
func osPathSubJoin(root string, elems ...string) (out string)
```
`osPathSubJoin` operates like [`pathSubJoin`](#fn_path_gnrc_psubj) but
with OS-specific separators.
The pipeline-friendly equivalent of this is
[`osPathPipeJoin`](#fn_path_os_ppj).
``` rouge
{{- osPathSubJoin "/a/b" "c" }}
{{- osPathSubJoin "/" "a" "b" "c" }}
{{- "c" | osPathSubJoin "/" "a" "b" }}
```
renders as:
| OS | Result |
|---|---|
Windows |
|
Others (e.g. Linux, macOS) |
|
### 4.7. PSUtil
These are functions from
github.com/shirou/gopsutil/v4 packages.
#### 4.7.1. CPU/Processor
##### 4.7.1.1.
psCpuCnts
Function Signature
``` rouge
func psCpuCnts(logical bool) (numCpu int, err error)
```
`psCpuCnts` directly calls
github.com/shirou/gopsutil/v4/cpu.Counts.
##### 4.7.1.2.
psCpuInfo
Function Signature
``` rouge
func psCpuInfo() (cpuInfo []cpu.Info, err error)
```
`psCpuInfo` directly calls
github.com/shirou/gopsutil/v4/cpu.Info.
##### 4.7.1.3.
psCpuPct
Function Signature
``` rouge
func psCpuPct(interval time.Duration, percpu bool) (pcts []float64, err error)
```
`psCpuPct` directly calls
github.com/shirou/gopsutil/v4/cpu.Percent.
##### 4.7.1.4.
psCpuTimes
Function Signature
``` rouge
func psCpuTimes(percpu bool) (cpuTimes []cpu.TimesStat, err error)
```
`psCpuTimes` directly calls
github.com/shirou/gopsutil/v4/cpu.Times.
#### 4.7.2. Disk
##### 4.7.2.1.
psDiskIoCnts
Function Signature
``` rouge
func psDiskIoCnts(names ...string) (stats map[string]disk.IOCountersStat, err error)
```
`psDiskIoCnts` directly calls
github.com/shirou/gopsutil/v4/disk.IOCounters.
##### 4.7.2.2.
psDiskLabel
Function Signature
``` rouge
func psDiskLabel(name string) (label string, err error)
```
`psDiskLabel` directly calls
github.com/shirou/gopsutil/v4/disk.Label.
##### 4.7.2.3.
psDiskParts
Function Signature
``` rouge
func psDiskParts(all bool) (parts []disk.PartitionStat, err error)
```
`psDiskParts` directly calls
github.com/shirou/gopsutil/v4/disk.Partitions.
##### 4.7.2.4.
psDiskSerial
Function Signature
``` rouge
func psDiskSerial(name string) (serial string, err error)
```
`psDiskSerial` directly calls
github.com/shirou/gopsutil/v4/disk.SerialNumber.
##### 4.7.2.5.
psDiskUsage
Function Signature
``` rouge
func psDiskUsage(path string) (usage *disk.UsageStat, err error)
```
`psDiskUsage` directly calls
github.com/shirou/gopsutil/v4/disk.Usage.
#### 4.7.3. Host
##### 4.7.3.1.
psHostBoot
Function Signature
``` rouge
func psHostBoot() (bootEpoch uint64, err error)
```
`psHostBoot` directly calls
github.com/shirou/gopsutil/v4/host.BootTime.
##### 4.7.3.2.
psHostId
Function Signature
``` rouge
func psHostId() (hostId string, err error)
```
`psHostId` directly calls
github.com/shirou/gopsutil/v4/host.HostID.
##### 4.7.3.3.
psHostInfo
Function Signature
``` rouge
func psHostInfo() (info *host.InfoStat, err error)
```
`psHostInfo` directly calls
github.com/shirou/gopsutil/v4/host.Info.
##### 4.7.3.4.
psHostKernArch
Function Signature
``` rouge
func psHostKernArch() (arch string, err error)
```
`psHostKernArch` directly calls
github.com/shirou/gopsutil/v4/host.KernelArch.
##### 4.7.3.5.
psHostKernVer
Function Signature
``` rouge
func psHostKernVer() (ver string, err error)
```
`psHostKernVer` directly calls
github.com/shirou/gopsutil/v4/host.KernelVersion.
##### 4.7.3.6.
psHostPlatInfo
Function Signature
``` rouge
func psHostPlatInfo() (platInfo [3]string, err error)
```
`psHostPlatInfo` wraps
github.com/shirou/gopsutil/v4/host.PlatformInformation.
It is necessary to wrap because the function normally returns
`(string, string, string, error)` but a template function may only
return either a single value (of any type) or a single value of any type
and an error, so the three `string` returns are consolidated into an
ordered `[3]string`.
##### 4.7.3.7.
psHostPlatUptime
Function Signature
``` rouge
func psHostPlatUptime() (uptimeSecs uint64, err error)
```
`psHostPlatUptime` directly calls
github.com/shirou/gopsutil/v4/host.Uptime.
##### 4.7.3.8.
psHostUsers
Function Signature
``` rouge
func psHostUsers() (users []host.UserStat, err error)
```
`psHostUsers` directly calls
github.com/shirou/gopsutil/v4/host.Users.
##### 4.7.3.9.
psHostPlatVirt
Function Signature
``` rouge
func psHostVirt() (virtInfo [2]string, err error)
```
`psHostPlatVirt` wraps
github.com/shirou/gopsutil/v4/host.Virtualization.
It is necessary to wrap because the function normally returns
`(string, string, error)` but a template function may only return either
a single value (of any type) or a single value of any type and an error,
so the two `string` returns are consolidated into an ordered
`[2]string`.
#### 4.7.4. Load
##### 4.7.4.1.
psLoadAvg
Function Signature
``` rouge
func psLoadAvg() (avg *load.AvgStat, err error)
```
`psLoadAvg` directly calls
github.com/shirou/gopsutil/v4/load.Avg.
##### 4.7.4.2.
psLoadMisc
Function Signature
``` rouge
func psLoadMisc() (misc *load.MiscStat, err error)
```
`psLoadMisc` directly calls
github.com/shirou/gopsutil/v4/load.Misc.
#### 4.7.5. Memory
##### 4.7.5.1.
psMemExVMem
Function Signature
``` rouge
func psMemExVMem() (exVMem *mem.ExVirtualMemory, err error)
```
Warning
|
This function is available on Windows and Linux platforms only. |
Warning
|
This function returns very different types depending on platform.
|
This function wraps
`github.com/shirou/gopsutil/v4/mem.NewExLinux`
.[`VirtualMemory`](https://pkg.go.dev/github.com/shirou/gopsutil/v4/mem?GOOS=linux#ExLinux.VirtualMemory)
on Linux and
`github.com/shirou/gopsutil/v4/mem.NewExWindows`
.[`VirtualMemory`](https://pkg.go.dev/github.com/shirou/gopsutil/v4/mem?GOOS=windows#ExWindows.VirtualMemory)
on Windows.
##### 4.7.5.2.
psMemSwap
Function Signature
``` rouge
func psMemSwap() (swap *mem.SwapMemoryStat, err error)
```
`psMemSwap` directly calls
github.com/shirou/gopsutil/v4/mem.SwapMemory.
##### 4.7.5.3.
psMemSwapDevs
Function Signature
``` rouge
func psMemSwapDevs() (swapDevs []*mem.SwapDevice, err error)
```
`psMemSwapDevs` directly calls
github.com/shirou/gopsutil/v4/mem.SwapDevices.
##### 4.7.5.4.
psMemVMem
Function Signature
``` rouge
func psMemVMem() (vmem *mem.VirtualMemoryStat, err error)
```
`psMemVMem` directly calls
github.com/shirou/gopsutil/v4/mem.VirtualMemory.
#### 4.7.6. Network
##### 4.7.6.1.
psNetConns
Function Signature
``` rouge
func psNetConns(kind string) (conns []net.ConnectionStat, err error)
```
`psNetConns` directly calls
github.com/shirou/gopsutil/v4/net.Connections.
##### 4.7.6.2.
psNetConnsMax
Function Signature
``` rouge
func psNetConnsMax(kind string, maxConn int) (conns []net.ConnectionStat, err error)
```
`psNetConnsMax` directly calls
github.com/shirou/gopsutil/v4/net.ConnectionsMax.
##### 4.7.6.3.
psNetConnsPid
Function Signature
``` rouge
func psNetConnsPid(kind string, pid int32) (conns []net.ConnectionStat, err error)
```
`psNetConnsPid` directly calls
github.com/shirou/gopsutil/v4/net.ConnectionsPid.
##### 4.7.6.4.
psNetConnsPidMax
Function Signature
``` rouge
func psNetConnsPidMax(kind string, pid int32, maxConn int) (conns []net.ConnectionStat, err error)
```
`psNetConnsPidMax` directly calls
github.com/shirou/gopsutil/v4/net.ConnectionsPidMax.
##### 4.7.6.5.
psNetCTStats
Function Signature
``` rouge
func psNetCTStats(percCpu bool) (ctStats []net.ConntrackStat, err error)
```
`psNetCTStats` directly calls
github.com/shirou/gopsutil/v4/net.ConntrackStats.
##### 4.7.6.6.
psNetCTStatList
Function Signature
``` rouge
func psNetCTStatList() (ctStats *net.ConntrackStatList, err error)
```
`psNetCTStatList` directly calls
github.com/shirou/gopsutil/v4/net.ConntrackStatList.
##### 4.7.6.7.
psNetFilterCnts
Function Signature
``` rouge
func psNetFilterCnts() (filterCnts []net.FilterStat, err error)
```
`psNetFilterCnts` directly calls
github.com/shirou/gopsutil/v4/net.FilterCounters.
##### 4.7.6.8.
psNetIoCnts
Function Signature
``` rouge
func psNetIoCnts(perNIC bool) (ioCnts []net.IOCountersStat, err error)
```
`psNetIoCnts` directly calls
github.com/shirou/gopsutil/v4/net.IOCounters.
##### 4.7.6.9.
psNetIoCntsFile
Function Signature
``` rouge
func psNetIoCntsFile(perNIC bool, filepath string) (ioCnts []net.IOCountersStat, err error)
```
`psNetIoCntsFile` directly calls
github.com/shirou/gopsutil/v4/net.IOCountersByFile.
##### 4.7.6.10.
psNetIfaces
Function Signature
``` rouge
func psNetIfaces() (ioCnts []net.InterfaceStatList, err error)
```
`psNetIfaces` directly calls
github.com/shirou/gopsutil/v4/net.Interfaces.
##### 4.7.6.11.
psNetPids
Function Signature
``` rouge
func psNetPids() (pids []int32, err error)
```
`psNetPids` directly calls
github.com/shirou/gopsutil/v4/net.Pids.
##### 4.7.6.12.
psNetProtoCnt
Function Signature
``` rouge
func psNetProtoCnt(protos []string) (protoCnts []net.ProtoCountersStat, err error)
```
Warning
|
This only works properly on Linux currently per upstream. |
`psNetProtoCnt` directly calls
github.com/shirou/gopsutil/v4/net.ProtoCounters.
##### 4.7.6.13.
psNetRev
Function Signature
``` rouge
func psNetRev(b []byte) (out []byte)
```
Warning
|
This function only exists on Linux. |
`psNetRev` directly calls
github.com/shirou/gopsutil/v4/net.Reverse.
#### 4.7.7. Processes
##### 4.7.7.1.
psProcs
Function Signature
``` rouge
func psProcs(pid int32) (procs []*process.Process, err error)
```
`psProcs` directly calls
github.com/shirou/gopsutil/v4/proc.Processes.
##### 4.7.7.2.
psProcNew
Function Signature
``` rouge
func psProcNew(pid int32) (proc *process.Process, err error)
```
`psProcNew` directly calls
github.com/shirou/gopsutil/v4/proc.NewProcess.
##### 4.7.7.3.
psProcPids
Function Signature
``` rouge
func psProcPids() (pids []int32, err error)
```
`psProcPids` directly calls
github.com/shirou/gopsutil/v4/proc.Pids.
##### 4.7.7.4.
psProcPidExists
Function Signature
``` rouge
func psProcPidExists(pid int32) (exists bool, err error)
```
`psProcPidExists` directly calls
github.com/shirou/gopsutil/v4/proc.PidExists.
#### 4.7.8. Sensors/Thermals
##### 4.7.8.1.
psSensorExTemp
Function Signature
``` rouge
func psSensorExTemp() (temps []sensors.ExTemperature, err error)
```
Warning
|
This function only exists on Linux. |
`psSensorExTemp` wraps
`github.com/shirou/gopsutil/v4/sensors.NewExLinux`
.[`github.com/shirou/gopsutil/v4/sensors.TemperatureWithContext`](https://pkg.go.dev/github.com/shirou/gopsutil/v4/sensors?GOOS=linux#TemperatureWithContext).
##### 4.7.8.2.
psSensorTemps
Function Signature
``` rouge
func psSensorTemps() (temps []sensors.TemperatureStat, err error)
```
`psSensorTemps` directly calls
github.com/shirou/gopsutil/v4/sensors.SensorsTemperatures.
#### 4.7.9. Windows Services
Warning
|
All of these functions are only available on Windows. |
##### 4.7.9.1.
psWinsvcList
Function Signature
``` rouge
func psWinsvcList() (svcs []winservices.Service, err error)
```
Warning
|
This function is only available on Windows. |
`psWinsvcList` directly calls
github.com/shirou/gopsutil/v4/winservices.ListServices.
##### 4.7.9.2.
psWinsvcNew
Function Signature
``` rouge
func psWinsvcNew(svcName string) (svc *winservices.Service, err error)
```
Warning
|
This function is only available on Windows. |
`psWinsvcNew` directly calls
github.com/shirou/gopsutil/v4/winservices.NewService.
### 4.8. Strings
#### 4.8.1.
extIndent
Function Signature
``` rouge
func extIndent(
levels int,
skipFirst, skipEmpty, skipWhitespace bool,
indentString, input string,
) (out string)
```
`extIndent` allows for a MUCH more flexible indenter than the `sprig`
`indent` function.
It works with both Windows (`\r\n`) and POSIX (`\n`) linebreaks.
Tip
|
If |
It has quite a few arguments, however:
| Argument | Type | Description |
|---|---|---|
|
|
The level of indentation for the text. If less than or equal to
|
|
|
If true, skip indenting the first line. This is particularly handy if you like to visually align your function calls in your templates. |
|
|
If true, do not add an indent to empty lines (where an "empty line" means "only has a linebreak"). |
|
|
If true, do not add an indent to lines that only consist of whitespace (spaces, tabs, etc.) and a linebreak. |
|
|
The string to use as the "indent character". This can be any string,
such as |
|
|
The text to be indented. Because it is the last argument,
|
### 4.9. System/Platform/Architecture
#### 4.9.1.
sysArch
Function Signature
``` rouge
func sysArch() (out string)
```
Returns the
runtime.GOARCH constant.
#### 4.9.2.
sysNumCpu
Function Signature
``` rouge
func sysNumCpu() (cnt int)
```
`sysNumCpu` directly calls
runtime.NumCPU.
#### 4.9.3.
sysOsName
Function Signature
``` rouge
func sysOsNm() (out string)
```
Returns the
runtime.GOOS constant.
#### 4.9.4.
| Key | Value Type |
|----|----|
| `compiler` | string |
| `arch` | string |
| `os` | string |
| `maxprocs` | int \[1\] |
| `cpu_cnt` | int |
| `num_cgo` | int |
| `num_go` | int |
| `go_ver` | string |
Table 1. `sysRuntime` Values
sysRuntime
Function Signature
``` rouge
func sysRuntime() (out map[string]string)
```
This function returns a `map[string]string` of various information from
the
runtime stdlib library.
Specifically, the following are returned.
Tip
|
The value type is a direct link to the Because all values are mapped as strings, they can be converted back to their native type via e.g. the Sprig conversion functions if necessary. |
As a convenience, some of these values also have their own dedicated
functions as well:
- [`sysArch`](#fn_sys_arch)
- [`sysNumCpu`](#fn_sys_numcpu)
- [`sysOsName`](#fn_sys_os)
### 4.10. Time/Dates/Timestamps
Note
|
Some of these functions duplicate Sprig functionality, but are included here for predictable API. Care has been taken to name these functions differently from the Sprig functions where possible and sensible. |
#### 4.10.1.
tmDate
Function Signature
``` rouge
func tmDate(year int, month time.Month, day, hour, min, sec, nsec int, loc *time.Location) (date time.Time)
```
`tmDate` directly calls
time.Date.
#### 4.10.2.
tmFloatMicro
Function Signature
``` rouge
func tmFloatMicro(t time.Time) (f64 float64)
```
`tmFloatMicro` directly calls
(r00t2.io/goutils/timex).F64Microseconds.
#### 4.10.3.
tmFloatMilli
Function Signature
``` rouge
func tmFloatMilli(t time.Time) (f64 float64)
```
`tmFloatMilli` directly calls
(r00t2.io/goutils/timex).F64Milliseconds.
#### 4.10.4.
tmFloatNano
Function Signature
``` rouge
func tmFloatNano(t time.Time) (f64 float64)
```
`tmFloatNano` directly calls
(r00t2.io/goutils/timex).F64Nanoseconds.
#### 4.10.5.
tmFloat
Function Signature
``` rouge
func tmFloat(t time.Time) (f64 float64)
```
`tmFloat` directly calls
(r00t2.io/goutils/timex).F64Seconds.
#### 4.10.6.
tmFmt
Function Signature
``` rouge
func tmFmt(fstr string, t time.Time) (out string)
```
`tmFormat` provides a more pipeline-friendly alternative to calling e.g.
``` rouge
{{- $t := tmNow -}}
{{ $t.Format "" }}
```
#### 4.10.7.
tmNow
Function Signature
``` rouge
func tmNow() (now time.Time)
```
`tmNow` directly calls
time.Now.
#### 4.10.8.
tmParseDur8n
Function Signature
``` rouge
func tmParseDur8n(s string) (d time.Duration, err error)
```
`tmParseDur8n` directly calls
time.ParseDuration.
#### 4.10.9.
tmParseMonth
Function Signature
``` rouge
func tmParseMonth(v any) (mon time.Month, err error)
```
`tmParseMonth` attempts to first try [`tmParseMonthInt`](#fn_tm_pmnthi)
and then tries [`tmParseMonthStr`](#fn_tm_pmnths) if `v` is not
"numeric".
#### 4.10.10.
tmParseMonthInt
Function Signature
``` rouge
func tmParseMonthInt(n any) (mon time.Month, err error)
```
`tmParseMonthInt` parses a number representation of month `n` to a
time.Month. `n` may be any numeric type
or a string representation of a number (or a custom type derived from
those).
A negative integer (or float, etc.) will be converted to a positive one
(e.g. `-6` → `6` → `time.June`).
Floats are rounded to the nearest integer.
The integer should map directly to the
time.Month constants in the `time`
module:
- `1`: `time.January`
- `2`: `time.February`
- `3`: `time.March`
- `4`: `time.April`
- `5`: `time.May`
- `6`: `time.June`
- `7`: `time.July`
- `8`: `time.August`
- `9`: `time.September`
- `10`: `time.October`
- `11`: `time.November`
- `12`: `time.December`
If `n` resolves to `0`, `mon` will be the current month (as determined
by
time.Now).
If `n` resolves to \> `12`, `err` will be `sprigx.ErrBadMonth` (though
be sure to use
errors.Is; it will be wrapped by
[`(text/template).ExecError`](https://pkg.go.dev/text/template#ExecError)/[`(html/template).ExecError`](https://pkg.go.dev/html/template#ExecError).
#### 4.10.11.
tmParseMonthStr
Function Signature
``` rouge
func tmParseMonthStr(s string) (mon time.Month, err error)
```
`tmParseMonthStr` parses a string representation `s` of a month to a
time.Month.
It normalizes `s` to lowercase and only uses the first 3 characters (the
minimum length needed to determine month name uniqueness - "June" vs.
"July", "March" vs. "May").
An empty (or whitespace-only) string will use the current month (as
determined by
time.Now).
#### 4.10.12.
tmParseTime
Function Signature
``` rouge
func tmParseTime(layout, value string) (t time.Time, err error)
```
`tmParseTime` directly calls
time.Parse.
Be sure that `layout` is a properly parseable
layout format.