uggo

README

uggo

Ungraceful Gnu-ification for Go.

This helps Go commandline apps to behave a bit more 'coreutils'-like, or 'Gnu-ish'.

Yes, there are many other flagset libraries out there. This one provides a wrapper around the existing flag.FlagSet, embedding and embellishing it. You can use uggo as a drop-in replacement for flag.FlagSet, or you can specify a couple of different behaviours. Up to you.

The reason why it's called 'ungraceful' is because it's an approximation of gnu-like behaviour, as close as I could get while still wrapping flag.FlagSet. It's good enough for me anyway. Also, the STDIN-pipe-detection is platform-specific, relying on an undocumented behaviour in Windows.

Initial features

• 'Gnuify' options such as -lah so they are treated as -l -a -h (whereas --lah is treated as-is, as a single option --lah)
• detect whether STDIN is being piped from another process
• 'aliased flags' (wrapper methods making it easier to define short and long options, or just multiple options)
• Re-jigged format of 'Usage' to incroporate 'aliased flags'

See Also

These programs use uggo:

• https://github.com/laher/someutils
• https://github.com/laher/wget-go
• https://github.com/laher/scp-go

Documentation

Overview

extend FlagSet with support for flag aliasMap

Index

• Constants
• Variables
• func Gnuify(call []string) []string
• func GnuifyWithExceptions(call, exceptions []string) []string
• func IsPipingStdin() bool
• func OpenAll(openers []FileOpener) ([]*os.File, error)
• type FileOpener
  • func ToPipeWriteableOpeners(args []string, flag int, perm os.FileMode, outPipe *os.File) []FileOpener
  • func ToWriteableOpeners(args []string, flag int, perm os.FileMode) []FileOpener
• type FlagSetWithAliases
  • func NewFlagSet(desc string, errorHandling flag.ErrorHandling) FlagSetWithAliases
  • func NewFlagSetDefault(name, argUsage, version string) FlagSetWithAliases
  • func (flagSet FlagSetWithAliases) AliasedBoolVar(p *bool, items []string, def bool, description string)
  • func (flagSet FlagSetWithAliases) AliasedDurationVar(p *time.Duration, items []string, def time.Duration, description string)
  • func (flagSet FlagSetWithAliases) AliasedFloat64Var(p *float64, items []string, def float64, description string)
  • func (flagSet FlagSetWithAliases) AliasedInt64Var(p *int64, items []string, def int64, description string)
  • func (flagSet FlagSetWithAliases) AliasedIntVar(p *int, items []string, def int, description string)
  • func (flagSet FlagSetWithAliases) AliasedStringVar(p *string, items []string, def string, description string)
  • func (flagSet FlagSetWithAliases) ArgsAsPipeWriteables(flag int, perm os.FileMode, outPipe *os.File) []FileOpener
  • func (flagSet FlagSetWithAliases) ArgsAsReadables() []FileOpener
  • func (flagSet FlagSetWithAliases) ArgsAsWriteables(flag int, perm os.FileMode) []FileOpener
  • func (flagSet FlagSetWithAliases) IsHelp() bool
  • func (flagSet FlagSetWithAliases) IsVersion() bool
  • func (flagSet FlagSetWithAliases) Parse(call []string) error
  • func (flagSet FlagSetWithAliases) ParsePlus(call []string) (error, int)
  • func (flagSet FlagSetWithAliases) PrintDefaults()
  • func (flagSet FlagSetWithAliases) PrintDefaultsTo(out io.Writer)
  • func (flagSet FlagSetWithAliases) PrintVersion()
  • func (flagSet FlagSetWithAliases) ProcessHelpOrVersion() bool
  • func (flagSet FlagSetWithAliases) RecordAliases(items []string, typ string)
  • func (flagSet FlagSetWithAliases) SetOutput(out io.Writer)
  • func (flagSet FlagSetWithAliases) Usage()

Constants

const (
	VERSION = "0.3.2"
)

Variables

var EXIT_OK = errors.New("Exit OK")

Functions

func Gnuify

func Gnuify(call []string) []string

gnuify a list of flags 'Gnuification' in this case refers to the Gnu-like expansion of single-hyphen multi-letter flags such as `-la` into separate flags `-l -a` note: allow '-help' to be used as single-hyphen (to assist the unitiated)

func GnuifyWithExceptions

func GnuifyWithExceptions(call, exceptions []string) []string

'Gnuify' a slice of flags, all bar for a list of exceptions. 'Gnuification' in this case refers to the Gnu-like expansion of single-hyphen multi-letter flags such as `-la` into separate flags `-l -a` 'Execeptions' in this case means exceptions to the rule (not the language construct)

func IsPipingStdin

func IsPipingStdin() bool

func OpenAll

func OpenAll(openers []FileOpener) ([]*os.File, error)

atomically open all files at once. Only use this when you actually want all open at once (rather than sequentially) e.g. writing the same data to all at once as-in a 'tee' operation.

Types

type FileOpener

type FileOpener func() (*os.File, error)

function which can (open and) return a File at some later time

func ToPipeWriteableOpeners

