## 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. Anchor-links (links within this document to other sections of this document) will likely also not work. Be sure to view it at properly via the in-repo AsciiDoc rendering or by downloading and viewing the HTML version in a browser locally and/or rendering a PDF version. |
## 2. How do I Render These Docs?
This documentation is written in AsciiDoc (with AsciiDoctor extensions).
To re-render all docs (including [PDF](#rndr_pdf)):
``` rouge
git clone https://git.r00t2.io/r00t2/go_goutils.git
cd go_goutils
.githooks/pre-commit/01-docgen
```
### 2.1. HTML
HTML output is re-rendered and included in git on each commit automatically (via
github:gabyx/Githooks) but can be re-rendered on-demand locally via:
``` rouge
git clone https://git.r00t2.io/r00t2/go_goutils.git
cd go_goutils
export orig_dir="$(pwd)"
cd tplx/sprigx
asciidoctor -a ROOTDIR="${orig_dir}/" -o README.html README.adoc
```
### 2.2. PDF
This documentation can be rendered to PDF via
asciidoctor-pdf. It is not included in git automatically because binary files that change on each commit is not a good idea for git, especially for a repo that gets cloned as part of a library inclusion in a module/package dependency system (like `gomod`).
To render as PDF:
``` rouge
git clone https://git.r00t2.io/r00t2/go_goutils.git
cd go_goutils
export orig_dir="$(pwd)"
cd tplx/sprigx
asciidoctor-pdf -a ROOTDIR="${orig_dir}/" -o README.pdf README.adoc
```
## 3. How do I Use SprigX?
whereas this will use `foo` from `sprig`
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`
``` 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())
)
```
``` 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,
like this.
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"],
},
),
)
)
```
## 4. Library Functions
These are generally intended to be used **outside** the template in the actual Go code.
### 4.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.
### 4.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.
### 4.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.
### 4.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.
### 4.5.
HtmlFuncMap
Function Signature
``` rouge
func HtmlFuncMap() (fmap template.FuncMap)
```
This function returns a SprigX
html/template.FuncMap.
### 4.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.
### 4.7.
TxtFuncMap
Function Signature
``` rouge
func TxtFuncMap() (fmap template.FuncMap)
```
This function returns a SprigX
text/template.FuncMap.
## 5. 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.
### 5.1. Debugging
#### 5.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.
### 5.2. "Meta"/Template Helpers
#### 5.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.
[id="fn_net_all"]
=== Networking
These template functions use capabilities from:
- [`net`](#fn_net)
- [`net/netip`](#fn_netip)
- [`go4.org/netipx`](#fn_netipx)
- [`r00t2.io/goutils/netx`](#fn_netx)
- [`r00t2.io/goutils/netx/dnsx`](#fn_dnsx)
The function prefix is used to indicate which module/package a function is added from.
#### 5.2.2.
net
These template functions contain capabilities from
net.
##### 5.2.2.1.
netCidrMask
Function Signature
``` rouge
func netCidrMask(ones, bits int) (mask net.IPMask)
```
`netCidrMask` directly calls
net.CIDRMask.
##### 5.2.2.2.
netExtractAddr
Function Signature
``` rouge
func netExtractAddr(s string) (addr net.IP, err error)
```
`netExtractAddr` wraps
net.ParseCIDR and returns the net.IP component.
##### 5.2.2.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).
##### 5.2.2.4.
netExtractIpnet
Function Signature
``` rouge
func netExtractIpnet(s string) (ipNet *net.IPNet, err error)
```
`netExtractIpnet` wraps
net.ParseCIDR and returns the net.IPNet component.
##### 5.2.2.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).
##### 5.2.2.6.
netIfaces
Function Signature
``` rouge
func netIfaces() (ifaces []net.Interface, err error)
```
`netIfaces` directly calls
net.Interfaces.
##### 5.2.2.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 -}}
```
##### 5.2.2.8.
netJoinHostPort
Function Signature
``` rouge
func netJoinHostPort(host, port string) (out string)
```
`netJoinHostPort` directly calls
net.JoinHostPort.
##### 5.2.2.9.
netParseIP
Function Signature
``` rouge
func netParseIP(s string) (ip net.IP)
```
`netParseIP` directly calls
net.ParseIP.
#### 5.2.3.
net/netip
These template functions contain capabilities from
net/netip.
##### 5.2.3.1.
netipAddrPort
Function Signature
``` rouge
func netipAddrPort(ip netip.Addr, port uint16) (addrPort netip.AddrPort)
```
`netipAddrPort` directly calls
net/netip.AddrPortFrom.
##### 5.2.3.2.
netipParseAddr
Function Signature
``` rouge
func netipParseAddr(s string) (addr netip.Addr, err error)
```
`netipParseAddr` directly calls
net/netip.ParseAddr.
##### 5.2.3.3.
netipParseAddrPort
Function Signature
``` rouge
func netipParseAddrPort(s string) (addrPort netip.AddrPort, err error)
```
`netipParseAddrPort` directly calls
net/netip.ParseAddrPort.
##### 5.2.3.4.
netipParsePrefix
Function Signature
``` rouge
func netipParsePrefix(s string) (pfx netip.Prefix, err error)
```
`netipParsePrefix` directly calls
net/netip.ParsePrefix.
##### 5.2.3.5.
netipPrefix
Function Signature
``` rouge
func netipPrefix(ip netip.Addr, bits int) (pfx netip.Prefix)
```
`netipPrefix` directly calls
net/netip.PrefixFrom.
#### 5.2.4.
go4.org/netipx
These template functions contain capabilities from
go4.org/netipx.
##### 5.2.4.1.
netipxAddrIpNet
Function Signature
``` rouge
func netipxAddrIpNet(addr netip.Addr) (ipNet *net.IPNet)
```
`netipxAddrIpNet` directly calls
go4.org/netipx.AddrIPNet.
##### 5.2.4.2.
netipxCmpPfx
Function Signature
``` rouge
func netipxCmpPfx(a, b netip.Prefix) (cmp int)
```
`netipxCmpPfx` directly calls
go4.org/netipx.ComparePrefix.
##### 5.2.4.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.
##### 5.2.4.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.
##### 5.2.4.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.
##### 5.2.4.6.
netipxParseRange
Function Signature
``` rouge
func netipxParseRange(s string) (ipRange netipx.IPRange, err error)
```
`netipxParseRange` directly calls
go4.org/netipx.ParseIPRange.
##### 5.2.4.7.
netipxPfxAddr
Function Signature
``` rouge
func netipxPfxAddr(s string) (addr netip.Addr, err error)
```
`netipxPfxAddr` directly calls
go4.org/netipx.ParsePrefixOrAddr.
##### 5.2.4.8.
netipxPfxIpNet
Function Signature
``` rouge
func netipxPfxIpNet(pfx netip.Prefix) (ipNet *net.IPNet)
```
`netipxPfxIpNet` directly calls
go4.org/netipx.PrefixIPNet.
##### 5.2.4.9.
netipxPfxLast
Function Signature
``` rouge
func netipxPfxLast(pfx netip.Prefix) (addr netip.Addr)
```
`netipxPfxLast` directly calls
go4.org/netipx.PrefixLastIP.
##### 5.2.4.10.
netipxPfxRange
Function Signature
``` rouge
func netipxPfxRange(pfx netip.Prefix) (ipRange netipx.IPRange)
```
`netipxPfxRange` directly calls
go4.org/netipx.RangeOfPrefix.
##### 5.2.4.11.
netipxRange
Function Signature
``` rouge
func netipxRange(from, to netip.Addr) (ipRange netipx.IPRange)
```
`netipxRange` directly calls
go4.org/netipx.IPRangeFrom.
#### 5.2.5.
r00t2.io/goutils/netx
These template functions contain capabilities from
r00t2.io/goutils/netx.
##### 5.2.5.1.
netxAddrRfc
Function Signature
``` rouge
func netxAddrRfc(addr netip.Addr) (rfcStr string)
```
`netxAddrRfc` directly calls
r00t2.io/goutils/netx.AddrRfc.
##### 5.2.5.2.
netxAddrRfc
Function Signature
``` rouge
func netxAddrRfc(cidr uint8) (ipMask net.IPMask, err error)
```
`netxCidr4IpMask` directly calls
r00t2.io/goutils/netx.Cidr4ToIPMask.
##### 5.2.5.3.
netxCidr4Mask
Function Signature
``` rouge
func netxCidr4Mask(cidr uint8) (mask uint32, err error)
```
`netxCidr4IpMask` directly calls
r00t2.io/goutils/netx.Cidr4ToMask.
##### 5.2.5.4.
netxCidr4Str
Function Signature
``` rouge
func netxCidr4Str(cidr uint8) (maskStr string, err error)
```
`netxCidr4Str` directly calls
r00t2.io/goutils/netx.Cidr4ToStr.
##### 5.2.5.5.
netxFamilyVer
Function Signature
``` rouge
func netxFamilyVer(family uint16) (ipVer int)
```
`netxFamilyVer` directly calls
r00t2.io/goutils/netx.FamilyToVer.
##### 5.2.5.6.
netxGetAddrFam
Function Signature
``` rouge
func netxGetAddrFam(addr netip.Addr) (family uint16)
```
`netxGetAddrFam` directly calls
r00t2.io/goutils/netx.GetAddrFamily.
##### 5.2.5.7.
netxGetIpFam
Function Signature
``` rouge
func netxGetIpFam(ip net.IP) (family uint16)
```
`netxGetIpFam` directly calls
r00t2.io/goutils/netx.GetIpFamily.
##### 5.2.5.8.
netxIpRfc
Function Signature
``` rouge
func netxIpRfc(ip net.IP) (rfcStr string)
```
`netxIpRfc` directly calls
r00t2.io/goutils/netx.IpRfc.
##### 5.2.5.9.
netxIpRfcStr
Function Signature
``` rouge
func netxIpRfcStr(s string) (rfcStr string)
```
`netxIpRfcStr` directly calls
r00t2.io/goutils/netx.IpRfcStr.
##### 5.2.5.10.
netxIpStripRfc
Function Signature
``` rouge
func netxIpStripRfc(s string) (stripStr string)
```
`netxIpStripRfc` directly calls
r00t2.io/goutils/netx.IpStripRfcStr.
##### 5.2.5.11.
netxIp4MaskCidr
Function Signature
``` rouge
func netxIp4MaskCidr(ipMask net.IPMask) (cidr uint8, err error)
```
`netxIp4MaskCidr` directly calls
r00t2.io/goutils/netx.IPMask4ToCidr.
##### 5.2.5.12.
netxIp4MaskMask
Function Signature
``` rouge
func netxIp4MaskMask(ipMask net.IPMask) (mask uint32, err error)
```
`netxIp4MaskMask` directly calls
r00t2.io/goutils/netx.IPMask4ToMask.
##### 5.2.5.13.
netxIp4MaskStr
Function Signature
``` rouge
func netxIp4MaskStr(ipMask net.IPMask) (maskStr string, err error)
```
`netxIp4MaskStr` directly calls
r00t2.io/goutils/netx.IPMask4ToStr.
##### 5.2.5.14.
netxIpVerStr
Function Signature
``` rouge
func netxIpVerStr(s string) (ipVer int)
```
`netxIpVerStr` directly calls
r00t2.io/goutils/netx.IpVerStr.
##### 5.2.5.15.
netxIsBrktd6
Function Signature
``` rouge
func netxIsBrktd6(s string) (isBrktdIp bool)
```
`netxIsBrktd6` directly calls
r00t2.io/goutils/netx.IsBracketedIp6.
##### 5.2.5.16.
netxIsIp
Function Signature
``` rouge
func netxIsIp(s string) (isIp bool)
```
`netxIsIp` directly calls
r00t2.io/goutils/netx.IsIpAddr.
##### 5.2.5.17.
netxIsPfx
Function Signature
``` rouge
func netxIsPfx(s string) (isNet bool)
```
`netxIsPfx` directly calls
r00t2.io/goutils/netx.IsPrefixNet.
##### 5.2.5.18.
netxMask4Cidr
Function Signature
``` rouge
func netxMask4Cidr(mask uint32) (cidr uint8, err error)
```
`netxMask4Cidr` directly calls
r00t2.io/goutils/netx.Mask4ToCidr.
##### 5.2.5.19.
netxMask4StrCidr
Function Signature
``` rouge
func netxMask4StrCidr(maskStr string) (cidr uint8, err error)
```
`netxMask4StrCidr` directly calls
r00t2.io/goutils/netx.Mask4StrToCidr.
##### 5.2.5.20.
netxMask4StrIpMask
Function Signature
``` rouge
func netxMask4StrIpMask(maskStr string) (mask net.IPMask, err error)
```
`netxMask4StrIpMask` directly calls
r00t2.io/goutils/netx.Mask4StrToIPMask.
##### 5.2.5.21.
netxMask4StrMask
Function Signature
``` rouge
func netxMask4StrMask(maskStr string) (mask uint32, err error)
```
`netxMask4StrMask` directly calls
r00t2.io/goutils/netx.Mask4StrToMask.
##### 5.2.5.22.
netxVerFamily
Function Signature
``` rouge
func netxVerFamily(ipVer int) (family uint16)
```
`netxVerFamily` directly calls
r00t2.io/goutils/netx.VerToFamily.
#### 5.2.6.
r00t2.io/goutils/netx/dnsx
These template functions contain capabilities from
r00t2.io/goutils/tplx/sprigx/netx/dnsx.
##### 5.2.6.1.
dnsxPtrAddr
Function Signature
``` rouge
func dnsxPtrAddr(s string) (ip netip.Addr, err error)
```
`dnsxPtrAddr` directly calls
r00t2.io/goutils/tplx/sprigx/netx/dnsx.AddrFromPtr.
##### 5.2.6.2.
dnsxAddrPtr
Function Signature
``` rouge
func dnsxAddrPtr(ip netip.Addr) (s string)
```
`dnsxAddrPtr` directly calls
r00t2.io/goutils/tplx/sprigx/netx/dnsx.AddrToPtr.
##### 5.2.6.3.
dnsxStrWire
Function Signature
``` rouge
func dnsxStrWire(recordNm string) (recordNmBytes []byte, err error)
```
`dnsxStrWire` directly calls
r00t2.io/goutils/tplx/sprigx/netx/dnsx.DnsStrToWire.
##### 5.2.6.4.
dnsxWireStr
Function Signature
``` rouge
func dnsxWireStr(recordNmBytes []byte) (recordNm string, err error)
```
`dnsxWireStr` directly calls
r00t2.io/goutils/tplx/sprigx/netx/dnsx.DnsWireToStr.
##### 5.2.6.5.
dnsxPtrIp
Function Signature
``` rouge
func dnsxPtrIp(s string) (ip net.IP, err error)
```
`dnsxPtrIp` directly calls
r00t2.io/goutils/tplx/sprigx/netx/dnsx.IpFromPtr.
##### 5.2.6.6.
dnsxIpPtr
Function Signature
``` rouge
func dnsxIpPtr(ip net.IP) (s string)
```
`dnsxIpPtr` directly calls
r00t2.io/goutils/tplx/sprigx/netx/dnsx.IpToPtr.
##### 5.2.6.7.
dnsxIsFqdn
Function Signature
``` rouge
func dnsxIsFqdn(s string) (fqdn bool)
```
`dnsxIsFqdn` directly calls
r00t2.io/goutils/tplx/sprigx/netx/dnsx.IsFqdn.
##### 5.2.6.8.
dnsxIsTxt
Function Signature
``` rouge
func dnsxIsTxt(fqdn string) (isOk bool)
```
`dnsxIsTxt` directly calls
r00t2.io/goutils/tplx/sprigx/netx/dnsx.IsFqdnDefinedTxt.
##### 5.2.6.9.
dnsxIsNsec3
Function Signature
``` rouge
func dnsxIsNsec3(s string) (maybeNsec3 bool)
```
`dnsxIsNsec3` directly calls
r00t2.io/goutils/tplx/sprigx/netx/dnsx.IsFqdnNsec3.
##### 5.2.6.10.
dnsxIsSrv
Function Signature
``` rouge
func dnsxIsSrv(s string) (srv bool)
```
`dnsxIsSrv` directly calls
r00t2.io/goutils/tplx/sprigx/netx/dnsx.IsFqdnSrv.
##### 5.2.6.11.
dnsxIsWild
Function Signature
``` rouge
func dnsxIsWild(s string) (wildcard bool)
```
`dnsxIsWild` directly calls
r00t2.io/goutils/tplx/sprigx/netx/dnsx.IsFqdnWildcard.
##### 5.2.6.12.
dnsxIsLbl
Function Signature
``` rouge
func dnsxIsLbl(s string) (isLbl bool)
```
`dnsxIsLbl` directly calls
r00t2.io/goutils/tplx/sprigx/netx/dnsx.IsLabel.
##### 5.2.6.13.
dnsxIsPtr
Function Signature
``` rouge
func dnsxIsPtr(s string) (isPtr bool, addr net.IP)
```
`dnsxIsPtr` directly calls
r00t2.io/goutils/tplx/sprigx/netx/dnsx.IsPtr.
### 5.3. Numbers/Math
#### 5.3.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`.
#### 5.3.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`.
#### 5.3.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`.
#### 5.3.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.
### 5.4. Operating System
#### 5.4.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).
#### 5.4.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.
#### 5.4.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.
#### 5.4.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).
#### 5.4.5.
osHostname
Function Signature
``` rouge
func osHostname() (out string, err error)
```
`osHostname` directly calls
os.Hostname.
#### 5.4.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. |
#### 5.4.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.
#### 5.4.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.
#### 5.4.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.
### 5.5. Paths
#### 5.5.1. Generic
These operate similar to the
path stdlib library and use a fixed `/` path separator.
##### 5.5.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
```
##### 5.5.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
```
##### 5.5.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
```
##### 5.5.1.4.
pathSlicePipeJoin
Function Signature
``` rouge
func pathSlicePipeJoin(sl []string, root string) (out string)
```
`pathSlicePipeJoin` operates like a hybrid of [`pathPipeJoin`](#fn_path_gnrc_ppj) and [`pathSliceJoin`](#fn_path_gnrc_psj):
- Like [`pathPipeJoin`](#fn_path_gnrc_ppj), it is suitable for pipeline use — the root/base path is passed in from the pipeline
- Like [`pathSliceJoin`](#fn_path_gnrc_psj), it **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
```
##### 5.5.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
```
#### 5.5.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 |
##### 5.5.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) |
|
##### 5.5.2.2.
osPathPipeJoin
Function Signature
``` rouge
func osPathJoin(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) |
|
##### 5.5.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) |
|
##### 5.5.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) |
|
##### 5.5.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) |
|
##### 5.5.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) |
|
### 5.6. PSUtil
These are functions from
github.com/shirou/gopsutil/v4 packages.
#### 5.6.1. CPU/Processor
##### 5.6.1.1.
psCpuCnts
Function Signature
``` rouge
func psCpuCnts(logical bool) (numCpu int, err error)
```
`psCpuCnts` directly calls
github.com/shirou/gopsutil/v4/cpu.Counts.
##### 5.6.1.2.
psCpuInfo
Function Signature
``` rouge
func psCpuInfo() (cpuInfo []cpu.Info, err error)
```
`psCpuInfo` directly calls
github.com/shirou/gopsutil/v4/cpu.Info.
##### 5.6.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.
##### 5.6.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.
#### 5.6.2. Disk
##### 5.6.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.
##### 5.6.2.2.
psDiskLabel
Function Signature
``` rouge
func psDiskLabel(name string) (label string, err error)
```
`psDiskLabel` directly calls
github.com/shirou/gopsutil/v4/disk.Label.
##### 5.6.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.
##### 5.6.2.4.
psDiskSerial
Function Signature
``` rouge
func psDiskSerial(name string) (serial string, err error)
```
`psDiskSerial` directly calls
github.com/shirou/gopsutil/v4/disk.SerialNumber.
##### 5.6.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.
#### 5.6.3. Host
##### 5.6.3.1.
psHostBoot
Function Signature
``` rouge
func psHostBoot() (bootEpoch uint64, err error)
```
`psHostBoot` directly calls
github.com/shirou/gopsutil/v4/host.BootTime.
##### 5.6.3.2.
psHostId
Function Signature
``` rouge
func psHostId() (hostId string, err error)
```
`psHostId` directly calls
github.com/shirou/gopsutil/v4/host.HostID.
##### 5.6.3.3.
psHostInfo
Function Signature
``` rouge
func psHostInfo() (info *host.InfoStat, err error)
```
`psHostInfo` directly calls
github.com/shirou/gopsutil/v4/host.Info.
##### 5.6.3.4.
psHostKernArch
Function Signature
``` rouge
func psHostKernArch() (arch string, err error)
```
`psHostKernArch` directly calls
github.com/shirou/gopsutil/v4/host.KernelArch.
##### 5.6.3.5.
psHostKernVer
Function Signature
``` rouge
func psHostKernVer() (ver string, err error)
```
`psHostKernVer` directly calls
github.com/shirou/gopsutil/v4/host.KernelVersion.
##### 5.6.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`.
##### 5.6.3.7.
psHostPlatUptime
Function Signature
``` rouge
func psHostPlatUptime() (uptimeSecs uint64, err error)
```
`psHostPlatUptime` directly calls
github.com/shirou/gopsutil/v4/host.Uptime.
##### 5.6.3.8.
psHostUsers
Function Signature
``` rouge
func psHostUsers() (users []host.UserStat, err error)
```
`psHostUsers` directly calls
github.com/shirou/gopsutil/v4/host.Users.
##### 5.6.3.9.
psHostPlatVirt
Function Signature
``` rouge
func psHostPlatVirt() (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`.
#### 5.6.4. Load
##### 5.6.4.1.
psLoadAvg
Function Signature
``` rouge
func psLoadAvg() (avg *load.AvgStat, err error)
```
`psLoadAvg` directly calls
github.com/shirou/gopsutil/v4/load.Avg.
##### 5.6.4.2.
psLoadMisc
Function Signature
``` rouge
func psLoadMisc() (misc *load.MiscStat, err error)
```
`psLoadMisc` directly calls
github.com/shirou/gopsutil/v4/load.Misc.
#### 5.6.5. Memory
##### 5.6.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.
##### 5.6.5.2.
psMemSwap
Function Signature
``` rouge
func psMemSwap() (swap *mem.SwapMemoryStat, err error)
```
`psMemSwap` directly calls
github.com/shirou/gopsutil/v4/mem.SwapMemory.
##### 5.6.5.3.
psMemSwapDevs
Function Signature
``` rouge
func psMemSwapDevs() (swapDevs []*mem.SwapDevice, err error)
```
`psMemSwapDevs` directly calls
github.com/shirou/gopsutil/v4/mem.SwapDevices.
##### 5.6.5.4.
psMemVMem
Function Signature
``` rouge
func psMemVMem() (vmem *mem.VirtualMemoryStat, err error)
```
`psMemVMem` directly calls
github.com/shirou/gopsutil/v4/mem.VirtualMemory.
#### 5.6.6. Network
##### 5.6.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.
##### 5.6.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.
##### 5.6.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.
##### 5.6.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.
##### 5.6.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.
##### 5.6.6.6.
psNetCTStatList
Function Signature
``` rouge
func psNetCTStatList() (ctStats *net.ConntrackStatList, err error)
```
`psNetCTStatList` directly calls
github.com/shirou/gopsutil/v4/net.ConntrackStatList.
##### 5.6.6.7.
psNetFilterCnts
Function Signature
``` rouge
func psNetFilterCnts() (filterCnts []net.FilterStat, err error)
```
`psNetFilterCnts` directly calls
github.com/shirou/gopsutil/v4/net.FilterCounters.
##### 5.6.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.
##### 5.6.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.
##### 5.6.6.10.
psNetIfaces
Function Signature
``` rouge
func psNetIfaces() (ioCnts []net.InterfaceStatList, err error)
```
`psNetIfaces` directly calls
github.com/shirou/gopsutil/v4/net.Interfaces.
##### 5.6.6.11.
psNetPids
Function Signature
``` rouge
func psNetPids() (pids []int32, err error)
```
`psNetPids` directly calls
github.com/shirou/gopsutil/v4/net.Pids.
##### 5.6.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.
##### 5.6.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.
#### 5.6.7. Processes
##### 5.6.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.
##### 5.6.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.
##### 5.6.7.3.
psProcPids
Function Signature
``` rouge
func psProcPids() (pids []int32, err error)
```
`psProcPids` directly calls
github.com/shirou/gopsutil/v4/proc.Pids.
##### 5.6.7.4.
psProcPidExists
Function Signature
``` rouge
func psProcPidExists(pid int32) (exists bool, err error)
```
`psProcPidExists` directly calls
github.com/shirou/gopsutil/v4/proc.PidExists.
#### 5.6.8. Sensors/Thermals
##### 5.6.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).
##### 5.6.8.2.
psSensorTemps
Function Signature
``` rouge
func psSensorTemps() (temps []sensors.TemperatureStat, err error)
```
`psSensorTemps` directly calls
github.com/shirou/gopsutil/v4/sensors.SensorsTemperatures.
#### 5.6.9. Windows Services
Warning
|
All of these functions are only available on Windows. |
##### 5.6.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.
##### 5.6.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.
### 5.7. Strings
These template functions use capabilities from:
- [Standalone](#fn_str_stnd)
- [`r00t2.io/goutils/stringsx`](#fn_str_strsx)
#### 5.7.1. Standalone
These functions are standalone developed purely for this library. For legacy reasons, these have the special prefix `ext`.
##### 5.7.1.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, |
#### 5.7.2.
r00t2.io/goutils/stringsx
These template functions contain capabilities from
r00t2.io/goutils/stringsx.
##### 5.7.2.1.
strsxIsAscii
Function Signature
``` rouge
func strsxIsAscii(s string, allowCtl, allowExt bool) (isAscii bool, err error)
```
`strsxIsAscii` directly calls
r00t2.io/goutils/tplx/sprigx/stringsx.IsAscii.
##### 5.7.2.2.
strsxIsAsciiBuf
Function Signature
``` rouge
func strsxIsAsciiBuf(r io.RuneReader, allowCtl, allowExt bool) (isAscii bool, err error)
```
`strsxIsAsciiBuf` directly calls
r00t2.io/goutils/tplx/sprigx/stringsx.IsAsciiBuf.
##### 5.7.2.3.
strsxIsAsciiSpcl
Function Signature
``` rouge
func strsxIsAsciiSpcl(
s string,
allowCtl, allowPrint, allowExt, allowWs bool,
incl, excl []byte
) (isAscii bool, err error)
```
`strsxIsAsciiSpcl` directly calls
r00t2.io/goutils/tplx/sprigx/stringsx.IsAsciiSpecial.
##### 5.7.2.4.
strsxIsAsciiBufSpcl
Function Signature
``` rouge
func strsxIsAsciiBufSpcl(
r io.RuneReader,
allowCtl, allowPrint, allowExt, allowWs bool,
incl, excl []byte
) (isAscii bool, err error)
```
`strsxIsAsciiBufSpcl` directly calls
r00t2.io/goutils/tplx/sprigx/stringsx.IsAsciiSpecial.
##### 5.7.2.5.
strsxLenSpl
Function Signature
``` rouge
func strsxLenSpl(s string, width uint) (out []string)
```
`strsxLenSpl` directly calls
r00t2.io/goutils/tplx/sprigx/stringsx.LenSplit.
##### 5.7.2.6.
strsxLenSplStr
Function Signature
``` rouge
func strsxLenSplStr(s string, width uint, winNewline bool) (out string)
```
`strsxLenSplStr` directly calls
r00t2.io/goutils/tplx/sprigx/stringsx.LenSplitStr.
##### 5.7.2.7.
strsxPad
Function Signature
``` rouge
func strsxPad(s []string, width uint, pad string, leftPad bool) (out []string)
```
`strsxPad` directly calls
r00t2.io/goutils/tplx/sprigx/stringsx.Pad.
##### 5.7.2.8.
strsxRedact
Function Signature
``` rouge
func strsxRedact(s, maskStr string, leading, trailing uint, newlines bool) (redacted string)
```
`strsxRedact` directly calls
r00t2.io/goutils/tplx/sprigx/stringsx.Redact.
##### 5.7.2.9.
strsxRev
Function Signature
``` rouge
func strsxRev(s string) (revS string)
```
`strsxRev` directly calls
r00t2.io/goutils/tplx/sprigx/stringsx.Reverse.
##### 5.7.2.10.
strsxTrimLns
Function Signature
``` rouge
func strsxTrimLns(s string, left, right bool) (trimmed string)
```
`strsxTrimLns` directly calls
r00t2.io/goutils/tplx/sprigx/stringsx.TrimLines.
##### 5.7.2.11.
strsxTrimSpcLft
Function Signature
``` rouge
func strsxTrimSpcLft(s string) (trimmed string)
```
`strsxTrimSpcLft` directly calls
r00t2.io/goutils/tplx/sprigx/stringsx.TrimSpaceLeft.
##### 5.7.2.12.
strsxTrimSpcRt
Function Signature
``` rouge
func strsxTrimSpcRt(s string) (trimmed string)
```
`strsxTrimSpcRt` directly calls
r00t2.io/goutils/tplx/sprigx/stringsx.TrimSpaceRight.
### 5.8. System/Platform/Architecture
#### 5.8.1.
sysArch
Function Signature
``` rouge
func sysArch() (out string)
```
Returns the
runtime.GOARCH constant.
#### 5.8.2.
sysNumCpu
Function Signature
``` rouge
func sysNumCpu() (cnt int)
```
`sysNumCpu` directly calls
runtime.NumCPU.
#### 5.8.3.
sysOsName
Function Signature
``` rouge
func sysOsName() (out string)
```
Returns the
runtime.GOOS constant.
#### 5.8.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)
### 5.9. 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. |
#### 5.9.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.
#### 5.9.2.
tmFloatMicro
Function Signature
``` rouge
func tmFloatMicro(t time.Time) (f64 float64)
```
`tmFloatMicro` directly calls
(r00t2.io/goutils/timex).F64Microseconds.
#### 5.9.3.
tmFloatMilli
Function Signature
``` rouge
func tmFloatMilli(t time.Time) (f64 float64)
```
`tmFloatMilli` directly calls
(r00t2.io/goutils/timex).F64Milliseconds.
#### 5.9.4.
tmFloatNano
Function Signature
``` rouge
func tmFloatNano(t time.Time) (f64 float64)
```
`tmFloatNano` directly calls
(r00t2.io/goutils/timex).F64Nanoseconds.
#### 5.9.5.
tmFloat
Function Signature
``` rouge
func tmFloat(t time.Time) (f64 float64)
```
`tmFloat` directly calls
(r00t2.io/goutils/timex).F64Seconds.
#### 5.9.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 "" }}
```
#### 5.9.7.
tmNow
Function Signature
``` rouge
func tmNow() (now time.Time)
```
`tmNow` directly calls
time.Now.
#### 5.9.8.
tmParseDur8n
Function Signature
``` rouge
func tmParseDur8n(s string) (d time.Duration, err error)
```
`tmParseDur8n` directly calls
time.ParseDuration.
#### 5.9.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".
#### 5.9.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).
#### 5.9.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).
#### 5.9.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.
## 6. TODO/Wishlist
### 6.1. Function Collections
Functions should be split into more granular function maps that allows a conusmer to only load a certain subset of relevant functions to reduce surface - string functions, network functions, etc.
This would ideally also allow for e.g. FuncMap "generators" that would return a FuncMap of methods bound to a struct with certain contextual settings (e.g. a root path restriction for [Extend OS functions](#todo_os)).
### 6.2. Fallibility
Requires [Function Collections](#todo_collctns) first.
Modeled after Vector’s VRL concept of Fallibility (see also).
Functions should be grouped/selectable by "fallibility" - if they are guaranteed to return a **meaningful** value always, if they are guaranteed to return a value that **may be empty** but no error will be returned, or if a function **may** return an error.
### 6.3. Function Scope Segregation
Requires [Function Collections](#todo_collctns) first.
Modeled (slightly) after Vector’s VRL concept of purity.
As more functions get added (and even with the present function set), it may be desired that only functions that work only with provided data are exposed to templates.
The goal is to scope/separate functions in such a way that they are "tagged" with multiple attributes/characteristics:
- [Fallibility](#todo_fallible)
- External Read (e.g. [reading arbitrary files](#todo_os_fs))
- Internal Modify (would potentially transform source data/data structures)
- External Modify (would affect the invoking system, e.g. [\[todo_os_fs\]](#todo_os_fs))
- Arbitrary Execution (e.g. `osExec` — see [\[todo_os_fs\]](#todo_os_fs))
- Network Access (e.g. would involve creating network connections instead of operating on provided data locally)
A risk "score" from 1-10 should also be implemented with the above scopes/classes for further/alternative filtering by consumers.
### 6.4. Extend OS functions
Requires [Function Scope Segregation](#todo_safe) first. (Not technically, but can provide a pretty big risk of not split out first.)
Adding the ability to read files from the filesystem should be added. As part of this, however, a package-level variable should be implemented (or [Function Collections](#todo_collctns)) that can restrict reading to a specific prefix.
Off the top of my head:
- `osReadFile`
- Returns an `*os.File`.
- Closing the handler gets tricky, though… it can be done from within the template, but templates also have no `defer` to my knowledge. Caveat emptor.
- `osReadFileBuf`
- Will return a `*bytes.Buffer` with the contents of a file.
- A little safer than `osReadFile` as it’s backed by a static set of bytes and doesn’t need to be `.Close()`'d.
- `osReadFileBytes`
- Should include an optional length limiter, so data from e.g. `/dev/urandom` can be read from.
- `osReadFileStr`
- Would return `string` instead of `[]byte`.
- `osReadDir`
- Returns a `[]fs.DirEntry` of a given path via `os.ReadDir`.
- `osStat`
- Returns an `fs.FileInfo` from an `os.Stat` or `os.LStat` (controlled by tpl function parameter)
- `osExec`
- Exactly what you’d think. Returns a command via an `os/exec.Cmd`, with params passed to `os/exec.Command` (plus `*bytes.Buffer`s set to `.Stdin` and `.Stdout`).
These obviously have the potential to be **incredibly** dangerous if using untrusted template strings.
#### 6.4.1. Environment Variables
- `osEnvGet` (`os.Getenv`)
- `osEnvs` (returns `os.Environ` result)
- `osEnvsMap` and other
r00t2.io/sysutils/envs funcs
### 6.5. System Functions
This would be… particularly tricky.
I essentially want to expose a large amount of functionality from
golang.org/x/sys/unix and golang.org/x/sys/windows (and its subpackages).
At the least I should have a way to (attempt to) convert/coerce an `fs.FileInfo.Sys()` into the platform-appropriate definite object (e.g. a
golang.org/x/sys/unix.Stat_t and/or golang.org/x/sys/unix.Statx_t, or a golang.org/x/sys/windows.Win32FileAttributeData).
### 6.6. Encoding Functions
Should require [Function Collections](#todo_collctns) first (at least for grouping).
- `hex*` functions (
encoding/hex)
- Technically hex is "base16"
- `hexx*` functions (r00t2.io/goutils/encodingx/hexx)
- `b64*` functions (encoding/base64)
### 6.7. UUID Functions
Should require [Function Collections](#todo_collctns) first (at least for grouping).
- `uuid*` functions for
github.com/google/uuid
- `uuidx*` functions for r00t2.io/goutils/uuidx
### 6.8. URL Functions
Expose
net/url functions to derive URLs.
### 6.9. Live Networking Functions
Requires [Function Scope Segregation](#todo_safe) first.
Sometimes networking data lookup is needed at time of render/contextual to render.
- `dns*` (DNS lookup options from
net)
- With the ability to use a custom resolver (would need [Function Collections](#todo_collctns))
- `http*` functions
- `httpReq` for a ` for a shorthand/one-shot version of `httpReq` above
- `resty*` functions for
net/http.Request
- `httpresty.dev/v3?
- Maybe via a configured [Function Collections](#todo_collctns) instead