r00t2/go_goutils
1
0
Fork 0
Code Issues Pull Requests Projects Releases Activity
Files
07e0e587fac49d82f0be6d2ca9581d31c8845041
go_goutils/tplx/sprigx/README.adoc
brent saner 07e0e587fa v1.16.4 
ADDED:
* math, time functions to tplx/sprigx
FIXED:
* logging not initializing properly on some BSDs
2026-01-30 06:35:23 -05:00

45 KiB
Raw Blame History

SprigX

Table of Contents

1. What is SprigX?

SprigX is a suite of extensions to the sprig library (Go docs).

They provide functions that offer more enriched use cases and domain-specific data.

Tip

If you are reading this README on the Go Module Directory documentation (https://pkg.go.dev/r00t2.io/goutils/tplx/sprigx) or the directory landing page (https://git.r00t2.io/r00t2/go_goutils/src/branch/master/tplx/sprigx), it may not render correctly.

Be sure to view it at properly via the AsciiDoc rendering or by downloading and viewing the HTML version.

2. How do I Use SprigX?

The same way you would sprig!

Like this. 
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. 
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 and/or sprigx.CombinedHtmlFuncMap functions.

If a <template>.FuncMap is added via .Funcs() after template parsing, it will override any functions of the same name of a <template>.FuncMap before parsing.

For example, if both sprig and sprigx provide a function foo:

this will use foo from sprigx

(show) 
package main

import (
	"text/template"

	"github.com/Masterminds/sprig/v3"
	"r00t2.io/goutils/tplx/sprigx"
)

const (
	myTpl string = `{{ "This is an example template string." | foo }}`
)

var (
	tpl *template.Template = template.Must(
					template.
						New("").
						Funcs(sprig.TxtFuncMap()).
						Parse(myTpl),
				).
				Funcs(sprigx.TxtFuncMap())
)

whereas this will use foo from sprig

(show) 
package main

import (
	"text/template"

	"github.com/Masterminds/sprig/v3"
	"r00t2.io/goutils/tplx/sprigx"
)

const (
	myTpl string = `{{ "This is an example template string." | foo }}`
)

var (
	tpl *template.Template = template.Must(
					template.
						New("").
						Funcs(sprigx.TxtFuncMap()).
						Parse(myTpl),
					).
					Funcs(sprig.TxtFuncMap())
)

and a function can even be explicitly overridden.

(show)

This would override a function foo and foo2 in sprigx from foo and foo2 from sprig, but leave all other sprig functions untouched.

package main

import (
	"text/template"

	"github.com/Masterminds/sprig/v3"
	"r00t2.io/goutils/tplx/sprigx"
)

const (
	myTpl string = `{{ "This is an example template string." | foo }}`
)

var (
	overrideFuncs template.FuncMap = sprig.TxtFuncMap()
	tpl *template.Template = template.Must(
					template.
						New("").
						Funcs(sprigx.TxtFuncMap()).
						Parse(myTpl),
					).
					Funcs(
						template.FuncMap(
							map[string]any{
								"foo": overrideFuncs["foo"],
								"foo2": overrideFuncs["foo2"],
							},
						),
					)
)

3. Library Functions

These are generally intended to be used outside the template in the actual Go code.

3.1. CombinedFuncMap

Function Signature
func CombinedFuncMap(preferSprigX bool) (fmap map[string]any)

This function returns a generic function map (like FuncMap) 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 or CombinedHtmlFuncMap instead, as they wrap this with the appropriate type.

3.2. CombinedHtmlFuncMap

Function Signature
func CombinedHtmlFuncMap(preferSprigX bool) (fmap (html/template).FuncMap)

This function returns an (html/template).FuncMap function map (like HtmlFuncMap) combined with github.com/Masterminds/sprig/v3.HtmlFuncMap.

If preferSprigx is true, SprigX function names will override Sprig functions with the same name. If false, Sprig functions will override conflicting SprigX functions with the same name.

3.3. CombinedTxtFuncMap

Function Signature
func CombinedTxtFuncMap(preferSprigX bool) (fmap (text/template).FuncMap)

This function returns a (text/template).FuncMap function map (like TxtFuncMap) combined with github.com/Masterminds/sprig/v3.TxtFuncMap.

If preferSprigx is true, SprigX function names will override Sprig functions with the same name. If false, Sprig functions will override conflicting SprigX functions with the same name.

3.4. FuncMap

Function Signature
func FuncMap() (fmap map[string]any)

This function returns a generic SprigX function map.

You probably want TxtFuncMap or HtmlFuncMap instead, as they wrap this with the appropriate type.

3.5. HtmlFuncMap

Function Signature
func HtmlFuncMap() (fmap (html/template).FuncMap)

This function returns a SprigX (html/template).FuncMap.

3.5.1. Nop

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

Nop is a NO-OP function that one can use in an override map to explicitly disable certain Sprig/SprigX functions that may be deemed "unsafe" and/or to sanitize templates from untrusted input.

It will never error or panic, and s is always an empty string.

3.6. TxtFuncMap

Function Signature
func TxtFuncMap() (fmap (text/template).FuncMap)

This function returns a SprigX (text/template).FuncMap.

4. Template Functions

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

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

4.1. Debugging

4.1.1. dump

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

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

4.2. "Meta"/Template Helpers

4.2.1. metaIsNil

Function Signature
func metaIsNil(obj any) (isNil bool)

metaIsNil returns true if obj is explicitly nil, otherwise it returns false.

This function fills in the gap that text/template.IsTrue and html/template.IsTrue (expressed in templates as {{ if …​ }}) leaves, as those functions/expressions return false for e.g. false booleans AND nils.

4.3. Numbers/Math

4.3.1. numFloat32Str

Function Signature
func numFloat32Str(f float32) (s string)

numFloat32Str returns a complete non-truncated non-right-padded string representation of a float32.

4.3.2. numFloat64

Function Signature
func numFloat64(val any) (f float64, err error)

numFloat64 returns any string representation of a numeric value or any type of numeric value to a float64.

4.3.3. numFloat64Str

Function Signature
func numFloat64Str(f float64) (s string)

numFloat64Str returns a complete non-truncated non-right-padded string representation of a float64.

4.3.4. numFloatStr

Function Signature
func numFloatStr(val any) (s string, err error)

numFloatStr wraps numFloat32Str and numFloat64Str.

val can be a string representation of any numeric value or any type of numeric value.

4.4. Operating System

4.4.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.

4.4.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.

4.4.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.

4.4.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.

4.4.5. osHostname

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

osHostname directly calls os.Hostname.

4.4.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.

4.4.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.

4.4.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.

4.4.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.

4.5. Paths

4.5.1. Generic

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

4.5.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
4.5.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
4.5.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
4.5.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
4.5.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

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

It is recommended to make use of sysOsName to conditionally format path bases/roots if needed.
4.5.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:

OS Result

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
4.5.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:

OS Result

Windows

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

Others (e.g. Linux, macOS)

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

osPathSep returns the os.PathSeparator for this OS.

{{- osPathSep }}

renders as:

OS Result

Windows

 
\

Others (e.g. Linux, macOS)

 
/
4.5.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:

OS Result

Windows

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

Others (e.g. Linux, macOS)

 
a/b/c
a/b/c
/a/b/c
4.5.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:

OS Result

Windows

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

Others (e.g. Linux, macOS)

 
/a/b/c/d
/a/b/c/d
4.5.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:

OS Result

Windows

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

Others (e.g. Linux, macOS)

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

4.6. PSUtil

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

4.6.1. CPU/Processor

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

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

4.6.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.

4.6.1.3. psCpuPct
Function Signature
func psCpuPct(interval time.Duration, percpu bool) (pcts []float64, err error)
4.6.1.4. psCpuTimes
Function Signature
func psCpuTimes(percpu bool) (cpuTimes []TimesStat, err error)

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

4.6.2. Disk

4.6.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.

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

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

4.6.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.

4.6.2.4. psDiskSerial
Function Signature
func psDiskSerial(name string) (serial string, err error)
4.6.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.

4.6.3. Host

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

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

4.6.3.2. psHostId
Function Signature
func psHostId() (hostId string, err error)
4.6.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.

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

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

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

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

4.6.3.6. psHostPlatInfo
Function Signature
func psHostPlatInfo() (platInfo [3]string, err error)

It is necessary to wrap because the function normally returns (string, string, string, error) but a template function may only return either a single value (of any type) or a single value of any type and an error, so the three string returns are consolidated into an ordered [3]string.

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

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

4.6.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.

4.6.3.9. psHostPlatVirt
Function Signature
func psHostVirt() (virtInfo [2]string, err error)

It is necessary to wrap because the function normally returns (string, string, error) but a template function may only return either a single value (of any type) or a single value of any type and an error, so the two string returns are consolidated into an ordered [2]string.

4.6.4. Load

4.6.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.

4.6.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.

4.6.5. Memory

4.6.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.
4.6.5.2. psMemSwap
Function Signature
func psMemSwap() (swap *(github.com/shirou/gopsutil/v4/mem).SwapMemoryStat, err error)
4.6.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.

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

4.6.6. Network

4.6.6.1. psNetConns
Function Signature
func psNetConns(kind string) (conns [](github.com/shirou/gopsutil/v4/net).ConnectionStat, err error)
4.6.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.

4.6.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.

4.6.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.

4.6.6.5. psNetCTStats
Function Signature
func psNetCTStats(percCpu bool) (ctStats [](github.com/shirou/gopsutil/v4/net).ConntrackStat, err error)
4.6.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.

4.6.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.

4.6.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.

4.6.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.

4.6.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.

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

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

4.6.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.

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

This function only exists on Linux.

4.6.7. Processes

4.6.7.1. psProcs
Function Signature
func psProcs(pid int32) (procs []*(github.com/shirou/gopsutil/v4/process).Process, err error)
4.6.7.2. psProcNew
Function Signature
func psProcNew(pid int32) (proc *(github.com/shirou/gopsutil/v4/process).Process, err error)
4.6.7.3. psProcPids
Function Signature
func psProcPids() (pids []int32, err error)

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

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

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

4.6.8. Sensors/Thermals

4.6.8.1. psSensorExTemp
Function Signature
func psSensorExTemp() (temps [](github.com/shirou/gopsutil/v4/sensors).ExTemperature, err error)
Warning

This function only exists on Linux.
4.6.8.2. psSensorTemps
Function Signature
func psSensorTemps() (temps [](github.com/shirou/gopsutil/v4/sensors).TemperatureStat, err error)

4.6.9. Windows Services

Warning

All of these functions are only available on Windows.
4.6.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.
4.6.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.

4.7. Strings

4.7.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.

4.8. Time/Dates/Timestamps

Note

Some of these functions duplicate Sprig functionality, but are included here for predictable API.

Care has been taken to name these functions differently from the Sprig functions where possible and sensible.

4.8.1. tmDate

Function Signature
func tmDate(year int, month time.Month, day, hour, min, sec, nsec int, loc *time.Location) (date time.Time)

tmDate directly calls time.Date.

4.8.2. tmFloatMicro

Function Signature
func tmFloatMicro(t time.Time) (f64 float64)

tmFloatMicro directly calls (r00t2.io/goutils/timex).F64Microseconds.

4.8.3. tmFloatMilli

Function Signature
func tmFloatMilli(t time.Time) (f64 float64)

tmFloatMilli directly calls (r00t2.io/goutils/timex).F64Milliseconds.

4.8.4. tmFloatNano

Function Signature
func tmFloatNano(t time.Time) (f64 float64)

tmFloatNano directly calls (r00t2.io/goutils/timex).F64Nanoseconds.

4.8.5. tmFloat

Function Signature
func tmFloat(t time.Time) (f64 float64)

tmFloat directly calls (r00t2.io/goutils/timex).F64Seconds.

4.8.6. tmFmt

Function Signature
func tmFmt(fstr string, t time.Time) (out string)

tmFormat provides a more pipeline-friendly alternative to calling e.g.

{{- $t := tmNow -}}
{{ $t.Format "<some time format string>" }}

4.8.7. tmNow

Function Signature
func tmNow() (now time.Time)

tmNow directly calls time.Now.

4.8.8. tmParseDur8n

Function Signature
func tmParseDur8n(s string) (d time.Duration, err error)

tmParseDur8n directly calls time.ParseDuration.

4.8.9. tmParseMonth

Function Signature
func tmParseMonth(v any) (mon time.Month, err error)

tmParseMonth attempts to first try tmParseMonthInt and then tries tmParseMonthStr if v is not "numeric".

4.8.10. tmParseMonthInt

Function Signature
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/(html/template).ExecError.

4.8.11. tmParseMonthStr

Function Signature
func tmParseMonthStr(s string) (mon time.Month, err error)

tmParseMonthStr parses a string representation s of a month to a time.Month.

It normalizes s to lowercase and only uses the first 3 characters (the minimum length needed to determine month name uniqueness - "June" vs. "July", "March" vs. "May").

An empty (or whitespace-only) string will use the current month (as determined by time.Now).`

4.8.12. tmParseTime

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

4.9. System/Platform/Architecture

4.9.1. sysArch

Function Signature
func sysArch() (out string)

Returns the runtime.GOARCH constant.

4.9.2. sysNumCpu

Function Signature
func sysNumCpu() (cnt int)

sysNumCpu directly calls runtime.NumCPU.

4.9.3. sysOsName

Function Signature
func sysOsNm() (out string)

Returns the runtime.GOOS constant.

4.9.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.

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 Sprig conversion functions if necessary.
Table 1. sysRuntime Values
Key Value Type

compiler

string

arch

string

os

string

maxprocs

int [1]

cpu_cnt

int

num_cgo

int

num_go

int

go_ver

string

As a convenience, some of these values also have their own dedicated functions as well:

1. For safety concerns, sprigx does not allow setting GOMAXPROCS, this value only contains the current GOMAXPROCS value.
Reference in New Issue View Git Blame Copy Permalink