From 1bd6e1256c1bb0bd58550015b56b4e432a5bdcc8 Mon Sep 17 00:00:00 2001 From: brent saner Date: Thu, 29 Jan 2026 19:02:21 -0500 Subject: [PATCH] v1.16.3 ADDED: * Much more functions to tplx/sprigx --- .githooks/pre-commit/01-docgen | 13 +- go.mod | 22 +- go.sum | 57 +- tplx/sprigx/README.adoc | 911 ++++++++- tplx/sprigx/README.html | 2432 +++++++++++++++++------- tplx/sprigx/README.md | 699 ------- tplx/sprigx/consts.go | 110 +- tplx/sprigx/consts_darwin.go | 9 + tplx/sprigx/consts_linux.go | 25 + tplx/sprigx/consts_unknown.go | 9 + tplx/sprigx/consts_windows.go | 24 + tplx/sprigx/funcs.go | 17 + tplx/sprigx/funcs_tpl_dbg.go | 17 - tplx/sprigx/funcs_tpl_meta.go | 14 + tplx/sprigx/funcs_tpl_os.go | 68 +- tplx/sprigx/funcs_tpl_psutils.go | 43 + tplx/sprigx/funcs_tpl_psutils_linux.go | 15 + tplx/sprigx/funcs_tpl_sys.go | 40 +- 18 files changed, 3036 insertions(+), 1489 deletions(-) delete mode 100644 tplx/sprigx/README.md create mode 100644 tplx/sprigx/consts_darwin.go create mode 100644 tplx/sprigx/consts_linux.go create mode 100644 tplx/sprigx/consts_unknown.go create mode 100644 tplx/sprigx/consts_windows.go delete mode 100644 tplx/sprigx/funcs_tpl_dbg.go create mode 100644 tplx/sprigx/funcs_tpl_meta.go create mode 100644 tplx/sprigx/funcs_tpl_psutils.go create mode 100644 tplx/sprigx/funcs_tpl_psutils_linux.go diff --git a/.githooks/pre-commit/01-docgen b/.githooks/pre-commit/01-docgen index 80e2506..69087a3 100755 --- a/.githooks/pre-commit/01-docgen +++ b/.githooks/pre-commit/01-docgen @@ -22,9 +22,18 @@ for f in $(find . -type f -iname "README.adoc"); do if command -v pandoc &> /dev/null; then newf="${pfx}.md" + + set +e asciidoctor -a ROOTDIR="${orig}/" -b docbook -o - "${f}" | pandoc -f docbook -t markdown_strict -o "${newf}" - echo "Generated ${newf} from ${f}" - git add "${newf}" + if [ $? -eq 0 ]; + then + echo "Generated ${newf} from ${f}" + git add "${newf}" + else + echo "Failed to generate ${newf} from ${f}" + git rm "${newf}" + fi + set -e fi cd ${orig} done diff --git a/go.mod b/go.mod index 689b9e5..c6301fc 100644 --- a/go.mod +++ b/go.mod @@ -4,24 +4,32 @@ go 1.25 require ( github.com/Masterminds/sprig/v3 v3.3.0 - github.com/coreos/go-systemd/v22 v22.6.0 + github.com/coreos/go-systemd/v22 v22.7.0 github.com/davecgh/go-spew v1.1.1 github.com/google/uuid v1.6.0 + github.com/shirou/gopsutil/v4 v4.25.12 go4.org/netipx v0.0.0-20231129151722-fdeea329fbba - golang.org/x/sys v0.39.0 - r00t2.io/sysutils v1.15.1 + golang.org/x/sys v0.40.0 + r00t2.io/sysutils v1.16.0 ) require ( - dario.cat/mergo v1.0.1 // indirect + dario.cat/mergo v1.0.2 // indirect github.com/Masterminds/goutils v1.1.1 // indirect - github.com/Masterminds/semver/v3 v3.3.0 // indirect + github.com/Masterminds/semver/v3 v3.4.0 // indirect github.com/djherbis/times v1.6.0 // indirect + github.com/ebitengine/purego v0.9.1 // indirect + github.com/go-ole/go-ole v1.3.0 // indirect github.com/huandu/xstrings v1.5.0 // indirect + github.com/lufia/plan9stats v0.0.0-20251013123823-9fd1530e3ec3 // indirect github.com/mitchellh/copystructure v1.2.0 // indirect github.com/mitchellh/reflectwalk v1.0.2 // indirect + github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 // indirect github.com/shopspring/decimal v1.4.0 // indirect - github.com/spf13/cast v1.7.0 // indirect - golang.org/x/crypto v0.26.0 // indirect + github.com/spf13/cast v1.10.0 // indirect + github.com/tklauser/go-sysconf v0.3.16 // indirect + github.com/tklauser/numcpus v0.11.0 // indirect + github.com/yusufpapurcu/wmi v1.2.4 // indirect + golang.org/x/crypto v0.47.0 // indirect golang.org/x/sync v0.19.0 // indirect ) diff --git a/go.sum b/go.sum index 8a58770..12a6440 100644 --- a/go.sum +++ b/go.sum @@ -1,21 +1,26 @@ -dario.cat/mergo v1.0.1 h1:Ra4+bf83h2ztPIQYNP99R6m+Y7KfnARDfID+a+vLl4s= -dario.cat/mergo v1.0.1/go.mod h1:uNxQE+84aUszobStD9th8a29P2fMDhsBdgRYvZOxGmk= +dario.cat/mergo v1.0.2 h1:85+piFYR1tMbRrLcDwR18y4UKJ3aH1Tbzi24VRW1TK8= +dario.cat/mergo v1.0.2/go.mod h1:E/hbnu0NxMFBjpMIE34DRGLWqDy0g5FuKDhCb31ngxA= github.com/Masterminds/goutils v1.1.1 h1:5nUrii3FMTL5diU80unEVvNevw1nH4+ZV4DSLVJLSYI= github.com/Masterminds/goutils v1.1.1/go.mod h1:8cTjp+g8YejhMuvIA5y2vz3BpJxksy863GQaJW2MFNU= -github.com/Masterminds/semver/v3 v3.3.0 h1:B8LGeaivUe71a5qox1ICM/JLl0NqZSW5CHyL+hmvYS0= -github.com/Masterminds/semver/v3 v3.3.0/go.mod h1:4V+yj/TJE1HU9XfppCwVMZq3I84lprf4nC11bSS5beM= +github.com/Masterminds/semver/v3 v3.4.0 h1:Zog+i5UMtVoCU8oKka5P7i9q9HgrJeGzI9SA1Xbatp0= +github.com/Masterminds/semver/v3 v3.4.0/go.mod h1:4V+yj/TJE1HU9XfppCwVMZq3I84lprf4nC11bSS5beM= github.com/Masterminds/sprig/v3 v3.3.0 h1:mQh0Yrg1XPo6vjYXgtf5OtijNAKJRNcTdOOGZe3tPhs= github.com/Masterminds/sprig/v3 v3.3.0/go.mod h1:Zy1iXRYNqNLUolqCpL4uhk6SHUMAOSCzdgBfDb35Lz0= -github.com/coreos/go-systemd/v22 v22.6.0 h1:aGVa/v8B7hpb0TKl0MWoAavPDmHvobFe5R5zn0bCJWo= -github.com/coreos/go-systemd/v22 v22.6.0/go.mod h1:iG+pp635Fo7ZmV/j14KUcmEyWF+0X7Lua8rrTWzYgWU= +github.com/coreos/go-systemd/v22 v22.7.0 h1:LAEzFkke61DFROc7zNLX/WA2i5J8gYqe0rSj9KI28KA= +github.com/coreos/go-systemd/v22 v22.7.0/go.mod h1:xNUYtjHu2EDXbsxz1i41wouACIwT7Ybq9o0BQhMwD0w= github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/djherbis/times v1.6.0 h1:w2ctJ92J8fBvWPxugmXIv7Nz7Q3iDMKNx9v5ocVH20c= github.com/djherbis/times v1.6.0/go.mod h1:gOHeRAz2h+VJNZ5Gmc/o7iD9k4wW7NMVqieYCY99oc0= +github.com/ebitengine/purego v0.9.1 h1:a/k2f2HQU3Pi399RPW1MOaZyhKJL9w/xFpKAg4q1s0A= +github.com/ebitengine/purego v0.9.1/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ= github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHkI4W8= github.com/frankban/quicktest v1.14.6/go.mod h1:4ptaffx2x8+WTWXmUCuVU6aPUX1/Mz7zb5vbUoiM6w0= -github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI= -github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY= +github.com/go-ole/go-ole v1.2.6/go.mod h1:pprOEPIfldk/42T2oK7lQ4v4JSDwmV0As9GaiUsvbm0= +github.com/go-ole/go-ole v1.3.0 h1:Dt6ye7+vXGIKZ7Xtk4s6/xVdGDQynvom7xCFEdWr6uE= +github.com/go-ole/go-ole v1.3.0/go.mod h1:5LS6F96DhAwUc7C+1HLexzMXY1xGRSryjyPPKW6zv78= +github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8= +github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU= github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0= github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= github.com/huandu/xstrings v1.5.0 h1:2ag3IFq9ZDANvthTwTiqSSZLjDc+BedvHPAp5tJy2TI= @@ -24,33 +29,43 @@ github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE= github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk= github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY= github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE= +github.com/lufia/plan9stats v0.0.0-20251013123823-9fd1530e3ec3 h1:PwQumkgq4/acIiZhtifTV5OUqqiP82UAl0h87xj/l9k= +github.com/lufia/plan9stats v0.0.0-20251013123823-9fd1530e3ec3/go.mod h1:autxFIvghDt3jPTLoqZ9OZ7s9qTGNAWmYCjVFWPX/zg= github.com/mitchellh/copystructure v1.2.0 h1:vpKXTN4ewci03Vljg/q9QvCGUDttBOGBIa15WveJJGw= github.com/mitchellh/copystructure v1.2.0/go.mod h1:qLl+cE2AmVv+CoeAwDPye/v+N2HKCj9FbZEVFJRxO9s= github.com/mitchellh/reflectwalk v1.0.2 h1:G2LzWKi524PWgd3mLHV8Y5k7s6XUvT0Gef6zxSIeXaQ= github.com/mitchellh/reflectwalk v1.0.2/go.mod h1:mSTlrgnPZtwu0c4WaC2kGObEpuNDbx0jmZXqmk4esnw= github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= +github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 h1:o4JXh1EVt9k/+g42oCprj/FisM4qX9L3sZB3upGN2ZU= +github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55/go.mod h1:OmDBASR4679mdNQnz2pUhc2G8CO2JrUAVFDRBDP/hJE= github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8= github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs= +github.com/shirou/gopsutil/v4 v4.25.12 h1:e7PvW/0RmJ8p8vPGJH4jvNkOyLmbkXgXW4m6ZPic6CY= +github.com/shirou/gopsutil/v4 v4.25.12/go.mod h1:EivAfP5x2EhLp2ovdpKSozecVXn1TmuG7SMzs/Wh4PU= github.com/shopspring/decimal v1.4.0 h1:bxl37RwXBklmTi0C79JfXCEBD1cqqHt0bbgBAGFp81k= github.com/shopspring/decimal v1.4.0/go.mod h1:gawqmDU56v4yIKSwfBSFip1HdCCXN8/+DMd9qYNcwME= -github.com/spf13/cast v1.7.0 h1:ntdiHjuueXFgm5nzDRdOS4yfT43P5Fnud6DH50rz/7w= -github.com/spf13/cast v1.7.0/go.mod h1:ancEpBxwJDODSW/UG4rDrAqiKolqNNh2DX3mk86cAdo= -github.com/stretchr/testify v1.5.1 h1:nOGnQDM7FYENwehXlg/kFVnos3rEvtKTjRvOWSzb6H4= -github.com/stretchr/testify v1.5.1/go.mod h1:5W2xD1RspED5o8YsWQXVCued0rvSQ+mT+I5cxcmMvtA= +github.com/spf13/cast v1.10.0 h1:h2x0u2shc1QuLHfxi+cTJvs30+ZAHOGRic8uyGTDWxY= +github.com/spf13/cast v1.10.0/go.mod h1:jNfB8QC9IA6ZuY2ZjDp0KtFO2LZZlg4S/7bzP6qqeHo= +github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U= +github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U= +github.com/tklauser/go-sysconf v0.3.16 h1:frioLaCQSsF5Cy1jgRBrzr6t502KIIwQ0MArYICU0nA= +github.com/tklauser/go-sysconf v0.3.16/go.mod h1:/qNL9xxDhc7tx3HSRsLWNnuzbVfh3e7gh/BmM179nYI= +github.com/tklauser/numcpus v0.11.0 h1:nSTwhKH5e1dMNsCdVBukSZrURJRoHbSEQjdEbY+9RXw= +github.com/tklauser/numcpus v0.11.0/go.mod h1:z+LwcLq54uWZTX0u/bGobaV34u6V7KNlTZejzM6/3MQ= +github.com/yusufpapurcu/wmi v1.2.4 h1:zFUKzehAFReQwLys1b/iSMl+JQGSCSjtVqQn9bBrPo0= +github.com/yusufpapurcu/wmi v1.2.4/go.mod h1:SBZ9tNy3G9/m5Oi98Zks0QjeHVDvuK0qfxQmPyzfmi0= go4.org/netipx v0.0.0-20231129151722-fdeea329fbba h1:0b9z3AuHCjxk0x/opv64kcgZLBseWJUpBw5I82+2U4M= go4.org/netipx v0.0.0-20231129151722-fdeea329fbba/go.mod h1:PLyyIXexvUFg3Owu6p/WfdlivPbZJsZdgWZlrGope/Y= -golang.org/x/crypto v0.26.0 h1:RrRspgV4mU+YwB4FYnuBoKsUapNIL5cohGAmSH3azsw= -golang.org/x/crypto v0.26.0/go.mod h1:GY7jblb9wI+FOo5y8/S2oY4zWP07AkOJ4+jxCqdqn54= +golang.org/x/crypto v0.47.0 h1:V6e3FRj+n4dbpw86FJ8Fv7XVOql7TEwpHapKoMJ/GO8= +golang.org/x/crypto v0.47.0/go.mod h1:ff3Y9VzzKbwSSEzWqJsJVBnWmRwRSHt/6Op5n9bQc4A= golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4= golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI= +golang.org/x/sys v0.0.0-20190916202348-b4ddaad3f8a3/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= +golang.org/x/sys v0.0.0-20201204225414-ed752295db88/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.0.0-20220615213510-4f61da869c0c/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= -golang.org/x/sys v0.39.0 h1:CvCKL8MeisomCi6qNZ+wbb0DN9E5AATixKsvNtMoMFk= -golang.org/x/sys v0.39.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks= -gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= -gopkg.in/yaml.v2 v2.3.0 h1:clyUAQHOM3G0M3f5vQj7LuJrETvjVot3Z5el9nffUtU= -gopkg.in/yaml.v2 v2.3.0/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI= +golang.org/x/sys v0.1.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.40.0 h1:DBZZqJ2Rkml6QMQsZywtnjnnGvHza6BTfYFWY9kjEWQ= +golang.org/x/sys v0.40.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks= gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= -r00t2.io/sysutils v1.15.1 h1:0EVZZAxTFqQN6jjfjqUKkXye0LMshUA5MO7l3Wd6wH8= -r00t2.io/sysutils v1.15.1/go.mod h1:T0iOnaZaSG5NE1hbXTqojRZc0ia/u8TB73lV7zhMz58= diff --git a/tplx/sprigx/README.adoc b/tplx/sprigx/README.adoc index 7d42724..71b3dcc 100644 --- a/tplx/sprigx/README.adoc +++ b/tplx/sprigx/README.adoc @@ -119,7 +119,7 @@ import ( "text/template" "github.com/Masterminds/sprig/v3" - "r00t2.io/goutils/tplx/sprigx" + "r00t2.io/goutils/tplx/sprigx" ) const ( @@ -170,7 +170,7 @@ var ( ---- ==== -and a function can even be explicitly overridden. +and a function can even be explicitly [[override]]overridden. [%collapsible] .(show) @@ -216,63 +216,191 @@ var ( == 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 types of arguments/parameters it accepts, +what it returns, and if it may potentially return an error or not. + +[id="fn_dbg"] +=== Debugging + +[id="fn_dbg_dump"] +==== `dump` +[source,go] +.Function Signature +---- +func dump(a ...interface{}) (out string) +---- + +The `dump` function directly calls https://pkg.go.dev/github.com/davecgh/go-spew/spew#Sdump[`github.com/davecgh/go-spew/spew.Sdump`^] +for whatever object(s) is/are passed to it. + +[id="fn_meta"] +=== "Meta"/Template Helpers + +[id="fn_meta_isnil"] +==== `metaIsNil` +[source,go] +.Function Signature +---- +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 https://pkg.go.dev/text/template#IsTrue[`text/template.IsTrue`^] and https://pkg.go.dev/html/template#IsTrue[`html/template.IsTrue`^] (expressed in templates as `{{ if ... }}`) leaves, as those functions/expressions return false for e.g. `false` booleans AND nils. + +[id="fn_meta_nop"] +==== `Nop` +[source,go] +.Function Signature +---- +func Nop(obj ...any) (s string) +---- + +`Nop` is not actually a *template* function, but rather an exported *Go* function that one can use in +an <> to explicitly disable certain template 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. + [id="fn_os"] === Operating System -[id="fn_os_hstnm"] -==== `osHostname` -`osHostname` simply wraps and returns the result of calling https://pkg.go.dev/os#Hostname[`os.Hostname`^]. +[id="fn_os_fqdn"] +==== `osFQDN` +[source,go] +.Function Signature +---- +func osFQDN() (fqdn string, err error) +---- -As such, it comes with the same caveats - it's possible for it to error, and it isn't guaranteed to be an FQDN -- it will be precisely/exactly whatever the kernel's hostname is set as. +`osFQDN` currently just directly calls https://pkg.go.dev/os#Hostname[`os.Hostname`^]. -[id="fn_sys"] -=== System/Platform/Architecture +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. -[id="fn_sys_arch"] -==== `sysArch` -Returns the https://pkg.go.dev/runtime#GOARCH[`runtime.GOARCH`^] constant. +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. -[id="fn_sys_numcpu"] -==== `sysNumCpu` -Returns the value from https://pkg.go.dev/runtime#NumCPU[`runtime.NumCPU`^]. +To (relatively) predictably get the "short hostname", use <>. +To directly/predictably use https://pkg.go.dev/os#Hostname[`os.Hostname`^], use <>. -[id="fn_sys_os"] -==== `sysOsName` -Returns the https://pkg.go.dev/runtime#GOOS[`runtime.GOOS`^] constant. +[id="fn_os_grpid"] +==== `osGroupById` +[source,go] +.Function Signature +---- +func osGroupById[T string | int](gid T) (g *user.Group, err error) +---- -[id="fn_sys_rntm"] -==== `sysRuntime` -This function returns a `map[string]string` of various information from the https://pkg.go.dev/runtime[`runtime` stdlib library^]. +`osGroupById` returns an https://pkg.go.dev/os/user#Group[`os/user.Group`^] from a given group ID/GID. -Specifically, the following are returned. +It more or less behaves exactly like https://pkg.go.dev/os/user#LookupGroupId[`os/user.LookupGroupId`^], +except it will accept either a `string` *or* an `int` as the GID. + +[id="fn_os_grpnm"] +==== `osGroupByName` +[source,go] +.Function Signature +---- +func osGroupByName(grpNm string) (g *user.Group, err error) +---- + +`osGroupByName` returns an https://pkg.go.dev/os/user#Group[`os/user.Group`^] from a given group name. + +It behaves exactly like https://pkg.go.dev/os/user#LookupGroup[`os/user.LookupGroup`^]. + +[id="fn_os_hst"] +==== `osHost` +[source,go] +.Function Signature +---- +func osHost() (out string, err error) +---- + +`osHost` returns the "short hostname" by calling https://pkg.go.dev/os#Hostname[`os.Hostname`^] +and returning the first "host label" (as RFCs refer to it). + +e.g.: + +[source,gotemplate] +---- +{{- $fqdn := osFQDN -}} +{{- $h := osHost -}} +{{- $cmp := index ($fqdn | splitList ".") 0 -}} +osHost {{ $h }} should be equal to first label of FQDN {{ $cmp }}. +---- [TIP] ==== -The value type is a direct link to the `runtime` documentation providing more detail about the associated value. - -Because all values are mapped as strings, they can be converted back to their native type via e.g. the https://masterminds.github.io/sprig/conversion.html[Sprig conversion functions^] if necessary. +The `splitList` function shown aboce is from the https://masterminds.github.io/sprig/string_slice.html[`sprig` string slice functions^]. ==== -.`sysRuntime` Values -[cols="^.^3m,^.^3",options="header"] -|=== -| Key | Value Type +To (try to) get the FQDN, use <>. +To directly use https://pkg.go.dev/os#Hostname[`os.Hostname`^], use <>. -| compiler | https://pkg.go.dev/runtime#Compiler[string^] -| arch | https://pkg.go.dev/runtime#GOARCH[string^] -| os | https://pkg.go.dev/runtime#GOOS[string^] -| maxprocs | https://pkg.go.dev/runtime#GOMAXPROCS[int^] footnote:[For safety concerns, `sprigx` does not allow *setting* `GOMAXPROCS`, this value only contains the *current* `GOMAXPROCS` value.] -| cpu_cnt | https://pkg.go.dev/runtime#NumCPU[int^] -| num_cgo | https://pkg.go.dev/runtime#NumCgoCall[int^] -| num_go | https://pkg.go.dev/runtime#NumGoroutine[int^] -| go_ver | https://pkg.go.dev/runtime#Version[string^] -|=== +[id="fn_os_hstnm"] +==== `osHostname` +[source,go] +.Function Signature +---- +func osHostname() (out string, err error) +---- -As a convenience, some of these values also have their own dedicated functions as well: +`osHostname` directly calls https://pkg.go.dev/os#Hostname[`os.Hostname`^]. -* <> -* <> -* <> +[id="fn_os_idst"] +==== `osIdState` +[source,go] +.Function Signature +---- +func osIdState() (idst sysutils.IDState) +---- + +`osIdState` returns the current runtime process' https://pkg.go.dev/r00t2.io/sysutils#IDState[`r00t2.io/sysutils.IDState`^]. + +It directly calls https://pkg.go.dev/r00t2.io/sysutils#GetIDState[`r00t2.io/sysutils.GetIDState`^]. + +[WARNING] +==== +This is more or less useless on Windows; it returns only a dummy struct for cross-platform compatibility. +==== + +[id="fn_os_usr"] +==== `osUser` +[source,go] +.Function Signature +---- +func osUser() (u *user.User, err error) +---- + +`osUser` returns the current runtime process' https://pkg.go.dev/os/user#User[`os/user.User`^]. + +It directly calls https://pkg.go.dev/os/user#Current[`os/user.Current`^]. + +[id="fn_os_usrid"] +==== `osUserById` +[source,go] +.Function Signature +---- +func osUserById[T string | int](uid T) (u *user.User, err error) +---- + +`osUserById` returns an https://pkg.go.dev/os/user#User[`os/user.User`^] from a given user ID/UID. + +It more or less behaves exactly like https://pkg.go.dev/os/user#LookupId[`os/user.LookupId`^], +except it will accept either a `string` *or* an `int` as the UID. + +[id="fn_os_usrnm"] +==== `osUserByName` +[source,go] +.Function Signature +---- +func osUserByName(userNm string) (u *user.User, err error) +---- + +`osUserByName` returns an https://pkg.go.dev/os/user#User[`os/user.User`^] from a given username. + +It directly calls https://pkg.go.dev/os/user#Lookup[`os/user.Lookup`^]. [id="fn_path"] === Paths @@ -283,11 +411,18 @@ These operate similar to https://pkg.go.dev/path[the `path` stdlib library^] and [id="fn_path_gnrc_pj"] ===== `pathJoin` -`pathJoin` operates *exactly* like https://pkg.go.dev/path#Join[`path.Join`^] in stdlib. +[source,go] +.Function Signature +---- +func pathJoin(elem ...string) (out string) +---- + +`pathJoin` directly calls https://pkg.go.dev/path#Join[`path.Join`^]. [WARNING] ==== -If you are joining paths in a pipeline, you almost assuredly want <> or <> instead unless you are explicitly *appending* a pipeline result to a path. +If you are joining paths in a pipeline, you almost assuredly want <> or <> instead +unless you are explicitly *appending* a pipeline result to a path. ==== [source,gotemplate] @@ -308,9 +443,16 @@ a/b/c [id="fn_path_gnrc_ppj"] ===== `pathPipeJoin` +[source,go] +.Function Signature +---- +func pathPipeJoin(elems ...string) (out string) +---- + `pathPipeJoin` operates like <> 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. +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. [source,gotemplate] ---- @@ -331,6 +473,12 @@ a/b/c [id="fn_path_gnrc_psj"] ===== `pathSliceJoin` +[source,go] +.Function Signature +---- +func pathSliceJoin(sl []string) (out string) +---- + `pathSliceJoin` joins a slice of path segment strings (`[]string`) instead of a variadic sequence of strings. [TIP] @@ -357,7 +505,15 @@ a/b/c [id="fn_path_gnrc_pspj"] ===== `pathSlicePipeJoin` -`pathSlicePipeJoin` operates like <> in that it is suitable for pipeline use in which the root/base path is passed in from the pipeline, but it is like <> in that it then also accepts a slice of path segments (`[]string`) to append to that base path. +[source,go] +.Function Signature +---- +func pathSlicePipeJoin(sl []string, root string) (out string) +---- + +`pathSlicePipeJoin` operates like <> in that it is suitable for pipeline use in which the root/base path is passed in +from the pipeline, but it is like <> in that it then also accepts a slice of +path segments (`[]string`) to append to that base path. [TIP] ==== @@ -382,6 +538,12 @@ renders as: [id="fn_path_gnrc_psubj"] ===== `pathSubJoin` +[source,go] +.Function Signature +---- +func pathSubJoin(root string, elems ...string) (out string) +---- + `pathSubJoin` operates like <> but it expects an explicit root/base path. The pipeline-friendly equivalent of this is <>. @@ -415,11 +577,18 @@ It is recommended to make use of <> to conditionally format path base [id="fn_path_os_pj"] ===== `osPathJoin` -`osPathJoin` operates *exactly* like https://pkg.go.dev/path/filepath#Join[`path/filepath.Join`^] in stdlib. +[source,go] +.Function Signature +---- +func osPathJoin(elem ...string) (out string) +---- + +`osPathJoin` directly calls https://pkg.go.dev/path/filepath#Join[`path/filepath.Join`^]. [WARNING] ==== -If you are joining paths in a pipeline, you almost assuredly want <> or <> instead unless you are explicitly *appending* a pipeline result to a path. +If you are joining paths in a pipeline, you almost assuredly want <> or <> instead unless you are +explicitly *appending* a pipeline result to a path. ==== [source,gotemplate] @@ -455,9 +624,16 @@ C:/a/b/c [id="fn_path_os_ppj"] ===== `osPathPipeJoin` +[source,go] +.Function Signature +---- +func osPathPipeJoin(elems ...string) (out string) +---- + `osPathPipeJoin` operates like <> (except using OS-specific path separators). -This makes it much more suitable for use in template pipelines, as the previous value in a pipeline is passed in as the last element to the next pipe function. +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. [source,gotemplate] ---- @@ -489,6 +665,12 @@ a/b/c [id="fn_path_ossep"] ===== `osPathSep` +[source,go] +.Function Signature +---- +func osPathSep() (out string) +---- + `osPathSep` returns the https://pkg.go.dev/os#PathSeparator[`os.PathSeparator`^] for this OS. [source,gotemplate] @@ -514,6 +696,12 @@ renders as: [id="fn_path_os_psj"] ===== `osPathSliceJoin` +[source,go] +.Function Signature +---- +func osPathSliceJoin(sl []string) (out string) +---- + `osPathSliceJoin` operates like <> but with OS-specific path separators. [TIP] @@ -551,6 +739,12 @@ a/b/c [id="fn_path_os_pspj"] ===== `osPathSlicePipeJoin` +[source,go] +.Function Signature +---- +func osPathSlicePipeJoin(sl []string, root string) (out string) +---- + `osPathSlicePipeJoin` operates like <> but with OS-specific separators. [TIP] @@ -586,6 +780,12 @@ renders as: [id="fn_path_os_psubj"] ===== `osPathSubJoin` +[source,go] +.Function Signature +---- +func osPathSubJoin(root string, elems ...string) (out string) +---- + `osPathSubJoin` operates like <> but with OS-specific separators. The pipeline-friendly equivalent of this is <>. @@ -617,11 +817,550 @@ renders as: ---- |=== +[id="fn_ps"] +=== PSUtils +These are functions from https://pkg.go.dev/github.com/shirou/gopsutil/v4[`github.com/shirou/gopsutil/v4`^] packages. + +[id="fn_ps_cpu"] +==== CPU/Processor + +[id="fn_ps_cpu_cnts"] +===== `psCpuCnts` +[source,go] +.Function Signature +---- +func psCpuCnts(logical bool) (numCpu int, err error) +---- + +`psCpuCnts` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/cpu#Counts[`github.com/shirou/gopsutil/v4/cpu.Counts`^]. + +[id="fn_ps_cpu_info"] +===== `psCpuInfo` +[source,go] +.Function Signature +---- +func psCpuInfo() (cpuInfo [](github.com/shirou/gopsutil/v4/cpu).Info, err error) +---- + +`psCpuInfo` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/cpu#Info[`github.com/shirou/gopsutil/v4/cpu.Info`^]. + +[id="fn_ps_cpu_pct"] +===== `psCpuPct` +[source,go] +.Function Signature +---- +func psCpuPct(interval time.Duration, percpu bool) (pcts []float64, err error) +---- + +`psCpuPct` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/cpu#Percent[`github.com/shirou/gopsutil/v4/cpu.Percent`^]. + +[id="fn_ps_cpu_tms"] +===== `psCpuTimes` +[source,go] +.Function Signature +---- +func psCpuTimes(percpu bool) (cpuTimes []TimesStat, err error) +---- + +`psCpuTimes` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/cpu#Times[`github.com/shirou/gopsutil/v4/cpu.Times`^]. + +[id="fn_ps_dsk"] +==== Disk + +[id="fn_ps_dsk_iocnts"] +===== `psDiskIoCnts` +[source,go] +.Function Signature +---- +func psDiskIoCnts(names ...string) (stats map[string]IOCountersStat, err error) +---- + +`psDiskIoCnts` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/disk#IOCounters[`github.com/shirou/gopsutil/v4/disk.IOCounters`^]. + +[id="fn_ps_dsk_lbl"] +===== `psDiskLabel` +[source,go] +.Function Signature +---- +func psDiskLabel(name string) (label string, err error) +---- + +`psDiskLabel` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/disk#Label[`github.com/shirou/gopsutil/v4/disk.Label`^]. + +[id="fn_ps_dsk_parts"] +===== `psDiskParts` +[source,go] +.Function Signature +---- +func psDiskParts(all bool) (parts [](github.com/shirou/gopsutil/v4/disk).PartitionStat, err error) +---- + +`psDiskParts` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/disk#Partitions[`github.com/shirou/gopsutil/v4/disk.Partitions`^]. + +[id="fn_ps_dsk_srl"] +===== `psDiskSerial` +[source,go] +.Function Signature +---- +func psDiskSerial(name string) (serial string, err error) +---- + +`psDiskSerial` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/disk#SerialNumber[`github.com/shirou/gopsutil/v4/disk.SerialNumber`^]. + +[id="fn_ps_dsk_usg"] +===== `psDiskUsage` +[source,go] +.Function Signature +---- +func psDiskUsage(path string) (usage *(github.com/shirou/gopsutil/v4/disk).UsageStat, err error) +---- + +`psDiskUsage` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/disk#Usage[`github.com/shirou/gopsutil/v4/disk.Usage`^]. + +[id="fn_ps_hst"] +==== Host + +[id="fn_ps_hst_boot"] +===== `psHostBoot` +[source,go] +.Function Signature +---- +func psHostBoot() (bootEpoch uint64, err error) +---- + +`psHostBoot` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/host#BootTime[`github.com/shirou/gopsutil/v4/host.BootTime`^]. + +[id="fn_ps_hst_id"] +===== `psHostId` +[source,go] +.Function Signature +---- +func psHostId() (hostId string, err error) +---- + +`psHostId` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/host#HostID[`github.com/shirou/gopsutil/v4/host.HostID`^]. + +[id="fn_ps_hst_info"] +===== `psHostInfo` +[source,go] +.Function Signature +---- +func psHostInfo() (info *(github.com/shirou/gopsutil/v4/host).InfoStat, err error) +---- + +`psHostInfo` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/host#Info[`github.com/shirou/gopsutil/v4/host.Info`^]. + +[id="fn_ps_hst_krnarch"] +===== `psHostKernArch` +[source,go] +.Function Signature +---- +func psHostKernArch() (arch string, err error) +---- + +`psHostKernArch` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/host#KernelArch[`github.com/shirou/gopsutil/v4/host.KernelArch`^]. + +[id="fn_ps_hst_krnver"] +===== `psHostKernVer` +[source,go] +.Function Signature +---- +func psHostKernVer() (ver string, err error) +---- + +`psHostKernVer` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/host#KernelVersion[`github.com/shirou/gopsutil/v4/host.KernelVersion`^]. + +[id="fn_ps_hst_plat"] +===== `psHostPlatInfo` +[source,go] +.Function Signature +---- +func psHostPlatInfo() (platInfo [3]string, err error) +---- + +`psHostPlatInfo` wraps https://pkg.go.dev/github.com/shirou/gopsutil/v4/host#PlatformInformation[`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`. + +[id="fn_ps_hst_uptm"] +===== `psHostPlatUptime` +[source,go] +.Function Signature +---- +func psHostPlatUptime() (uptimeSecs uint64, err error) +---- + +`psHostPlatUptime` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/host#Uptime[`github.com/shirou/gopsutil/v4/host.Uptime`^]. + +[id="fn_ps_hst_usrs"] +===== `psHostUsers` +[source,go] +.Function Signature +---- +func psHostUsers() (users [](github.com/shirou/gopsutil/v4/host).UserStat, err error) +---- + +`psHostUsers` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/host#Users[`github.com/shirou/gopsutil/v4/host.Users`^]. + +[id="fn_ps_hst_virt"] +===== `psHostPlatVirt` +[source,go] +.Function Signature +---- +func psHostVirt() (virtInfo [2]string, err error) +---- + +`psHostPlatVirt` wraps https://pkg.go.dev/github.com/shirou/gopsutil/v4/host#Virtualization[`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`. + +[id="fn_ps_ld"] +==== Load + +[id="fn_ps_ld_avg"] +===== `psLoadAvg` +[source,go] +.Function Signature +---- +func psLoadAvg() (avg *(github.com/shirou/gopsutil/v4/load).AvgStat, err error) +---- + +`psLoadAvg` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/load#Avg[`github.com/shirou/gopsutil/v4/load.Avg`^]. + +[id="fn_ps_ld_misc"] +===== `psLoadMisc` +[source,go] +.Function Signature +---- +func psLoadMisc() (misc *(github.com/shirou/gopsutil/v4/load).MiscStat, err error) +---- + +`psLoadMisc` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/load#Misc[`github.com/shirou/gopsutil/v4/load.Misc`^]. + +[id="fn_ps_mem"] +==== Memory + +[id="fn_ps_mem_exvmem"] +===== `psMemExVMem` +[source,go] +.Function Signature +---- +func psMemExVMem() (exVMem *(github.com/shirou/gopsutil/v4/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. + +* Linux: https://pkg.go.dev/github.com/shirou/gopsutil/v4/mem?GOOS=linux#ExVirtualMemory[`mem.ExVirtualMemory`^] +* Windows: https://pkg.go.dev/github.com/shirou/gopsutil/v4/mem?GOOS=windows#ExVirtualMemory[`mem.ExVirtualMemory`^] +==== + +This function wraps link:https://pkg.go.dev/github.com/shirou/gopsutil/v4/mem?GOOS=linux#NewExLinux[`github.com/shirou/gopsutil/v4/mem.NewExLinux`^].link:https://pkg.go.dev/github.com/shirou/gopsutil/v4/mem?GOOS=linux#ExLinux.VirtualMemory[`VirtualMemory`^] on Linux and +link:https://pkg.go.dev/github.com/shirou/gopsutil/v4/mem?GOOS=windows#NewExWindows[`github.com/shirou/gopsutil/v4/mem.NewExWindows`^].link:https://pkg.go.dev/github.com/shirou/gopsutil/v4/mem?GOOS=windows#ExWindows.VirtualMemory[`VirtualMemory`^] on Windows. + +[id="fn_ps_mem_swap"] +===== `psMemSwap` +[source,go] +.Function Signature +---- +func psMemSwap() (swap *(github.com/shirou/gopsutil/v4/mem).SwapMemoryStat, err error) +---- + +`psMemSwap` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/mem#SwapMemory[`github.com/shirou/gopsutil/v4/mem.SwapMemory`^]. + +[id="fn_ps_mem_swapdevs"] +===== `psMemSwapDevs` +[source,go] +.Function Signature +---- +func psMemSwapDevs() (swapDevs []*(github.com/shirou/gopsutil/v4/mem).SwapDevice, err error) +---- + +`psMemSwapDevs` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/mem#SwapDevices[`github.com/shirou/gopsutil/v4/mem.SwapDevices`^]. + +[id="fn_ps_mem_vmem"] +===== `psMemVMem` +[source,go] +.Function Signature +---- +func psMemVMem() (vmem *(github.com/shirou/gopsutil/v4/mem).VirtualMemoryStat, err error) +---- + +`psMemVMem` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/mem#VirtualMemory[`github.com/shirou/gopsutil/v4/mem.VirtualMemory`^]. + +[id="fn_ps_net"] +==== Network + +[id="fn_ps_net_conns"] +===== `psNetConns` +[source,go] +.Function Signature +---- +func psNetConns(kind string) (conns [](github.com/shirou/gopsutil/v4/net).ConnectionStat, err error) +---- + +`psNetConns` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/net#Connections[`github.com/shirou/gopsutil/v4/net.Connections`^]. + +[id="fn_ps_net_connsmax"] +===== `psNetConnsMax` +[source,go] +.Function Signature +---- +func psNetConnsMax(kind string, maxConn int) (conns [](github.com/shirou/gopsutil/v4/net).ConnectionStat, err error) +---- + +`psNetConnsMax` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/net#ConnectionsMax[`github.com/shirou/gopsutil/v4/net.ConnectionsMax`^]. + +[id="fn_ps_net_connspid"] +===== `psNetConnsPid` +[source,go] +.Function Signature +---- +func psNetConnsPid(kind string, pid int32) (conns [](github.com/shirou/gopsutil/v4/net).ConnectionStat, err error) +---- + +`psNetConnsPid` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/net#ConnectionsPid[`github.com/shirou/gopsutil/v4/net.ConnectionsPid`^]. + +[id="fn_ps_net_connspidmax"] +===== `psNetConnsPidMax` +[source,go] +.Function Signature +---- +func psNetConnsPidMax(kind string, pid int32, maxConn int) (conns [](github.com/shirou/gopsutil/v4/net).ConnectionStat, err error) +---- + +`psNetConnsPidMax` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/net#ConnectionsPidMax[`github.com/shirou/gopsutil/v4/net.ConnectionsPidMax`^]. + +[id="fn_ps_net_ct"] +===== `psNetCTStats` +[source,go] +.Function Signature +---- +func psNetCTStats(percCpu bool) (ctStats [](github.com/shirou/gopsutil/v4/net).ConntrackStat, err error) +---- + +`psNetCTStats` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/net#ConntrackStats[`github.com/shirou/gopsutil/v4/net.ConntrackStats`^]. + +[id="fn_ps_net_ctlist"] +===== `psNetCTStatList` +[source,go] +.Function Signature +---- +func psNetCTStatList() (ctStats *(github.com/shirou/gopsutil/v4/net).ConntrackStatList, err error) +---- + +`psNetCTStatList` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/net#ConntrackStatList[`github.com/shirou/gopsutil/v4/net.ConntrackStatList`^]. + +[id="fn_ps_net_fltcnt"] +===== `psNetFilterCnts` +[source,go] +.Function Signature +---- +func psNetFilterCnts() (filterCnts [](github.com/shirou/gopsutil/v4/net).FilterStat, err error) +---- + +`psNetFilterCnts` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/net#FilterCounters[`github.com/shirou/gopsutil/v4/net.FilterCounters`^]. + +[id="fn_ps_net_iocnts"] +===== `psNetIoCnts` +[source,go] +.Function Signature +---- +func psNetIoCnts(perNIC bool) (ioCnts [](github.com/shirou/gopsutil/v4/net).IOCountersStat, err error) +---- + +`psNetIoCnts` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/net#IOCounters[`github.com/shirou/gopsutil/v4/net.IOCounters`^]. + +[id="fn_ps_net_iocntsfl"] +===== `psNetIoCntsFile` +[source,go] +.Function Signature +---- +func psNetIoCntsFile(perNIC bool, filepath string) (ioCnts [](github.com/shirou/gopsutil/v4/net).IOCountersStat, err error) +---- + +`psNetIoCntsFile` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/net#IOCountersByFile[`github.com/shirou/gopsutil/v4/net.IOCountersByFile`^]. + +[id="fn_ps_net_ifaces"] +===== `psNetIfaces` +[source,go] +.Function Signature +---- +func psNetIfaces() (ioCnts [](github.com/shirou/gopsutil/v4/net).InterfaceStatList, err error) +---- + +`psNetIfaces` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/net#Interfaces[`github.com/shirou/gopsutil/v4/net.Interfaces`^]. + +[id="fn_ps_net_pids"] +===== `psNetPids` +[source,go] +.Function Signature +---- +func psNetPids() (pids []int32, err error) +---- + +`psNetPids` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/net#Pids[`github.com/shirou/gopsutil/v4/net.Pids`^]. + +[id="fn_ps_net_protocnts"] +===== `psNetProtoCnt` +[source,go] +.Function Signature +---- +func psNetProtoCnt(protos []string) (protoCnts [](github.com/shirou/gopsutil/v4/net).ProtoCountersStat, err error) +---- + +[WARNING] +==== +This only works properly on Linux currently per upstream. +==== + +`psNetProtoCnt` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/net#ProtoCounters[`github.com/shirou/gopsutil/v4/net.ProtoCounters`^]. + +[id="fn_ps_net_rev"] +===== `psNetRev` +[source,go] +.Function Signature +---- +func psNetRev(b []byte) (out []byte) +---- + +[WARNING] +==== +This function only exists on Linux. +==== + +`psNetRev` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/net?GOOS=linux#Reverse[`github.com/shirou/gopsutil/v4/net.Reverse`^]. + +[id="fn_ps_proc"] +==== Processes + +[id="fn_ps_procs_procs"] +===== `psProcs` +[source,go] +.Function Signature +---- +func psProcs(pid int32) (procs []*(github.com/shirou/gopsutil/v4/process).Process, err error) +---- + +`psProcs` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/process#Processes[`github.com/shirou/gopsutil/v4/proc.Processes`^]. + +[id="fn_ps_proc_new"] +===== `psProcNew` +[source,go] +.Function Signature +---- +func psProcNew(pid int32) (proc *(github.com/shirou/gopsutil/v4/process).Process, err error) +---- + +`psProcNew` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/process#NewProcess[`github.com/shirou/gopsutil/v4/proc.NewProcess`^]. + +[id="fn_ps_proc_pids"] +===== `psProcPids` +[source,go] +.Function Signature +---- +func psProcPids() (pids []int32, err error) +---- + +`psProcPids` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/process#Pids[`github.com/shirou/gopsutil/v4/proc.Pids`^]. + +[id="fn_ps_proc_pidxst"] +===== `psProcPidExists` +[source,go] +.Function Signature +---- +func psProcPidExists(pid int32) (exists bool, err error) +---- + +`psProcPidExists` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/process#PidExists[`github.com/shirou/gopsutil/v4/proc.PidExists`^]. + +[id="fn_ps_sns"] +==== Sensors/Thermals + +[id="fn_ps_sns_extemp"] +===== `psSensorExTemp` +[source,go] +.Function Signature +---- +func psSensorExTemp() (temps [](github.com/shirou/gopsutil/v4/sensors).ExTemperature, err error) +---- + +[WARNING] +==== +This function only exists on Linux. +==== + +`psSensorExTemp` wraps link:https://pkg.go.dev/github.com/shirou/gopsutil/v4/sensors?GOOS=linux#NewExLinux[`github.com/shirou/gopsutil/v4/sensors.NewExLinux`^].link:https://pkg.go.dev/github.com/shirou/gopsutil/v4/sensors?GOOS=linux#TemperatureWithContext[`github.com/shirou/gopsutil/v4/sensors.TemperatureWithContext`^]. + +[id="fn_ps_sns_temps"] +===== `psSensorTemps` +[source,go] +.Function Signature +---- +func psSensorTemps() (temps [](github.com/shirou/gopsutil/v4/sensors).TemperatureStat, err error) +---- + +`psSensorTemps` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/sensors#SensorsTemperatures[`github.com/shirou/gopsutil/v4/sensors.SensorsTemperatures`^]. + +[id="fn_ps_winsvc"] +==== Windows Services + +[WARNING] +==== +All of these functions are only available on Windows. +==== + +[id="fn_ps_winsvc_list"] +===== `psWinsvcList` +[source,go] +.Function Signature +---- +func psWinsvcList() (svcs [](github.com/shirou/gopsutil/v4/winservices).Service, err error) +---- + +[WARNING] +==== +This function is only available on Windows. +==== + +`psWinsvcList` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/winservices?GOOS=windows#ListServices[`github.com/shirou/gopsutil/v4/winservices.ListServices`^]. + +[id="fn_ps_winsvc_new"] +===== `psWinsvcNew` +[source,go] +.Function Signature +---- +func psWinsvcNew(svcName string) (svc *(github.com/shirou/gopsutil/v4/winservices).Service, err error) +---- + +[WARNING] +==== +This function is only available on Windows. +==== + +`psWinsvcNew` directly calls https://pkg.go.dev/github.com/shirou/gopsutil/v4/winservices?GOOS=windows#NewService[`github.com/shirou/gopsutil/v4/winservices.NewService`^]. + [id="fn_str"] === Strings [id="fn_str_extindent"] ==== `extIndent` +[source,go] +.Function Signature +---- +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. @@ -647,9 +1386,75 @@ Where: * ``: The string to use as the "indent character". This can be any string, such as `" "`, `"\t"`, `"."`, `"|"`, `"=="` etc. * ``: The text to be indented. Because it is the last argument, `extIndent` works with pipelined text as well. -[id="fn_dbg"] -=== Debugging +[id="fn_sys"] +=== System/Platform/Architecture -[id="fn_dbg_dump"] -==== `dump` -The `dump` function calls https://pkg.go.dev/github.com/davecgh/go-spew/spew#Sdump[the `Sdump` function^] from https://github.com/davecgh/go-spew[`go-spew`] (https://pkg.go.dev/github.com/davecgh/go-spew/spew[`github.com/davecgh/go-spew/spew`^]) for whatever object(s) is/are passed to it. +[id="fn_sys_arch"] +==== `sysArch` +[source,go] +.Function Signature +---- +func sysArch() (out string) +---- + +Returns the https://pkg.go.dev/runtime#GOARCH[`runtime.GOARCH`^] constant. + +[id="fn_sys_numcpu"] +==== `sysNumCpu` +[source,go] +.Function Signature +---- +func sysNumCpu() (cnt int) +---- + +`sysNumCpu` directly calls https://pkg.go.dev/runtime#NumCPU[`runtime.NumCPU`^]. + +[id="fn_sys_os"] +==== `sysOsName` +[source,go] +.Function Signature +---- +func sysOsNm() (out string) +---- + +Returns the https://pkg.go.dev/runtime#GOOS[`runtime.GOOS`^] constant. + +[id="fn_sys_rntm"] +==== `sysRuntime` +[source,go] +.Function Signature +---- +func sysRuntime() (out map[string]string) +---- + +This function returns a `map[string]string` of various information from the https://pkg.go.dev/runtime[`runtime` stdlib library^]. + +Specifically, the following are returned. + +[TIP] +==== +The value type is a direct link to the `runtime` documentation providing more detail about the associated value. + +Because all values are mapped as strings, they can be converted back to their native type via e.g. the https://masterminds.github.io/sprig/conversion.html[Sprig conversion functions^] if necessary. +==== + +.`sysRuntime` Values +[cols="^.^3m,^.^3",options="header"] +|=== +| Key | Value Type + +| compiler | https://pkg.go.dev/runtime#Compiler[string^] +| arch | https://pkg.go.dev/runtime#GOARCH[string^] +| os | https://pkg.go.dev/runtime#GOOS[string^] +| maxprocs | https://pkg.go.dev/runtime#GOMAXPROCS[int^] footnote:[For safety concerns, `sprigx` does not allow *setting* `GOMAXPROCS`, this value only contains the *current* `GOMAXPROCS` value.] +| cpu_cnt | https://pkg.go.dev/runtime#NumCPU[int^] +| num_cgo | https://pkg.go.dev/runtime#NumCgoCall[int^] +| num_go | https://pkg.go.dev/runtime#NumGoroutine[int^] +| go_ver | https://pkg.go.dev/runtime#Version[string^] +|=== + +As a convenience, some of these values also have their own dedicated functions as well: + +* <> +* <> +* <> diff --git a/tplx/sprigx/README.html b/tplx/sprigx/README.html index 551a4a6..60eeb29 100644 --- a/tplx/sprigx/README.html +++ b/tplx/sprigx/README.html @@ -559,7 +559,7 @@ pre.rouge .gs {
Brent Saner

-Last rendered 2026-01-28 09:20:19 -0500 +Last rendered 2026-01-29 19:01:34 -0500
Table of Contents
@@ -568,50 +568,149 @@ pre.rouge .gs {
  • 2. How do I Use SprigX?
  • 3. Functions @@ -801,7 +900,7 @@ var txtTpl *template.Template = template.
    • -

    and a function can even be explicitly overridden.

    +

    and a function can even be explicitly overridden.

    (show) @@ -853,40 +952,1681 @@ var txtTpl *template.Template = template.

    Expect this list to grow over time, and potentially more frequently than the sprigx functions.

    -
    -

    3.1. Operating System

    -
    -

    3.1.1. osHostname

    -

    osHostname simply wraps and returns the result of calling os.Hostname.

    +

    Each function includes its function signature to indicate what types of arguments/parameters it accepts, +what it returns, and if it may potentially return an error or not.

    +
    +
    +

    3.1. Debugging

    +
    +

    3.1.1. dump

    +
    +
    Function Signature
    +
    +
    func dump(a ...interface{}) (out string)
    +
    -

    As such, it comes with the same caveats - it’s possible for it to error, and it isn’t guaranteed to be an FQDN — it will be precisely/exactly whatever the kernel’s hostname is set as.

    +

    The dump function directly calls github.com/davecgh/go-spew/spew.Sdump +for whatever object(s) is/are passed to it.

    -

    3.2. System/Platform/Architecture

    +

    3.2. "Meta"/Template Helpers

    -

    3.2.1. sysArch

    +

    3.2.1. metaIsNil

    +
    +
    Function Signature
    +
    +
    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.

    +
    +
    +
    +

    3.2.2. Nop

    +
    +
    Function Signature
    +
    +
    func Nop(obj ...any) (s string)
    +
    +
    +
    +

    Nop is not actually a template function, but rather an exported Go function that one can use in +an override map to explicitly disable certain template 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.3. Operating System

    +
    +

    3.3.1. osFQDN

    +
    +
    Function Signature
    +
    +
    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. +To directly/predictably use os.Hostname, use osHostname.

    +
    +
    +
    +

    3.3.2. osGroupById

    +
    +
    Function Signature
    +
    +
    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.

    +
    +
    +
    +

    3.3.3. osGroupByName

    +
    +
    Function Signature
    +
    +
    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.

    +
    +
    +
    +

    3.3.4. osHost

    +
    +
    Function Signature
    +
    +
    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).

    +
    +
    +

    e.g.:

    +
    +
    +
    +
    {{- $fqdn := osFQDN -}}
+{{- $h := osHost -}}
+{{- $cmp := index ($fqdn | splitList ".") 0 -}}
+osHost {{ $h }} should be equal to first label of FQDN {{ $cmp }}.
    +
    +
    +
    + + + + + +
    +
    Tip
    +    		 +
    +

    The splitList function shown aboce is from the sprig string slice functions.

    +
    +
    +
    +
    +

    To (try to) get the FQDN, use osFQDN. +To directly use os.Hostname, use osHostname.

    +
    +
    +
    +

    3.3.5. osHostname

    +
    +
    Function Signature
    +
    +
    func osHostname() (out string, err error)
    +
    +
    +
    +

    osHostname directly calls os.Hostname.

    +
    +
    +
    +

    3.3.6. osIdState

    +
    +
    Function Signature
    +
    +
    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.

    +
    +
    +
    +
    +
    +

    3.3.7. osUser

    +
    +
    Function Signature
    +
    +
    func osUser() (u *user.User, err error)
    +
    +
    +
    +

    osUser returns the current runtime process' os/user.User.

    +
    +
    +

    It directly calls os/user.Current.

    +
    +
    +
    +

    3.3.8. osUserById

    +
    +
    Function Signature
    +
    +
    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.

    +
    +
    +
    +

    3.3.9. osUserByName

    +
    +
    Function Signature
    +
    +
    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.

    +
    +
    +
    +
    +

    3.4. Paths

    +
    +

    3.4.1. Generic

    +
    +

    These operate similar to the path stdlib library and use a fixed / path separator.

    +
    +
    +
    3.4.1.1. pathJoin
    +
    +
    Function Signature
    +
    +
    func pathJoin(elem ...string) (out string)
    +
    +
    +
    +

    pathJoin directly calls path.Join.

    +
    +
    + + + + + +
    +
    Warning
    +    		 +
    +

    If you are joining paths in a pipeline, you almost assuredly want pathPipeJoin or pathSlicePipeJoin instead +unless you are explicitly appending a pipeline result to a path.

    +
    +
    +
    +
    +
    +
    {{- pathJoin "a" "b" "c" }}
+{{- pathJoin "/" "a" "b" "c" }}
+{{- pathJoin "/a/b" "c" }}
    +
    +
    +
    +

    renders as:

    +
    +
    +
    +
    a/b/c
+/a/b/c
+/a/b/c
    +
    +
    +
    +
    +
    3.4.1.2. pathPipeJoin
    +
    +
    Function Signature
    +
    +
    func pathPipeJoin(elems ...string) (out string)
    +
    +
    +
    +

    pathPipeJoin operates like pathJoin with one deviation: the root/base path is expected to be last in the arguments.

    +
    +
    +

    This makes it much more suitable for use in template pipelines, as the previous value in a pipeline is passed in +as the last element to the next pipe function.

    +
    +
    +
    +
    {{- $myBase := "/a" -}}
+{{- pathPipeJoin "b" "c" "a" }}
+{{- pathPipeJoin "a" "b" "c" "/" }}
+{{- $myBase | pathPipeJoin "b" "c" }}
    +
    +
    +
    +

    renders as:

    +
    +
    +
    +
    a/b/c
+/a/b/c
+/a/b/c
    +
    +
    +
    +
    +
    3.4.1.3. pathSliceJoin
    +
    +
    Function Signature
    +
    +
    func pathSliceJoin(sl []string) (out string)
    +
    +
    +
    +

    pathSliceJoin joins a slice of path segment strings ([]string) instead of a variadic sequence of strings.

    +
    +
    + + + + + +
    +
    Tip
    +    		 +
    +

    The splitList function shown below is from the sprig string slice functions.

    +
    +
    +
    +
    +
    +
    {{- $myList := "a,b,c" | splitList "," -}}
+{{- $myList | pathSliceJoin }}
+{{- ("a,b,c" | splitList ",") | pathSliceJoin }}
+{{- ("/,a,b,c" | splitList ",") | pathSliceJoin }}
    +
    +
    +
    +

    renders as:

    +
    +
    +
    +
    a/b/c
+a/b/c
+/a/b/c
    +
    +
    +
    +
    +
    3.4.1.4. pathSlicePipeJoin
    +
    +
    Function Signature
    +
    +
    func pathSlicePipeJoin(sl []string, root string) (out string)
    +
    +
    +
    +

    pathSlicePipeJoin operates like pathPipeJoin 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 in that it then also accepts a slice of +path segments ([]string) to append to that base path.

    +
    +
    + + + + + +
    +
    Tip
    +    		 +
    +

    The splitList function shown below is from the sprig string slice functions.

    +
    +
    +
    +
    +
    +
    {{- $myBase := "/a" -}}
+{{- $myList := "b,c,d" | splitList "." -}}
+{{- pathSlicePipeJoin $myList $myBase }}
+{{- $myBase | pathSlicePipeJoin $myList }}
    +
    +
    +
    +

    renders as:

    +
    +
    +
    +
    /a/b/c
+/a/b/c
    +
    +
    +
    +
    +
    3.4.1.5. pathSubJoin
    +
    +
    Function Signature
    +
    +
    func pathSubJoin(root string, elems ...string) (out string)
    +
    +
    +
    +

    pathSubJoin operates like pathJoin but it expects an explicit root/base path.

    +
    +
    +

    The pipeline-friendly equivalent of this is pathPipeJoin.

    +
    +
    +
    +
    {{- pathSubJoin "/a/b" "c" }}
+{{- pathSubJoin "/" "a" "b" "c" }}
+{{- "c" | pathSubJoin "/" "a" "b" }}
    +
    +
    +
    +

    renders as:

    +
    +
    +
    +
    /a/b/c
+/a/b/c
+/a/b/c
    +
    +
    +
    +
    +
    +

    3.4.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. osPathJoin!

    +
    +
    +

    It is recommended to make use of sysOsName to conditionally format path bases/roots if needed.

    +
    +
    +
    +
    +
    3.4.2.1. osPathJoin
    +
    +
    Function Signature
    +
    +
    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 osPathPipeJoin or osPathSlicePipeJoin instead unless you are +explicitly appending a pipeline result to a path.

    +
    +
    +
    +
    +
    +
    {{- osPathJoin "a" "b" "c" }}
+{{- osPathJoin "/" "a" "b" "c" }}
+{{- osPathJoin "C:\\" "a" "b" "c" }}
+{{- osPathJoin "C:" "a" "b" "c" }}
    +
    +
    +
    +

    renders as:

    +
    + ++++ + + + + + + + + + + + + + + + + +
    OSResult

    Windows

    +
    +
    a\b\c
+\a\b\c
+\a\b\c
+C:\a\b\c
+C:a\b\c
    +
    +

    Others (e.g. Linux, macOS)

    +
    +
    a/b/c
+/a/b/c
+C:\/a/b/c
+C:/a/b/c
    +
    +
    +
    +
    +
    3.4.2.2. osPathPipeJoin
    +
    +
    Function Signature
    +
    +
    func osPathPipeJoin(elems ...string) (out string)
    +
    +
    +
    +

    osPathPipeJoin operates like pathPipeJoin (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.

    +
    +
    +
    +
    {{- $myBase := "/a" -}}
+{{- osPathPipeJoin "b" "c" "a" }}
+{{- osPathPipeJoin "a" "b" "c" "/" }}
+{{- $myBase | osPathPipeJoin "b" "c" }}
    +
    +
    +
    +

    renders as:

    +
    + ++++ + + + + + + + + + + + + + + + + +
    OSResult

    Windows

    +
    +
    a\b\c
+\a\b\c
+\a\b\c
    +
    +

    Others (e.g. Linux, macOS)

    +
    +
    a/b/c
+/a/b/c
+/a/b/c
    +
    +
    +
    +
    +
    3.4.2.3. osPathSep
    +
    +
    Function Signature
    +
    +
    func osPathSep() (out string)
    +
    +
    +
    +

    osPathSep returns the os.PathSeparator for this OS.

    +
    +
    +
    +
    {{- osPathSep }}
    +
    +
    +
    +

    renders as:

    +
    + ++++ + + + + + + + + + + + + + + + + +
    OSResult

    Windows

    +
    +
    \
    +
    +

    Others (e.g. Linux, macOS)

    +
    +
    /
    +
    +
    +
    +
    +
    3.4.2.4. osPathSliceJoin
    +
    +
    Function Signature
    +
    +
    func osPathSliceJoin(sl []string) (out string)
    +
    +
    +
    +

    osPathSliceJoin operates like pathSliceJoin but with OS-specific path separators.

    +
    +
    + + + + + +
    +
    Tip
    +    		 +
    +

    The splitList function shown below is from the sprig string slice functions.

    +
    +
    +
    +
    +
    +
    {{- $myList := "a,b,c" | splitList "," -}}
+{{- $myList | osPathSliceJoin }}
+{{- ("a,b,c" | splitList ",") | osPathSliceJoin }}
+{{- ("/,a,b,c" | splitList ",") | osPathSliceJoin }}
    +
    +
    +
    +

    renders as:

    +
    + ++++ + + + + + + + + + + + + + + + + +
    OSResult

    Windows

    +
    +
    a\b\c
+a\b\c
+\a\b\c
    +
    +

    Others (e.g. Linux, macOS)

    +
    +
    a/b/c
+a/b/c
+/a/b/c
    +
    +
    +
    +
    +
    3.4.2.5. osPathSlicePipeJoin
    +
    +
    Function Signature
    +
    +
    func osPathSlicePipeJoin(sl []string, root string) (out string)
    +
    +
    +
    +

    osPathSlicePipeJoin operates like pathSlicePipeJoin but with OS-specific separators.

    +
    +
    + + + + + +
    +
    Tip
    +    		 +
    +

    The splitList function shown below is from the sprig string slice functions.

    +
    +
    +
    +
    +
    +
    {{- $myBase := "/a" -}}
+{{- $myList := "b,c,d" | splitList "." -}}
+{{- osPathSlicePipeJoin $myList $myBase }}
+{{- $myBase | osPathSlicePipeJoin $myList }}
    +
    +
    +
    +

    renders as:

    +
    + ++++ + + + + + + + + + + + + + + + + +
    OSResult

    Windows

    +
    +
    \a\b\c\d
+\a\b\c\d
    +
    +

    Others (e.g. Linux, macOS)

    +
    +
    /a/b/c/d
+/a/b/c/d
    +
    +
    +
    +
    +
    3.4.2.6. osPathSubJoin
    +
    +
    Function Signature
    +
    +
    func osPathSubJoin(root string, elems ...string) (out string)
    +
    +
    +
    +

    osPathSubJoin operates like pathSubJoin but with OS-specific separators.

    +
    +
    +

    The pipeline-friendly equivalent of this is osPathPipeJoin.

    +
    +
    +
    +
    {{- osPathSubJoin "/a/b" "c" }}
+{{- osPathSubJoin "/" "a" "b" "c" }}
+{{- "c" | osPathSubJoin "/" "a" "b" }}
    +
    +
    +
    +

    renders as:

    +
    + ++++ + + + + + + + + + + + + + + + + +
    OSResult

    Windows

    +
    +
    \a\b\c
+\a\b\c
+\a\b\c
    +
    +

    Others (e.g. Linux, macOS)

    +
    +
    /a/b/c
+/a/b/c
+/a/b/c
    +
    +
    +
    +
    +
    +
    +

    3.5. PSUtils

    +
    +

    These are functions from github.com/shirou/gopsutil/v4 packages.

    +
    +
    +

    3.5.1. CPU/Processor

    +
    +
    3.5.1.1. psCpuCnts
    +
    +
    Function Signature
    +
    +
    func psCpuCnts(logical bool) (numCpu int, err error)
    +
    +
    +
    +

    psCpuCnts directly calls github.com/shirou/gopsutil/v4/cpu.Counts.

    +
    +
    +
    +
    3.5.1.2. psCpuInfo
    +
    +
    Function Signature
    +
    +
    func psCpuInfo() (cpuInfo [](github.com/shirou/gopsutil/v4/cpu).Info, err error)
    +
    +
    +
    +

    psCpuInfo directly calls github.com/shirou/gopsutil/v4/cpu.Info.

    +
    +
    +
    +
    3.5.1.3. psCpuPct
    +
    +
    Function Signature
    +
    +
    func psCpuPct(interval time.Duration, percpu bool) (pcts []float64, err error)
    +
    +
    +
    +

    psCpuPct directly calls github.com/shirou/gopsutil/v4/cpu.Percent.

    +
    +
    +
    +
    3.5.1.4. psCpuTimes
    +
    +
    Function Signature
    +
    +
    func psCpuTimes(percpu bool) (cpuTimes []TimesStat, err error)
    +
    +
    +
    +

    psCpuTimes directly calls github.com/shirou/gopsutil/v4/cpu.Times.

    +
    +
    +
    +
    +

    3.5.2. Disk

    +
    +
    3.5.2.1. psDiskIoCnts
    +
    +
    Function Signature
    +
    +
    func psDiskIoCnts(names ...string) (stats map[string]IOCountersStat, err error)
    +
    +
    +
    +

    psDiskIoCnts directly calls github.com/shirou/gopsutil/v4/disk.IOCounters.

    +
    +
    +
    +
    3.5.2.2. psDiskLabel
    +
    +
    Function Signature
    +
    +
    func psDiskLabel(name string) (label string, err error)
    +
    +
    +
    +

    psDiskLabel directly calls github.com/shirou/gopsutil/v4/disk.Label.

    +
    +
    +
    +
    3.5.2.3. psDiskParts
    +
    +
    Function Signature
    +
    +
    func psDiskParts(all bool) (parts [](github.com/shirou/gopsutil/v4/disk).PartitionStat, err error)
    +
    +
    +
    +

    psDiskParts directly calls github.com/shirou/gopsutil/v4/disk.Partitions.

    +
    +
    +
    +
    3.5.2.4. psDiskSerial
    +
    +
    Function Signature
    +
    +
    func psDiskSerial(name string) (serial string, err error)
    +
    +
    +
    +

    psDiskSerial directly calls github.com/shirou/gopsutil/v4/disk.SerialNumber.

    +
    +
    +
    +
    3.5.2.5. psDiskUsage
    +
    +
    Function Signature
    +
    +
    func psDiskUsage(path string) (usage *(github.com/shirou/gopsutil/v4/disk).UsageStat, err error)
    +
    +
    +
    +

    psDiskUsage directly calls github.com/shirou/gopsutil/v4/disk.Usage.

    +
    +
    +
    +
    +

    3.5.3. Host

    +
    +
    3.5.3.1. psHostBoot
    +
    +
    Function Signature
    +
    +
    func psHostBoot() (bootEpoch uint64, err error)
    +
    +
    +
    +

    psHostBoot directly calls github.com/shirou/gopsutil/v4/host.BootTime.

    +
    +
    +
    +
    3.5.3.2. psHostId
    +
    +
    Function Signature
    +
    +
    func psHostId() (hostId string, err error)
    +
    +
    +
    +

    psHostId directly calls github.com/shirou/gopsutil/v4/host.HostID.

    +
    +
    +
    +
    3.5.3.3. psHostInfo
    +
    +
    Function Signature
    +
    +
    func psHostInfo() (info *(github.com/shirou/gopsutil/v4/host).InfoStat, err error)
    +
    +
    +
    +

    psHostInfo directly calls github.com/shirou/gopsutil/v4/host.Info.

    +
    +
    +
    +
    3.5.3.4. psHostKernArch
    +
    +
    Function Signature
    +
    +
    func psHostKernArch() (arch string, err error)
    +
    +
    +
    +

    psHostKernArch directly calls github.com/shirou/gopsutil/v4/host.KernelArch.

    +
    +
    +
    +
    3.5.3.5. psHostKernVer
    +
    +
    Function Signature
    +
    +
    func psHostKernVer() (ver string, err error)
    +
    +
    +
    +

    psHostKernVer directly calls github.com/shirou/gopsutil/v4/host.KernelVersion.

    +
    +
    +
    +
    3.5.3.6. psHostPlatInfo
    +
    +
    Function Signature
    +
    +
    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.

    +
    +
    +
    +
    3.5.3.7. psHostPlatUptime
    +
    +
    Function Signature
    +
    +
    func psHostPlatUptime() (uptimeSecs uint64, err error)
    +
    +
    +
    +

    psHostPlatUptime directly calls github.com/shirou/gopsutil/v4/host.Uptime.

    +
    +
    +
    +
    3.5.3.8. psHostUsers
    +
    +
    Function Signature
    +
    +
    func psHostUsers() (users [](github.com/shirou/gopsutil/v4/host).UserStat, err error)
    +
    +
    +
    +

    psHostUsers directly calls github.com/shirou/gopsutil/v4/host.Users.

    +
    +
    +
    +
    3.5.3.9. psHostPlatVirt
    +
    +
    Function Signature
    +
    +
    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.

    +
    +
    +
    +
    +

    3.5.4. Load

    +
    +
    3.5.4.1. psLoadAvg
    +
    +
    Function Signature
    +
    +
    func psLoadAvg() (avg *(github.com/shirou/gopsutil/v4/load).AvgStat, err error)
    +
    +
    +
    +

    psLoadAvg directly calls github.com/shirou/gopsutil/v4/load.Avg.

    +
    +
    +
    +
    3.5.4.2. psLoadMisc
    +
    +
    Function Signature
    +
    +
    func psLoadMisc() (misc *(github.com/shirou/gopsutil/v4/load).MiscStat, err error)
    +
    +
    +
    +

    psLoadMisc directly calls github.com/shirou/gopsutil/v4/load.Misc.

    +
    +
    +
    +
    +

    3.5.5. Memory

    +
    +
    3.5.5.1. psMemExVMem
    +
    +
    Function Signature
    +
    +
    func psMemExVMem() (exVMem *(github.com/shirou/gopsutil/v4/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 on Linux and +github.com/shirou/gopsutil/v4/mem.NewExWindows.VirtualMemory on Windows.

    +
    +
    +
    +
    3.5.5.2. psMemSwap
    +
    +
    Function Signature
    +
    +
    func psMemSwap() (swap *(github.com/shirou/gopsutil/v4/mem).SwapMemoryStat, err error)
    +
    +
    +
    +

    psMemSwap directly calls github.com/shirou/gopsutil/v4/mem.SwapMemory.

    +
    +
    +
    +
    3.5.5.3. psMemSwapDevs
    +
    +
    Function Signature
    +
    +
    func psMemSwapDevs() (swapDevs []*(github.com/shirou/gopsutil/v4/mem).SwapDevice, err error)
    +
    +
    +
    +

    psMemSwapDevs directly calls github.com/shirou/gopsutil/v4/mem.SwapDevices.

    +
    +
    +
    +
    3.5.5.4. psMemVMem
    +
    +
    Function Signature
    +
    +
    func psMemVMem() (vmem *(github.com/shirou/gopsutil/v4/mem).VirtualMemoryStat, err error)
    +
    +
    +
    +

    psMemVMem directly calls github.com/shirou/gopsutil/v4/mem.VirtualMemory.

    +
    +
    +
    +
    +

    3.5.6. Network

    +
    +
    3.5.6.1. psNetConns
    +
    +
    Function Signature
    +
    +
    func psNetConns(kind string) (conns [](github.com/shirou/gopsutil/v4/net).ConnectionStat, err error)
    +
    +
    +
    +

    psNetConns directly calls github.com/shirou/gopsutil/v4/net.Connections.

    +
    +
    +
    +
    3.5.6.2. psNetConnsMax
    +
    +
    Function Signature
    +
    +
    func psNetConnsMax(kind string, maxConn int) (conns [](github.com/shirou/gopsutil/v4/net).ConnectionStat, err error)
    +
    +
    +
    +

    psNetConnsMax directly calls github.com/shirou/gopsutil/v4/net.ConnectionsMax.

    +
    +
    +
    +
    3.5.6.3. psNetConnsPid
    +
    +
    Function Signature
    +
    +
    func psNetConnsPid(kind string, pid int32) (conns [](github.com/shirou/gopsutil/v4/net).ConnectionStat, err error)
    +
    +
    +
    +

    psNetConnsPid directly calls github.com/shirou/gopsutil/v4/net.ConnectionsPid.

    +
    +
    +
    +
    3.5.6.4. psNetConnsPidMax
    +
    +
    Function Signature
    +
    +
    func psNetConnsPidMax(kind string, pid int32, maxConn int) (conns [](github.com/shirou/gopsutil/v4/net).ConnectionStat, err error)
    +
    +
    +
    +

    psNetConnsPidMax directly calls github.com/shirou/gopsutil/v4/net.ConnectionsPidMax.

    +
    +
    +
    +
    3.5.6.5. psNetCTStats
    +
    +
    Function Signature
    +
    +
    func psNetCTStats(percCpu bool) (ctStats [](github.com/shirou/gopsutil/v4/net).ConntrackStat, err error)
    +
    +
    +
    +

    psNetCTStats directly calls github.com/shirou/gopsutil/v4/net.ConntrackStats.

    +
    +
    +
    +
    3.5.6.6. psNetCTStatList
    +
    +
    Function Signature
    +
    +
    func psNetCTStatList() (ctStats *(github.com/shirou/gopsutil/v4/net).ConntrackStatList, err error)
    +
    +
    +
    +

    psNetCTStatList directly calls github.com/shirou/gopsutil/v4/net.ConntrackStatList.

    +
    +
    +
    +
    3.5.6.7. psNetFilterCnts
    +
    +
    Function Signature
    +
    +
    func psNetFilterCnts() (filterCnts [](github.com/shirou/gopsutil/v4/net).FilterStat, err error)
    +
    +
    +
    +

    psNetFilterCnts directly calls github.com/shirou/gopsutil/v4/net.FilterCounters.

    +
    +
    +
    +
    3.5.6.8. psNetIoCnts
    +
    +
    Function Signature
    +
    +
    func psNetIoCnts(perNIC bool) (ioCnts [](github.com/shirou/gopsutil/v4/net).IOCountersStat, err error)
    +
    +
    +
    +

    psNetIoCnts directly calls github.com/shirou/gopsutil/v4/net.IOCounters.

    +
    +
    +
    +
    3.5.6.9. psNetIoCntsFile
    +
    +
    Function Signature
    +
    +
    func psNetIoCntsFile(perNIC bool, filepath string) (ioCnts [](github.com/shirou/gopsutil/v4/net).IOCountersStat, err error)
    +
    +
    +
    +

    psNetIoCntsFile directly calls github.com/shirou/gopsutil/v4/net.IOCountersByFile.

    +
    +
    +
    +
    3.5.6.10. psNetIfaces
    +
    +
    Function Signature
    +
    +
    func psNetIfaces() (ioCnts [](github.com/shirou/gopsutil/v4/net).InterfaceStatList, err error)
    +
    +
    +
    +

    psNetIfaces directly calls github.com/shirou/gopsutil/v4/net.Interfaces.

    +
    +
    +
    +
    3.5.6.11. psNetPids
    +
    +
    Function Signature
    +
    +
    func psNetPids() (pids []int32, err error)
    +
    +
    +
    +

    psNetPids directly calls github.com/shirou/gopsutil/v4/net.Pids.

    +
    +
    +
    +
    3.5.6.12. psNetProtoCnt
    +
    +
    Function Signature
    +
    +
    func psNetProtoCnt(protos []string) (protoCnts [](github.com/shirou/gopsutil/v4/net).ProtoCountersStat, err error)
    +
    +
    +
    + + + + + +
    +
    Warning
    +    		 +
    +

    This only works properly on Linux currently per upstream.

    +
    +
    +
    +
    +

    psNetProtoCnt directly calls github.com/shirou/gopsutil/v4/net.ProtoCounters.

    +
    +
    +
    +
    3.5.6.13. psNetRev
    +
    +
    Function Signature
    +
    +
    func psNetRev(b []byte) (out []byte)
    +
    +
    +
    + + + + + +
    +
    Warning
    +    		 +
    +

    This function only exists on Linux.

    +
    +
    +
    +
    +

    psNetRev directly calls github.com/shirou/gopsutil/v4/net.Reverse.

    +
    +
    +
    +
    +

    3.5.7. Processes

    +
    +
    3.5.7.1. psProcs
    +
    +
    Function Signature
    +
    +
    func psProcs(pid int32) (procs []*(github.com/shirou/gopsutil/v4/process).Process, err error)
    +
    +
    +
    +

    psProcs directly calls github.com/shirou/gopsutil/v4/proc.Processes.

    +
    +
    +
    +
    3.5.7.2. psProcNew
    +
    +
    Function Signature
    +
    +
    func psProcNew(pid int32) (proc *(github.com/shirou/gopsutil/v4/process).Process, err error)
    +
    +
    +
    +

    psProcNew directly calls github.com/shirou/gopsutil/v4/proc.NewProcess.

    +
    +
    +
    +
    3.5.7.3. psProcPids
    +
    +
    Function Signature
    +
    +
    func psProcPids() (pids []int32, err error)
    +
    +
    +
    +

    psProcPids directly calls github.com/shirou/gopsutil/v4/proc.Pids.

    +
    +
    +
    +
    3.5.7.4. psProcPidExists
    +
    +
    Function Signature
    +
    +
    func psProcPidExists(pid int32) (exists bool, err error)
    +
    +
    +
    +

    psProcPidExists directly calls github.com/shirou/gopsutil/v4/proc.PidExists.

    +
    +
    +
    +
    +

    3.5.8. Sensors/Thermals

    +
    +
    3.5.8.1. psSensorExTemp
    +
    +
    Function Signature
    +
    +
    func psSensorExTemp() (temps [](github.com/shirou/gopsutil/v4/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.

    +
    +
    +
    +
    3.5.8.2. psSensorTemps
    +
    +
    Function Signature
    +
    +
    func psSensorTemps() (temps [](github.com/shirou/gopsutil/v4/sensors).TemperatureStat, err error)
    +
    +
    +
    +

    psSensorTemps directly calls github.com/shirou/gopsutil/v4/sensors.SensorsTemperatures.

    +
    +
    +
    +
    +

    3.5.9. Windows Services

    +
    + + + + + +
    +
    Warning
    +    		 +
    +

    All of these functions are only available on Windows.

    +
    +
    +
    +
    +
    3.5.9.1. psWinsvcList
    +
    +
    Function Signature
    +
    +
    func psWinsvcList() (svcs [](github.com/shirou/gopsutil/v4/winservices).Service, err error)
    +
    +
    +
    + + + + + +
    +
    Warning
    +    		 +
    +

    This function is only available on Windows.

    +
    +
    +
    +
    +

    psWinsvcList directly calls github.com/shirou/gopsutil/v4/winservices.ListServices.

    +
    +
    +
    +
    3.5.9.2. psWinsvcNew
    +
    +
    Function Signature
    +
    +
    func psWinsvcNew(svcName string) (svc *(github.com/shirou/gopsutil/v4/winservices).Service, err error)
    +
    +
    +
    + + + + + +
    +
    Warning
    +    		 +
    +

    This function is only available on Windows.

    +
    +
    +
    +
    +

    psWinsvcNew directly calls github.com/shirou/gopsutil/v4/winservices.NewService.

    +
    +
    +
    +
    +
    +

    3.6. Strings

    +
    +

    3.6.1. extIndent

    +
    +
    Function Signature
    +
    +
    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 <indentString> is set to \n and <levels> is always set to 1, this function can even be used to doubelspace text!

    +
    +
    +
    +
    +

    It has quite a few arguments, however:

    +
    +
    +
    +
    {{ extIndent <levels> <skipFirst> <skipEmpty> <skipWhitespace> <indentString> <input> }}
    +
    +
    +
    +

    Where:

    +
    +
    +
      +
    • +

      <levels>: The level of indentation for the text. If less than or equal to 0, extIndent just returns <input> as-is and NO-OPs otherwise.

      +
      • +
    • +

      <skipFirst>: If true, skip indenting the first line. This is particularly handy if you like to visually align your function calls in your templates.

      +
      • +
    • +

      <skipEmpty>: If true, do not add an indent to empty lines (where an "empty line" means "only has a linebreak").

      +
      • +
    • +

      <skipWhitespace>: If true, do not add an indent to lines that only consist of whitespace (spaces, tabs, etc.) and a linebreak.

      +
      • +
    • +

      <indentString>: The string to use as the "indent character". This can be any string, such as " ", "\t", ".", "|", "==" etc.

      +
      • +
    • +

      <input>: The text to be indented. Because it is the last argument, extIndent works with pipelined text as well.

      +
      • +
    +
    +
    +
    +
    +

    3.7. System/Platform/Architecture

    +
    +

    3.7.1. sysArch

    +
    +
    Function Signature
    +
    +
    func sysArch() (out string)
    +
    +

    Returns the runtime.GOARCH constant.

    -

    3.2.2. sysNumCpu

    +

    3.7.2. sysNumCpu

    +
    +
    Function Signature
    +
    +
    func sysNumCpu() (cnt int)
    +
    +
    -

    Returns the value from runtime.NumCPU.

    +

    sysNumCpu directly calls runtime.NumCPU.

    -

    3.2.3. sysOsName

    +

    3.7.3. sysOsName

    +
    +
    Function Signature
    +
    +
    func sysOsNm() (out string)
    +
    +

    Returns the runtime.GOOS constant.

    -

    3.2.4. sysRuntime

    +

    3.7.4. sysRuntime

    +
    +
    Function Signature
    +
    +
    func sysRuntime() (out map[string]string)
    +
    +

    This function returns a map[string]string of various information from the runtime stdlib library.

    @@ -975,618 +2715,6 @@ var txtTpl *template.Template = template.
    -
    -

    3.3. Paths

    -
    -

    3.3.1. Generic

    -
    -

    These operate similar to the path stdlib library and use a fixed / path separator.

    -
    -
    -
    3.3.1.1. pathJoin
    -
    -

    pathJoin operates exactly like path.Join in stdlib.

    -
    -
    - - - - - -
    -
    Warning
    -    		 -
    -

    If you are joining paths in a pipeline, you almost assuredly want pathPipeJoin or pathSlicePipeJoin instead unless you are explicitly appending a pipeline result to a path.

    -
    -
    -
    -
    -
    -
    {{- pathJoin "a" "b" "c" }}
-{{- pathJoin "/" "a" "b" "c" }}
-{{- pathJoin "/a/b" "c" }}
    -
    -
    -
    -

    renders as:

    -
    -
    -
    -
    a/b/c
-/a/b/c
-/a/b/c
    -
    -
    -
    -
    -
    3.3.1.2. pathPipeJoin
    -
    -

    pathPipeJoin operates like pathJoin with one deviation: the root/base path is expected to be last in the arguments.

    -
    -
    -

    This makes it much more suitable for use in template pipelines, as the previous value in a pipeline is passed in as the last element to the next pipe function.

    -
    -
    -
    -
    {{- $myBase := "/a" -}}
-{{- pathPipeJoin "b" "c" "a" }}
-{{- pathPipeJoin "a" "b" "c" "/" }}
-{{- $myBase | pathPipeJoin "b" "c" }}
    -
    -
    -
    -

    renders as:

    -
    -
    -
    -
    a/b/c
-/a/b/c
-/a/b/c
    -
    -
    -
    -
    -
    3.3.1.3. pathSliceJoin
    -
    -

    pathSliceJoin joins a slice of path segment strings ([]string) instead of a variadic sequence of strings.

    -
    -
    - - - - - -
    -
    Tip
    -    		 -
    -

    The splitList function shown below is from the sprig string slice functions.

    -
    -
    -
    -
    -
    -
    {{- $myList := "a,b,c" | splitList "," -}}
-{{- $myList | pathSliceJoin }}
-{{- ("a,b,c" | splitList ",") | pathSliceJoin }}
-{{- ("/,a,b,c" | splitList ",") | pathSliceJoin }}
    -
    -
    -
    -

    renders as:

    -
    -
    -
    -
    a/b/c
-a/b/c
-/a/b/c
    -
    -
    -
    -
    -
    3.3.1.4. pathSlicePipeJoin
    -
    -

    pathSlicePipeJoin operates like pathPipeJoin 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 in that it then also accepts a slice of path segments ([]string) to append to that base path.

    -
    -
    - - - - - -
    -
    Tip
    -    		 -
    -

    The splitList function shown below is from the sprig string slice functions.

    -
    -
    -
    -
    -
    -
    {{- $myBase := "/a" -}}
-{{- $myList := "b,c,d" | splitList "." -}}
-{{- pathSlicePipeJoin $myList $myBase }}
-{{- $myBase | pathSlicePipeJoin $myList }}
    -
    -
    -
    -

    renders as:

    -
    -
    -
    -
    /a/b/c
-/a/b/c
    -
    -
    -
    -
    -
    3.3.1.5. pathSubJoin
    -
    -

    pathSubJoin operates like pathJoin but it expects an explicit root/base path.

    -
    -
    -

    The pipeline-friendly equivalent of this is pathPipeJoin.

    -
    -
    -
    -
    {{- pathSubJoin "/a/b" "c" }}
-{{- pathSubJoin "/" "a" "b" "c" }}
-{{- "c" | pathSubJoin "/" "a" "b" }}
    -
    -
    -
    -

    renders as:

    -
    -
    -
    -
    /a/b/c
-/a/b/c
-/a/b/c
    -
    -
    -
    -
    -
    -

    3.3.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. osPathJoin!

    -
    -
    -

    It is recommended to make use of sysOsName to conditionally format path bases/roots if needed.

    -
    -
    -
    -
    -
    3.3.2.1. osPathJoin
    -
    -

    osPathJoin operates exactly like path/filepath.Join in stdlib.

    -
    -
    - - - - - -
    -
    Warning
    -    		 -
    -

    If you are joining paths in a pipeline, you almost assuredly want osPathPipeJoin or osPathSlicePipeJoin instead unless you are explicitly appending a pipeline result to a path.

    -
    -
    -
    -
    -
    -
    {{- osPathJoin "a" "b" "c" }}
-{{- osPathJoin "/" "a" "b" "c" }}
-{{- osPathJoin "C:\\" "a" "b" "c" }}
-{{- osPathJoin "C:" "a" "b" "c" }}
    -
    -
    -
    -

    renders as:

    -
    - ---- - - - - - - - - - - - - - - - - -
    OSResult

    Windows

    -
    -
    a\b\c
-\a\b\c
-\a\b\c
-C:\a\b\c
-C:a\b\c
    -
    -

    Others (e.g. Linux, macOS)

    -
    -
    a/b/c
-/a/b/c
-C:\/a/b/c
-C:/a/b/c
    -
    -
    -
    -
    -
    3.3.2.2. osPathPipeJoin
    -
    -

    osPathPipeJoin operates like pathPipeJoin (except using OS-specific path separators).

    -
    -
    -

    This makes it much more suitable for use in template pipelines, as the previous value in a pipeline is passed in as the last element to the next pipe function.

    -
    -
    -
    -
    {{- $myBase := "/a" -}}
-{{- osPathPipeJoin "b" "c" "a" }}
-{{- osPathPipeJoin "a" "b" "c" "/" }}
-{{- $myBase | osPathPipeJoin "b" "c" }}
    -
    -
    -
    -

    renders as:

    -
    - ---- - - - - - - - - - - - - - - - - -
    OSResult

    Windows

    -
    -
    a\b\c
-\a\b\c
-\a\b\c
    -
    -

    Others (e.g. Linux, macOS)

    -
    -
    a/b/c
-/a/b/c
-/a/b/c
    -
    -
    -
    -
    -
    3.3.2.3. osPathSep
    -
    -

    osPathSep returns the os.PathSeparator for this OS.

    -
    -
    -
    -
    {{- osPathSep }}
    -
    -
    -
    -

    renders as:

    -
    - ---- - - - - - - - - - - - - - - - - -
    OSResult

    Windows

    -
    -
    \
    -
    -

    Others (e.g. Linux, macOS)

    -
    -
    /
    -
    -
    -
    -
    -
    3.3.2.4. osPathSliceJoin
    -
    -

    osPathSliceJoin operates like pathSliceJoin but with OS-specific path separators.

    -
    -
    - - - - - -
    -
    Tip
    -    		 -
    -

    The splitList function shown below is from the sprig string slice functions.

    -
    -
    -
    -
    -
    -
    {{- $myList := "a,b,c" | splitList "," -}}
-{{- $myList | osPathSliceJoin }}
-{{- ("a,b,c" | splitList ",") | osPathSliceJoin }}
-{{- ("/,a,b,c" | splitList ",") | osPathSliceJoin }}
    -
    -
    -
    -

    renders as:

    -
    - ---- - - - - - - - - - - - - - - - - -
    OSResult

    Windows

    -
    -
    a\b\c
-a\b\c
-\a\b\c
    -
    -

    Others (e.g. Linux, macOS)

    -
    -
    a/b/c
-a/b/c
-/a/b/c
    -
    -
    -
    -
    -
    3.3.2.5. osPathSlicePipeJoin
    -
    -

    osPathSlicePipeJoin operates like pathSlicePipeJoin but with OS-specific separators.

    -
    -
    - - - - - -
    -
    Tip
    -    		 -
    -

    The splitList function shown below is from the sprig string slice functions.

    -
    -
    -
    -
    -
    -
    {{- $myBase := "/a" -}}
-{{- $myList := "b,c,d" | splitList "." -}}
-{{- osPathSlicePipeJoin $myList $myBase }}
-{{- $myBase | osPathSlicePipeJoin $myList }}
    -
    -
    -
    -

    renders as:

    -
    - ---- - - - - - - - - - - - - - - - - -
    OSResult

    Windows

    -
    -
    \a\b\c\d
-\a\b\c\d
    -
    -

    Others (e.g. Linux, macOS)

    -
    -
    /a/b/c/d
-/a/b/c/d
    -
    -
    -
    -
    -
    3.3.2.6. osPathSubJoin
    -
    -

    osPathSubJoin operates like pathSubJoin but with OS-specific separators.

    -
    -
    -

    The pipeline-friendly equivalent of this is osPathPipeJoin.

    -
    -
    -
    -
    {{- osPathSubJoin "/a/b" "c" }}
-{{- osPathSubJoin "/" "a" "b" "c" }}
-{{- "c" | osPathSubJoin "/" "a" "b" }}
    -
    -
    -
    -

    renders as:

    -
    - ---- - - - - - - - - - - - - - - - - -
    OSResult

    Windows

    -
    -
    \a\b\c
-\a\b\c
-\a\b\c
    -
    -

    Others (e.g. Linux, macOS)

    -
    -
    /a/b/c
-/a/b/c
-/a/b/c
    -
    -
    -
    -
    -
    -
    -

    3.4. Strings

    -
    -

    3.4.1. extIndent

    -
    -

    extIndent allows for a MUCH more flexible indenter than the sprig indent function.

    -
    -
    -

    It works with both Windows (\r\n) and POSIX (\n) linebreaks.

    -
    -
    - - - - - -
    -
    Tip
    -    		 -
    -

    If <indentString> is set to \n and <levels> is always set to 1, this function can even be used to doubelspace text!

    -
    -
    -
    -
    -

    It has quite a few arguments, however:

    -
    -
    -
    -
    {{ extIndent <levels> <skipFirst> <skipEmpty> <skipWhitespace> <indentString> <input> }}
    -
    -
    -
    -

    Where:

    -
    -
    -
      -
    • -

      <levels>: The level of indentation for the text. If less than or equal to 0, extIndent just returns <input> as-is and NO-OPs otherwise.

      -
      • -
    • -

      <skipFirst>: If true, skip indenting the first line. This is particularly handy if you like to visually align your function calls in your templates.

      -
      • -
    • -

      <skipEmpty>: If true, do not add an indent to empty lines (where an "empty line" means "only has a linebreak").

      -
      • -
    • -

      <skipWhitespace>: If true, do not add an indent to lines that only consist of whitespace (spaces, tabs, etc.) and a linebreak.

      -
      • -
    • -

      <indentString>: The string to use as the "indent character". This can be any string, such as " ", "\t", ".", "|", "==" etc.

      -
      • -
    • -

      <input>: The text to be indented. Because it is the last argument, extIndent works with pipelined text as well.

      -
      • -
    -
    -
    -
    -
    -

    3.5. Debugging

    -
    -

    3.5.1. dump

    -
    -

    The dump function calls the Sdump function from go-spew (github.com/davecgh/go-spew/spew) for whatever object(s) is/are passed to it.

    -
    -
    -
    @@ -1598,7 +2726,7 @@ a/b/c diff --git a/tplx/sprigx/README.md b/tplx/sprigx/README.md deleted file mode 100644 index fd7effd..0000000 --- a/tplx/sprigx/README.md +++ /dev/null @@ -1,699 +0,0 @@ -# What is SprigX? - -SprigX are extensions to [the `sprig` -library](https://masterminds.github.io/sprig/) ([Go -docs](https://pkg.go.dev/github.com/Masterminds/sprig/v3)). - -They provide functions that offer more enriched use cases and -domain-specific data. - -If you are reading this README on the Go Module Directory documentation -() or the directory -landing page -(), -it may not render correctly. - -Be sure to view it at properly via [the AsciiDoc -rendering](https://git.r00t2.io/r00t2/go_goutils/src/branch/master/tplx/sprigx/README.adoc) -or by downloading and viewing the [HTML -version](https://git.r00t2.io/r00t2/go_goutils/raw/branch/master/tplx/sprigx/README.html). - -# How do I Use SprigX? - -The same way you would `sprig`! - - 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. - - package main - - import ( - "text/template" - - "github.com/Masterminds/sprig/v3" - "r00t2.io/goutils/tplx/sprigx" - ) - - var txtTpl *template.Template = template. - New(""). - Funcs( - sprigx.TxtFuncMap(), - ). - Funcs( - sprig.TxtFuncMap(), - ) - // Or: - /* - var txtTpl *template.Template = template. - New(""). - Funcs( - sprig.TxtFuncMap(), - ). - Funcs( - sprigx.TxtFuncMap(), - ) - */ - -If a `