func ToPipeWriteableOpeners(args []string, flag int, perm os.FileMode, outPipe *os.File) []FileOpener

Convert arguments to File openers. An argument with filename "-" is treated as the 'standard output' Takes a writer 'outPipe' for handling this special case

func ToWriteableOpeners

func ToWriteableOpeners(args []string, flag int, perm os.FileMode) []FileOpener

Convert arguments to File openers. An argument with filename "-" is treated as the 'standard output'

type FlagSetWithAliases

type FlagSetWithAliases struct {
	*flag.FlagSet
	AutoGnuify bool //sets whether it interprets options gnuishly (e.g. -lah being equivalent to -l -a -h)
	// contains filtered or unexported fields
}

This FlagSet embeds Golang's FlagSet but adds some extra flavour - support for 'aliased' arguments - support for 'gnuification' of short-form arguments - handling of --help and --version - some flexibility in 'usage' message

func NewFlagSet

func NewFlagSet(desc string, errorHandling flag.ErrorHandling) FlagSetWithAliases

factory which sets defaults and NOTE: discards thet output of the embedded flag.FlagSet. This was necessary in order to override the 'usage' message

func NewFlagSetDefault

func NewFlagSetDefault(name, argUsage, version string) FlagSetWithAliases

Factory setting useful defaults Sets up --help and --version flags

func (FlagSetWithAliases) AliasedBoolVar

func (flagSet FlagSetWithAliases) AliasedBoolVar(p *bool, items []string, def bool, description string)

Set up multiple names for a bool flag

func (FlagSetWithAliases) AliasedDurationVar

func (flagSet FlagSetWithAliases) AliasedDurationVar(p *time.Duration, items []string, def time.Duration, description string)

Set up multiple names for a time.Duration flag

func (FlagSetWithAliases) AliasedFloat64Var

func (flagSet FlagSetWithAliases) AliasedFloat64Var(p *float64, items []string, def float64, description string)

Set up multiple names for a float64 flag

func (FlagSetWithAliases) AliasedInt64Var

func (flagSet FlagSetWithAliases) AliasedInt64Var(p *int64, items []string, def int64, description string)

Set up multiple names for an int64 flag

func (FlagSetWithAliases) AliasedIntVar

func (flagSet FlagSetWithAliases) AliasedIntVar(p *int, items []string, def int, description string)

Set up multiple names for an int flag

func (FlagSetWithAliases) AliasedStringVar

func (flagSet FlagSetWithAliases) AliasedStringVar(p *string, items []string, def string, description string)

Set up multiple names for a string flag

func (FlagSetWithAliases) ArgsAsPipeWriteables

func (flagSet FlagSetWithAliases) ArgsAsPipeWriteables(flag int, perm os.FileMode, outPipe *os.File) []FileOpener

Convert arguments to File openers. An argument with filename "-" is treated as the 'standard output' Takes a writer 'outPipe' for handling this special case

func (FlagSetWithAliases) ArgsAsReadables

func (flagSet FlagSetWithAliases) ArgsAsReadables() []FileOpener

converts arguments to readable file references. An argument with filename "-" is treated as the 'standard input'

func (FlagSetWithAliases) ArgsAsWriteables

func (flagSet FlagSetWithAliases) ArgsAsWriteables(flag int, perm os.FileMode) []FileOpener

Convert arguments to File openers. An argument with filename "-" is treated as the 'standard output'

func (FlagSetWithAliases) IsHelp

func (flagSet FlagSetWithAliases) IsHelp() bool

convenience method for storing 'usage' behaviour

func (FlagSetWithAliases) IsVersion

func (flagSet FlagSetWithAliases) IsVersion() bool

convenience method for storing 'get version' behaviour

func (FlagSetWithAliases) Parse

func (flagSet FlagSetWithAliases) Parse(call []string) error

parse flags from a given set of argv type flags

func (FlagSetWithAliases) ParsePlus

func (flagSet FlagSetWithAliases) ParsePlus(call []string) (error, int)

func (FlagSetWithAliases) PrintDefaults

func (flagSet FlagSetWithAliases) PrintDefaults()

print defaults to the default output writer

func (FlagSetWithAliases) PrintDefaultsTo

func (flagSet FlagSetWithAliases) PrintDefaultsTo(out io.Writer)

print defaults to a given writer. Output distinguishes aliases

func (FlagSetWithAliases) PrintVersion

func (flagSet FlagSetWithAliases) PrintVersion()

PrintVersion

func (FlagSetWithAliases) ProcessHelpOrVersion

func (flagSet FlagSetWithAliases) ProcessHelpOrVersion() bool

process built-in help and version flags.

Returns 'true' when one of these was set. (i.e. stop processing)

func (FlagSetWithAliases) RecordAliases

func (flagSet FlagSetWithAliases) RecordAliases(items []string, typ string)

keep track of aliases to a given flag

func (FlagSetWithAliases) SetOutput

func (flagSet FlagSetWithAliases) SetOutput(out io.Writer)

Set writer for displaying help and usage messages.

func (FlagSetWithAliases) Usage

func (flagSet FlagSetWithAliases) Usage()

Print Usage message