mains

Documentation

Overview

Package mains contains functions for implementing a service or command-line utility

Index

• Constants
• func BaseOptionData(program string, yaml YamlOption) (optionData []pflags.OptionData)
• func MinimalRecovery(errp *error)
• func ProcessStart(pid int) (processStart time.Time, err error)
• func ProcessStartTime() (createTime time.Time)
• func SystemUpSince() (upSince time.Time, err error)
• type ArgumentSpec
• type BaseOptionsType
• type Executable
  • func (x *Executable) AddErr(err error)
  • func (x *Executable) ConfigureLog() (ex1 *Executable)
  • func (x *Executable) Exit(stausCode ...int)
  • func (x *Executable) Init() (ex2 *Executable)
  • func (x *Executable) LongErrors(isLongErrors bool, isErrorLocation bool) *Executable
  • func (x *Executable) PrintBannerAndParseOptions(optionsList []pflags.OptionData) (ex1 *Executable)
  • func (x *Executable) Recover(errp ...*error)
• type Keystrokes
  • func NewKeystrokes() (keystrokes *Keystrokes)
  • func (k *Keystrokes) Ch() (ch <-chan string)
  • func (k *Keystrokes) CloseNow(errp *error)
  • func (k *Keystrokes) Launch() (k2 *Keystrokes)
• type YamlOption

Constants

const (
	// if [Executable.OKtext] is assigned NoOK there ir no successful message on app exit
	NoOK = "-"
	// displays error location but not stack traces
	//	- second argument to [Executable.LongErrors]
	OutputErrorLocationTrue = true
)

const (
	// NoArguments besides switches, zero trailing arguments is allowed
	NoArguments = 1 << iota
	// OneArgument besides switches, exactly one trailing arguments is allowed
	OneArgument
	// ManyArguments besides switches, one or more trailing arguments is allowed
	ManyArguments
)

Functions

func BaseOptionData

func BaseOptionData(program string, yaml YamlOption) (optionData []pflags.OptionData)

BaseOptionData returns basic options for mains

• verbose debug silent version
• if yaml == YamlYes: yamlFile yamlKey

func MinimalRecovery

func MinimalRecovery(errp *error)

MinimalRecovery handles process exit for main, in particular error message and non-zero status code for errors

• on success:
• – a timestamped success message is printed to stderr
• — the function returns
• panics are not handled
• on error:
• if error contains a panic, error is printed with stack trace
• otherwise one-liner with location
• os.Exit is invoked with status code 1

Usage:

