r00t2/go_goutils
1
0
Fork 0
Code Issues Pull Requests Projects Releases Activity
Files
58556d728126274bc06b54a48813cbb412615132
go_goutils/tplx/sprigx/README.adoc
T
brent saner 58556d7281 v1.16.9 
ADDED:
* netx.IsPub
* encodingx/hexx

Rest are mostly small corrections and docs
2026-06-22 18:51:13 -04:00

69 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. Anchor-links (links within this document to other sections of this document) will likely also not work.

Be sure to view it at properly via the in-repo AsciiDoc rendering or by downloading and viewing the HTML version in a browser locally and/or rendering a PDF version.

2. How do I Render These Docs?

This documentation is written in AsciiDoc (with AsciiDoctor extensions).

To re-render all docs (including PDF):

git clone https://git.r00t2.io/r00t2/go_goutils.git
cd go_goutils
.githooks/pre-commit/01-docgen

2.1. HTML

HTML output is re-rendered and included in git on each commit automatically (via github:gabyx/Githooks) but can be re-rendered on-demand locally via:

git clone https://git.r00t2.io/r00t2/go_goutils.git
cd go_goutils
export orig_dir="$(pwd)"
cd tplx/sprigx
asciidoctor -a ROOTDIR="${orig_dir}/" -o README.html README.adoc

2.2. PDF

This documentation can be rendered to PDF via asciidoctor-pdf. It is not included in git automatically because binary files that change on each commit is not a good idea for git, especially for a repo that gets cloned as part of a library inclusion in a module/package dependency system (like gomod).

To render as PDF:

git clone https://git.r00t2.io/r00t2/go_goutils.git
cd go_goutils
export orig_dir="$(pwd)"
cd tplx/sprigx
asciidoctor-pdf -a ROOTDIR="${orig_dir}/" -o README.pdf README.adoc

3. How do I Use SprigX?

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 
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 
package main

