exec_extra

Documentation

Index

• Constants
• Variables
• func ExecCmdReturn(cmd *exec.Cmd) (exitStatus int, err error)
• func GetCmdFromStruct[T any](s T, defaultOpts ...cmdArgOpt) (cmdSlice []string, err error)

Constants

const (
	/*
		CmdArgOptPreferShort prefers short options where possible.
		Has no effect if Windows traditional syntax is used.

		The default is to use long options.
		See also CmdArgOptPreferLong.

		Corresponding struct tag option: prefer_short
	*/
	CmdArgOptPreferShort cmdArgOpt = 1 << iota
	/*
		CmdArgOptPreferLong prefers long options where possible.
		Has no effect if Windows traditional syntax is used.

		This behavior is the default, but it can be used to
		 override a CmdArgOptPreferShort from a parent.

		Corresponding struct tag option: prefer_long
	*/
	CmdArgOptPreferLong
	/*
		CmdArgOptShortEquals will use an equals separator
		 for short flags instead of a space (the default).
		Has no effect if Windows traditional syntax is used.

		Corresponding struct tag option: short_equals
	*/
	CmdArgOptShortEquals
	/*
		CmdArgOptShortNoEquals will use a space separator
		 for short flags instead of an equals.
		Has no effect if Windows traditional syntax is used.

		This behavior is the default, but it can be used to
		 override a CmdArgOptPreferShort from a parent.

		Corresponding struct tag option: no_short_equals
	*/
	CmdArgOptShortNoEquals
	/*
		CmdArgOptLongEquals will use an equals separator
		 for long flags instead of a space.
		Has no effect if Windows traditional syntax is used.

		This behavior is the default, but it can be used to
		 override a CmdArgOptLongNoEquals from a parent.

		Corresponding struct tag option: long_equals
	*/
	CmdArgOptLongEquals
	/*
		CmdArgOptLongNoEquals will use a space separator
		 for short flags instead of an equals.
		Has no effect if Windows traditional syntax is used.

		This behavior is the default, but it can be used to
		 override a CmdArgOptPreferShort from a parent.

		Corresponding struct tag option: no_long_equals
	*/
	CmdArgOptLongNoEquals
	/*
		CmdArgOptForceNoPosix forces the resulting command string to use "traditional Windows" flag notation.

		Traditionally, Windows used flags like `/f` instead of POSIX `-f`, `/c:value` instead of `-c value`
		 or `-c=value`, etc.
		Has no effect if not running on Windows.

		This behavior is the default, but it can be used to
		 override a CmdArgOptPreferShort from a parent.

		See also the inverse of this option, CmdArgOptForcePosix.

		Corresponding struct tag option: force_no_posix
	*/
	CmdArgOptForceNoPosix
	/*
		CmdArgOptForcePosix forces the resulting command string to use "POSIX" flag notation.

		Traditionally, Windows used flags like `/f` instead of POSIX `-f`, `/c:value` instead of `-c value`
		 or `-c=value`, etc.

		If this option is passed, then the POSIX flag syntax (-a/--arg) will be used instead.

		Note that on Windows runtime, the default is to use the traditional slash-based syntax.
		If you are generating command strings for Powershell or third-party software, you probably
		 want to use CmdArgsOptForcePosix instead.

		See also the inverse of this option, CmdArgsOptForceNoPosix.

		Corresponding struct tag option: force_posix
	*/
	CmdArgOptForcePosix
)

const CmdArgOptNone bitmask.MaskBit = 0

CmdArgOptNone is an "empty option" and does nothing.

Variables

var (
	CmdArgsTag string = "cmdarg"
	/*
		CmdArgsDictSep specifies the string to use to separate keys and values.

		To override at the struct field level, use the tag value:

			`<CmdArgsTag>:"dictsep=<str>"`

		Where str is the string to use. e.g.:

			`cmdarg:"short=d,long=data,dictsep=."`

		Would render a map value of map[string]string{"foo": "bar"} as:

			`-d foo.bar`
	*/
	CmdArgsDictSep string = ":"
)

Functions

func ExecCmdReturn

func ExecCmdReturn(cmd *exec.Cmd) (exitStatus int, err error)

ExecCmdReturn runs cmd and alsom returns the exitStatus.

A non-zero exit status is not treated as an error.

func GetCmdFromStruct

func GetCmdFromStruct[T any](s T, defaultOpts ...cmdArgOpt) (cmdSlice []string, err error)

GetCmdFromStruct takes a pointer to a struct and returns a slice of strings compatible with os/exec.Cmd.

The tag name used can be changed by setting the CmdArgsTag variable in this module; the default is `cmdarg`.

Tag value format:

<tag>:"<option>=<value>[,<option>[=<value>],<option>[=<value>]...]"

e.g.

cmdarg:"short=l,long=list"
cmdarg:"short=l"
cmdarg:"long=list"

If the tag value is "-", the field will be explicitly skipped. (This is the default behavior for struct fields not tagged with `cmdarg`.) If the field is nil, it will be skipped.

If a cmdarg tag is specified but has no `short` or `long` option value, the field will be skipped entirely. If a field's value is nil, it will be skipped. Otherwise if a field's value is the zero-value, it will be skipped.

Aside from the 'short' and 'long' tag valued-options, see the comment for each CmdArgOpt* constant

for their corresponding tag option and the CmdArgs* variables as well for their corresponding tag option.

Each struct field can be one of the following types:

• string
• *string
• slice (with elements of supported types)
• array (with elements of supported types)
• map (with keys and values of supported types; see the CmdArgsDictSep variable for the separator to use)
• struct (with fields of supported types)
• int/int8/int16/int32/int64
• uint/uint8/uint16/uint32/uint64
• float32/float64

Struct fields, slice/array elements, etc. are processed in order. Maps, because ordering is non-deterministic, may have unpredictable ordering.

If s is nil, nothing will be done. If s is not a pointer to a struct, nothing will be done.