main() {
  var err error
  defer mains.MinimalRecovery(&err)

func ProcessStart

func ProcessStart(pid int) (processStart time.Time, err error)

ProcessStart returns start time for process pid with second resolution

func ProcessStartTime

func ProcessStartTime() (createTime time.Time)

ProcessStartTime returns start time for process pid with second resolution

• panic on troubles

func SystemUpSince

func SystemUpSince() (upSince time.Time, err error)

SystemUpSince returns boot time second resolution

Types

type ArgumentSpec

type ArgumentSpec uint32

ArgumentSpec bitfield for 0, 1, many arguments following command-line switches

type BaseOptionsType

type BaseOptionsType = struct {
	YamlFile, YamlKey, Verbosity   string
	Debug, Silent, Version, DoYaml bool
}

BaseOptionsType is the type that holds mains’ effective option values

var BaseOptions BaseOptionsType

BaseOptions is the value that holds mains’ effective option values

type Executable

type Executable struct {
	Program        string       // “gonet”
	Version        string       // “0.0.1”
	Comment        string       // [ banner text after program and version] “options parsing” changes in last version
	Description    string       // [Description part of usage] “configures firewall and routing”
	Copyright      string       // “© 2020…”
	License        string       // “ISC License”
	OKtext         string       // “Completed successfully”
	ArgumentsUsage string       // usage help text for arguments after options
	Arguments      ArgumentSpec // eg. mains.NoArguments

	Launch       time.Time // process start time
	LaunchString string    // Launch as printable rfc 3339 time string
	Host         string    // short hostname, ie. no dots “mymac”

	ArgCount int      // number of post-options strings during parse
	Arg      string   // if one post-options string and that is allowed, this is the string
	Args     []string // any post-options strings if allowed
	// errors are printed with stack traces, associated values and errors
	//	- panics are always printed long
	//	- if errors long or more than 1 error, the first error is repeated last as a one-liner
	IsLongErrors bool
	// adds a code location to errors if not IsLongErrors
	IsErrorLocation bool
	// contains filtered or unexported fields
}

Executable constant strings that describes an executable advisable static values include Program Version Comment Description Copyright License Arguments like:

var ex = mains.Executable{
  Program:     "getip",
  Version:     "0.0.1",
  Comment:     "first version",
  Description: "finds ip address for hostname",
  Copyright:   "© 2020-present Harald Rudell <harald.rudell@gmail.com> (http://www.haraldrudell.com)",
  License:     "All rights reserved",
  Arguments:   mains.NoArguments | mains.OneArgument,
}

func (*Executable) AddErr

func (x *Executable) AddErr(err error)

AddErr extended with immediate printing of first error

func (*Executable) ConfigureLog

func (x *Executable) ConfigureLog() (ex1 *Executable)

ConfigureLog configures the default log such as parl.Log parl.Out parl.D for silent, debug and regExp. Settings come from BaseOptions.Silent and BaseOptions.Debug.

ConfigureLog supports functional chaining like:

exe.Init().
  …
  ConfigureLog().
  ApplyYaml(…)

func (*Executable) Exit

func (x *Executable) Exit(stausCode ...int)

Exit terminate from mains.err: exit 0 or echo to stderr and status code 1

• Usually invoked for all app terminations
• — either by defer ex.Recover(&err) at beginning fo main
• — or rarely by direct invocation in program code
• when invoked, errors are expected to be in ex.err from:
• — ex.AddErr or
• — ex.Recover
• Exit does not return from invoking os.Exit

func (*Executable) Init

func (x *Executable) Init() (ex2 *Executable)

Init initializes a created mains.Executable value

• the value should have relevant fields populates such as exeuctable name and more
• — Program Version Comment Copyright License Arguments
• populates launch time and sets silence if first os.Args argument is “-silent.”
• Init supports function chaining like:

typical code:

ex.Init().
  PrintBannerAndParseOptions(optionData).
  LongErrors(options.Debug, options.Verbosity != "").
  ConfigureLog()
applyYaml(options.YamlFile, options.YamlKey, applyYaml, optionData)
…

func (*Executable) LongErrors

func (x *Executable) LongErrors(isLongErrors bool, isErrorLocation bool) *Executable

LongErrors sets if errors are printed with stack trace and values. LongErrors supports functional chaining:

exe.Init().
  …
  LongErrors(options.Debug, options.Verbosity != "").
  ConfigureLog()…

isLongErrors prints full stack traces, related errors and error data in string lists and string maps.

isErrorLocation appends the innermost location to the error message when isLongErrors is not set:

error-message at error116.(*csTypeName).FuncName-chainstring_test.go:26

func (*Executable) PrintBannerAndParseOptions

func (x *Executable) PrintBannerAndParseOptions(optionsList []pflags.OptionData) (ex1 *Executable)

PrintBannerAndParseOptions prints greeting like:

parl 0.1.0 parlca https server/client udp server

It then parses options described by []OptionData stroing the values at OptionData.P. If options fail to parse, a proper message is printed to stderr and the process exits with status code 2. PrintBannerAndParseOptions supports functional chaining like:

exe.Init().
  PrintBannerAndParseOptions(…).
  LongErrors(…

Options and yaml is configured likeso:

var options = &struct {
  noStdin bool
  *mains.BaseOptionsType
}{BaseOptionsType: &mains.BaseOptions}
var optionData = append(mains.BaseOptionData(exe.Program, mains.YamlYes), []mains.OptionData{
  {P: &options.noStdin, Name: "no-stdin", Value: false, Usage: "Service: do not use standard input", Y: mains.NewYamlValue(&y, &y.NoStdin)},
}...)
type YamlData struct {
  NoStdin bool // nostdin: true
}
var y YamlData

func (*Executable) Recover

func (x *Executable) Recover(errp ...*error)

Recover function to be used in main.main:

func main() {
  defer Recover()
  …

On panic, the function prints to stderr: "Unhandled panic invoked exe.Recover: stack:" followed by a stack trace. It then adds an error to mains.Executable and terminates the process with status code 1

type Keystrokes

type Keystrokes struct {
	// contains filtered or unexported fields
}

Keystrokes reads line-wise from standard input

func NewKeystrokes

func NewKeystrokes() (keystrokes *Keystrokes)

NewKeystrokes returns an object reading lines from standard input

• -verbose='mains...Keystrokes|mains.keystrokesThread' “github.com/haraldrudell/parl/mains.(*Keystrokes)”

func (*Keystrokes) Ch

func (k *Keystrokes) Ch() (ch <-chan string)

Ch returns a channel where lines from the keyboard can be received

• the channel may close upon Keystrokes.CloseNow

func (*Keystrokes) CloseNow

func (k *Keystrokes) CloseNow(errp *error)

func (*Keystrokes) Launch

func (k *Keystrokes) Launch() (k2 *Keystrokes)

Launch starts reading stdin for keystrokes

• keystrokesThread reads blocking from os.Stdin and therefore cannot be cancelled
• therefore no parl.Go is used
• parl.Infallible prints errors that should not happen to os.Stderr
• on CloseNow, KeystrokesThread exits on the following return keypress. Mostly, the process exits prior.

type YamlOption

type YamlOption bool

type for second argument to BaseOptionData

• mains.YamlNo mains.YamlYes

const (
	// as second argument to [BaseOptionData], indicates that yaml options -yamlFile -yamlKey should not be present
	YamlNo YamlOption = false
	// as second argument to [BaseOptionData], indicates that yaml options -yamlFile -yamlKey should be present
	YamlYes YamlOption = true
	// indicates silent: no banner. Must be first option on command-line ‘-silent’
	SilentString = "-" + silentOption
)