import (
	"text/template"

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

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

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

and a function can even be explicitly overridden,

like this.

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

package main

import (
	"text/template"

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

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

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

4. Library Functions

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

4.1. CombinedFuncMap

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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.

4.2. CombinedHtmlFuncMap

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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.

4.3. CombinedTxtFuncMap

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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.

4.4. FuncMap

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

This function returns a generic SprigX function map.

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

4.5. HtmlFuncMap

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

This function returns a SprigX html/template.FuncMap.

4.6. Nop

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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.

4.7. TxtFuncMap

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

This function returns a SprigX text/template.FuncMap.

5. Template Functions

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

Each function includes its Function Signature to indicate what arguments/parameters it accepts, their type(s), what it returns, and the returned value(s) type(s).

Because Go template functions can only return either:

  • a single value of any type, or

  • a value of any type and an error (in that order)

you can easily determine whether a function can return an error or not by simply referring to the Function Signature.

5.1. Debugging

5.1.1. dump

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.2. "Meta"/Template Helpers

5.2.1. metaIsNil

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

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

	[id="fn_net_all"]
=== Networking
These template functions use capabilities from:

The function prefix is used to indicate which module/package a function is added from.

5.2.2. net

These template functions contain capabilities from net.

5.2.2.1. netCidrMask

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netCidrMask directly calls net.CIDRMask.

5.2.2.2. netExtractAddr

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netExtractAddr wraps net.ParseCIDR and returns the net.IP component.

5.2.2.3. netExtractHost

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netExtractHost wraps net.SplitHostPort and returns the host component (as a string).

5.2.2.4. netExtractIpnet

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netExtractIpnet wraps net.ParseCIDR and returns the net.IPNet component.

5.2.2.5. netExtractPort

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netExtractPort wraps net.SplitHostPort and returns the port component (as a uint16).

5.2.2.6. netIfaces

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netIfaces directly calls net.Interfaces.

5.2.2.7. netIp4Mask

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netIp4Mask wraps net.IPv4Mask.

It is wrapped so that a, b, c, and d may be a string:

{{- $mask := netIp4Mask "198" "51" "100" "10" -}}

or integers/other numeric:

{{- $mask := netIp4Mask 198 51 100 10 -}}

or bytes:

{{- $mask := netIp4Mask 0xc6 0x33 0x64 0x0a -}}

or even a mix:

{{- $mask := netIp4Mask "198" 51 "100" 0x0a -}}
5.2.2.8. netJoinHostPort

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netJoinHostPort directly calls net.JoinHostPort.

5.2.2.9. netParseIP

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netParseIP directly calls net.ParseIP.

5.2.3. net/netip

These template functions contain capabilities from net/netip.

5.2.3.1. netipAddrPort

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netipAddrPort directly calls net/netip.AddrPortFrom.

5.2.3.2. netipParseAddr

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netipParseAddr directly calls net/netip.ParseAddr.

5.2.3.3. netipParseAddrPort

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netipParseAddrPort directly calls net/netip.ParseAddrPort.

5.2.3.4. netipParsePrefix

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netipParsePrefix directly calls net/netip.ParsePrefix.

5.2.3.5. netipPrefix

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netipPrefix directly calls net/netip.PrefixFrom.

5.2.4. go4.org/netipx

These template functions contain capabilities from go4.org/netipx.

5.2.4.1. netipxAddrIpNet

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netipxAddrIpNet directly calls go4.org/netipx.AddrIPNet.

5.2.4.2. netipxCmpPfx

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netipxCmpPfx directly calls go4.org/netipx.ComparePrefix.

5.2.4.3. netipxFromStdAddr

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netipxFromStdAddr wraps go4.org/netipx.FromStdAddr. Instead of returning a boolean as the second value, it will instead be an error if the wrapped boolean is false.

5.2.4.4. netipxFromIp

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netipxFromIp wraps go4.org/netipx.FromStdIP. Instead of returning a boolean as the second value, it will instead be an error if the wrapped boolean is false.

5.2.4.5. netipxFromIpNet

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netipxFromIpNet wraps go4.org/netipx.FromStdIPNet. Instead of returning a boolean as the second value, it will instead be an error if the wrapped boolean is false.

5.2.4.6. netipxParseRange

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netipxParseRange directly calls go4.org/netipx.ParseIPRange.

5.2.4.7. netipxPfxAddr

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netipxPfxAddr directly calls go4.org/netipx.ParsePrefixOrAddr.

5.2.4.8. netipxPfxIpNet

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netipxPfxIpNet directly calls go4.org/netipx.PrefixIPNet.

5.2.4.9. netipxPfxLast

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netipxPfxLast directly calls go4.org/netipx.PrefixLastIP.

5.2.4.10. netipxPfxRange

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netipxPfxRange directly calls go4.org/netipx.RangeOfPrefix.

5.2.4.11. netipxRange

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netipxRange directly calls go4.org/netipx.IPRangeFrom.

5.2.5. r00t2.io/goutils/netx

These template functions contain capabilities from r00t2.io/goutils/netx.

5.2.5.1. netxAddrRfc

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netxAddrRfc directly calls r00t2.io/goutils/netx.AddrRfc.

5.2.5.2. netxAddrRfc

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netxCidr4IpMask directly calls r00t2.io/goutils/netx.Cidr4ToIPMask.

5.2.5.3. netxCidr4Mask

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netxCidr4IpMask directly calls r00t2.io/goutils/netx.Cidr4ToMask.

5.2.5.4. netxCidr4Str

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netxCidr4Str directly calls r00t2.io/goutils/netx.Cidr4ToStr.

5.2.5.5. netxFamilyVer

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netxFamilyVer directly calls r00t2.io/goutils/netx.FamilyToVer.

5.2.5.6. netxGetAddrFam

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netxGetAddrFam directly calls r00t2.io/goutils/netx.GetAddrFamily.

5.2.5.7. netxGetIpFam

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netxGetIpFam directly calls r00t2.io/goutils/netx.GetIpFamily.

5.2.5.8. netxIpRfc

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netxIpRfc directly calls r00t2.io/goutils/netx.IpRfc.

5.2.5.9. netxIpRfcStr

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netxIpRfcStr directly calls r00t2.io/goutils/netx.IpRfcStr.

5.2.5.10. netxIpStripRfc

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netxIpStripRfc directly calls r00t2.io/goutils/netx.IpStripRfcStr.

5.2.5.11. netxIp4MaskCidr

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netxIp4MaskCidr directly calls r00t2.io/goutils/netx.IPMask4ToCidr.

5.2.5.12. netxIp4MaskMask

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netxIp4MaskMask directly calls r00t2.io/goutils/netx.IPMask4ToMask.

5.2.5.13. netxIp4MaskStr

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netxIp4MaskStr directly calls r00t2.io/goutils/netx.IPMask4ToStr.

5.2.5.14. netxIpVerStr

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netxIpVerStr directly calls r00t2.io/goutils/netx.IpVerStr.

5.2.5.15. netxIsBrktd6

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netxIsBrktd6 directly calls r00t2.io/goutils/netx.IsBracketedIp6.

5.2.5.16. netxIsIp

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netxIsIp directly calls r00t2.io/goutils/netx.IsIpAddr.

5.2.5.17. netxIsPfx

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netxIsPfx directly calls r00t2.io/goutils/netx.IsPrefixNet.

5.2.5.18. netxMask4Cidr

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netxMask4Cidr directly calls r00t2.io/goutils/netx.Mask4ToCidr.

5.2.5.19. netxMask4StrCidr

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netxMask4StrCidr directly calls r00t2.io/goutils/netx.Mask4StrToCidr.

5.2.5.20. netxMask4StrIpMask

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netxMask4StrIpMask directly calls r00t2.io/goutils/netx.Mask4StrToIPMask.

5.2.5.21. netxMask4StrMask

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netxMask4StrMask directly calls r00t2.io/goutils/netx.Mask4StrToMask.

5.2.5.22. netxVerFamily

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

netxVerFamily directly calls r00t2.io/goutils/netx.VerToFamily.

5.2.6. r00t2.io/goutils/netx/dnsx

These template functions contain capabilities from r00t2.io/goutils/tplx/sprigx/netx/dnsx.

5.2.6.1. dnsxPtrAddr

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

5.2.6.2. dnsxAddrPtr

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

5.2.6.3. dnsxStrWire

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

5.2.6.4. dnsxWireStr

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

5.2.6.5. dnsxPtrIp

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

5.2.6.6. dnsxIpPtr

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

5.2.6.7. dnsxIsFqdn

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

5.2.6.8. dnsxIsTxt

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

5.2.6.9. dnsxIsNsec3

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

5.2.6.10. dnsxIsSrv

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

5.2.6.11. dnsxIsWild

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

5.2.6.12. dnsxIsLbl

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

5.2.6.13. dnsxIsPtr

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

5.3. Numbers/Math

5.3.1. numFloat32Str

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.3.2. numFloat64

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.3.3. numFloat64Str

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.3.4. numFloatStr

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

numFloatStr wraps numFloat32Str and numFloat64Str.

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

5.4. Operating System

5.4.1. osFQDN

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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.

5.4.2. osGroupById

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

osGroupById returns an os/user.Group from a given group ID/GID.

It more or less behaves exactly like os/user.LookupGroupId, except it will accept either a string or an int as the GID.

5.4.3. osGroupByName

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

osGroupByName returns an os/user.Group from a given group name.

It behaves exactly like os/user.LookupGroup.

5.4.4. osHost

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

osHost returns the "short hostname" by calling os.Hostname and returning the first "host label" (as RFCs refer to it). This is commonly/colloquially called the "hostname" or "hostname without the domain part".

e.g.:

{{- $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 above is from the sprig string slice functions.

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

5.4.5. osHostname

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

osHostname directly calls os.Hostname.

5.4.6. osIdState

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

osIdState returns the current runtime process' r00t2.io/sysutils.IDState.

It directly calls r00t2.io/sysutils.GetIDState.

Warning

This is more or less useless on Windows; it returns only a dummy struct for cross-platform compatibility.

5.4.7. osUser

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

It directly calls os/user.Current.

5.4.8. osUserById

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

osUserById returns an os/user.User from a given user ID/UID.

It more or less behaves exactly like os/user.LookupId, except it will accept either a string or an int as the UID.

5.4.9. osUserByName

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

osUserByName returns an os/user.User from a given username.

It directly calls os/user.Lookup.

5.5. Paths

5.5.1. Generic

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

5.5.1.1. pathJoin

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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
5.5.1.2. pathPipeJoin

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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
5.5.1.3. pathSliceJoin

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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
5.5.1.4. pathSlicePipeJoin

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

pathSlicePipeJoin operates like a hybrid of pathPipeJoin and pathSliceJoin:

  • Like pathPipeJoin, it is suitable for pipeline use — the root/base path is passed in from the pipeline

  • Like pathSliceJoin, it 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
5.5.1.5. pathSubJoin

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.5.2. OS/Platform-Tailored

These operate similar to the path/filepath stdlib library, and use the OS-specific os.PathSeparator.

Warning

Take special note of the oddness around specifying Windows paths and drive letters in e.g. osPathJoin!

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

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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
5.5.2.2. osPathPipeJoin

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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
5.5.2.3. osPathSep

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

osPathSep returns the os.PathSeparator for this OS.

{{- osPathSep }}

renders as:

OS Result

Windows

 
\

Others (e.g. Linux, macOS)

 
/
5.5.2.4. osPathSliceJoin

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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
5.5.2.5. osPathSlicePipeJoin

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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
5.5.2.6. osPathSubJoin

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.6. PSUtil

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

5.6.1. CPU/Processor

5.6.1.1. psCpuCnts

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.6.1.2. psCpuInfo

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.6.1.3. psCpuPct

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

5.6.1.4. psCpuTimes

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.6.2. Disk

5.6.2.1. psDiskIoCnts

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.6.2.2. psDiskLabel

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.6.2.3. psDiskParts

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.6.2.4. psDiskSerial

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

5.6.2.5. psDiskUsage

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.6.3. Host

5.6.3.1. psHostBoot

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.6.3.2. psHostId

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

5.6.3.3. psHostInfo

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.6.3.4. psHostKernArch

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.6.3.5. psHostKernVer

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.6.3.6. psHostPlatInfo

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.6.3.7. psHostPlatUptime

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.6.3.8. psHostUsers

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.6.3.9. psHostPlatVirt

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.6.4. Load

5.6.4.1. psLoadAvg

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.6.4.2. psLoadMisc

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.6.5. Memory

5.6.5.1. psMemExVMem

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

Warning

This function is available on Windows and Linux platforms only.
Warning

This function returns very different types depending on platform.
5.6.5.2. psMemSwap

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

5.6.5.3. psMemSwapDevs

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.6.5.4. psMemVMem

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

5.6.6. Network

5.6.6.1. psNetConns

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

5.6.6.2. psNetConnsMax

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.6.6.3. psNetConnsPid

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.6.6.4. psNetConnsPidMax

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.6.6.5. psNetCTStats

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

5.6.6.6. psNetCTStatList

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.6.6.7. psNetFilterCnts

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.6.6.8. psNetIoCnts

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.6.6.9. psNetIoCntsFile

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.6.6.10. psNetIfaces

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.6.6.11. psNetPids

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.6.6.12. psNetProtoCnt

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

Warning

This only works properly on Linux currently per upstream.

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

5.6.6.13. psNetRev

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

Warning

This function only exists on Linux.

5.6.7. Processes

5.6.7.1. psProcs

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

5.6.7.2. psProcNew

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

5.6.7.3. psProcPids

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.6.7.4. psProcPidExists

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.6.8. Sensors/Thermals

5.6.8.1. psSensorExTemp

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

Warning

This function only exists on Linux.
5.6.8.2. psSensorTemps

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

5.6.9. Windows Services

Warning

All of these functions are only available on Windows.
5.6.9.1. psWinsvcList

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

Warning

This function is only available on Windows.
5.6.9.2. psWinsvcNew

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

Warning

This function is only available on Windows.

5.7. Strings

These template functions use capabilities from:

5.7.1. Standalone

These functions are standalone developed purely for this library. For legacy reasons, these have the special prefix ext.

5.7.1.1. extIndent

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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 doublespace text!

It has quite a few arguments, however:

Argument Type Description

levels

int

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

bool

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

skipEmpty

bool

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

skipWhitespace

bool

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

indentString

string

The string to use as the "indent character". This can be any string, such as "<SP>" (0x20), "\t", ".", "|", "==" etc.

input

string

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

5.7.2. r00t2.io/goutils/stringsx

These template functions contain capabilities from r00t2.io/goutils/stringsx.

5.7.2.1. strsxIsAscii

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

strsxIsAscii directly calls r00t2.io/goutils/tplx/sprigx/stringsx.IsAscii.

5.7.2.2. strsxIsAsciiBuf

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

strsxIsAsciiBuf directly calls r00t2.io/goutils/tplx/sprigx/stringsx.IsAsciiBuf.

5.7.2.3. strsxIsAsciiSpcl

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

strsxIsAsciiSpcl directly calls r00t2.io/goutils/tplx/sprigx/stringsx.IsAsciiSpecial.

5.7.2.4. strsxIsAsciiBufSpcl

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

strsxIsAsciiBufSpcl directly calls r00t2.io/goutils/tplx/sprigx/stringsx.IsAsciiSpecial.

5.7.2.5. strsxLenSpl

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

5.7.2.6. strsxLenSplStr

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

strsxLenSplStr directly calls r00t2.io/goutils/tplx/sprigx/stringsx.LenSplitStr.

5.7.2.7. strsxPad

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

5.7.2.8. strsxRedact

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

strsxRedact directly calls r00t2.io/goutils/tplx/sprigx/stringsx.Redact.

5.7.2.9. strsxRev

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

5.7.2.10. strsxTrimLns

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

5.7.2.11. strsxTrimSpcLft

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

strsxTrimSpcLft directly calls r00t2.io/goutils/tplx/sprigx/stringsx.TrimSpaceLeft.

5.7.2.12. strsxTrimSpcRt

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

5.8. System/Platform/Architecture

5.8.1. sysArch

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

Returns the runtime.GOARCH constant.

5.8.2. sysNumCpu

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

sysNumCpu directly calls runtime.NumCPU.

5.8.3. sysOsName

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

Returns the runtime.GOOS constant.

5.8.4. sysRuntime

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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:

5.9. Time/Dates/Timestamps

Note

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

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

5.9.1. tmDate

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

tmDate directly calls time.Date.

5.9.2. tmFloatMicro

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.9.3. tmFloatMilli

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.9.4. tmFloatNano

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.9.5. tmFloat

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.9.6. tmFmt

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

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

5.9.7. tmNow

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

tmNow directly calls time.Now.

5.9.8. tmParseDur8n

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

tmParseDur8n directly calls time.ParseDuration.

5.9.9. tmParseMonth

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

5.9.10. tmParseMonthInt

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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.

5.9.11. tmParseMonthStr

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

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

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

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

5.9.12. tmParseTime

Unresolved directive in <stdin> - include::./_docs/includes/funcsig.adoc[]

tmParseTime directly calls time.Parse.

Be sure that layout is a properly parseable layout format.

6. TODO/Wishlist

6.1. Function Collections

Functions should be split into more granular function maps that allows a conusmer to only load a certain subset of relevant functions to reduce surface - string functions, network functions, etc.

This would ideally also allow for e.g. FuncMap "generators" that would return a FuncMap of methods bound to a struct with certain contextual settings (e.g. a root path restriction for Extend OS functions).

6.2. Fallibility

Requires Function Collections first.

Modeled after Vector’s VRL concept of Fallibility (see also).

Functions should be grouped/selectable by "fallibility" - if they are guaranteed to return a meaningful value always, if they are guaranteed to return a value that may be empty but no error will be returned, or if a function may return an error.

6.3. Function Scope Segregation

Requires Function Collections first.

Modeled (slightly) after Vector’s VRL concept of purity.

As more functions get added (and even with the present function set), it may be desired that only functions that work only with provided data are exposed to templates.

The goal is to scope/separate functions in such a way that they are "tagged" with multiple attributes/characteristics:

  • Fallibility

  • External Read (e.g. reading arbitrary files)

  • Internal Modify (would potentially transform source data/data structures)

  • External Modify (would affect the invoking system, e.g. [todo_os_fs])

  • Arbitrary Execution (e.g. osExec — see [todo_os_fs])

  • Network Access (e.g. would involve creating network connections instead of operating on provided data locally)

A risk "score" from 1-10 should also be implemented with the above scopes/classes for further/alternative filtering by consumers.

6.4. Extend OS functions

Requires Function Scope Segregation first. (Not technically, but can provide a pretty big risk of not split out first.)

Adding the ability to read files from the filesystem should be added. As part of this, however, a package-level variable should be implemented (or Function Collections) that can restrict reading to a specific prefix.

Off the top of my head:

  • osReadFile

    • Returns an *os.File.

    • Closing the handler gets tricky, though…​ it can be done from within the template, but templates also have no defer to my knowledge. Caveat emptor.

  • osReadFileBuf

    • Will return a *bytes.Buffer with the contents of a file.

    • A little safer than osReadFile as it’s backed by a static set of bytes and doesn’t need to be .Close()'d.

  • osReadFileBytes

    • Should include an optional length limiter, so data from e.g. /dev/urandom can be read from.

  • osReadFileStr

    • Would return string instead of []byte.

  • osReadDir

    • Returns a []fs.DirEntry of a given path via os.ReadDir.

  • osStat

    • Returns an fs.FileInfo from an os.Stat or os.LStat (controlled by tpl function parameter)

  • osExec

    • Exactly what you’d think. Returns a command via an os/exec.Cmd, with params passed to os/exec.Command (plus *bytes.Buffers set to <exec.Cmd>.Stdin and <exec.Cmd>.Stdout).

These obviously have the potential to be incredibly dangerous if using untrusted template strings.

6.4.1. Environment Variables

6.5. System Functions

This would be…​ particularly tricky.

I essentially want to expose a large amount of functionality from golang.org/x/sys/unix and golang.org/x/sys/windows (and its subpackages).

At the least I should have a way to (attempt to) convert/coerce an fs.FileInfo.Sys() into the platform-appropriate definite object (e.g. a golang.org/x/sys/unix.Stat_t and/or golang.org/x/sys/unix.Statx_t, or a golang.org/x/sys/windows.Win32FileAttributeData).

6.6. Encoding Functions

Should require Function Collections first (at least for grouping).

6.7. UUID Functions

Should require Function Collections first (at least for grouping).

6.8. URL Functions

Expose net/url functions to derive URLs.

6.9. Live Networking Functions

Requires Function Scope Segregation first.

Sometimes networking data lookup is needed at time of render/contextual to render.

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