flag

Documentation

Overview

Package flag is an internal package to allow us to gracefully transition from the standard library's flag package to pflag. See VEP-4 for details.

In general, this package should not be imported or depended on, except in the cases of package servenv, and entrypoints in go/cmd. This package WILL be deleted after the migration to pflag is completed, without any support for compatibility.

Copyright 2022 The Vitess Authors.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

• func Arg(i int) string
• func Args() (args []string)
• func IsFlagProvided(name string) bool
• func Lookup(name string) *flag.Flag
• func Parse(fs *flag.FlagSet)
• func ParseFlagsForTest()
• func Parsed() bool
• func PreventGlogVFlagFromClobberingVersionFlagShorthand(fs *flag.FlagSet)
• func SetUsage(fs *goflag.FlagSet, opts UsageOptions)
• func TrickGlog()
• func Usage()
• type UsageOptions

Functions

func Arg

func Arg(i int) string

Arg returns the ith command-line argument after flags have been processed, ignoring the first double-dash ("--") argument separator. If fewer than `i` arguments were specified, the empty string is returned. If no double-dash was specified, this is equivalent to flag.Arg(i) from the standard library flag package.

func Args

func Args() (args []string)

Args returns the positional arguments with the first double-dash ("--") removed. If no double-dash was specified on the command-line, this is equivalent to flag.Args() from the standard library flag package.

func IsFlagProvided

func IsFlagProvided(name string) bool

IsFlagProvided returns if the given flag has been provided by the user explicitly or not

func Lookup

func Lookup(name string) *flag.Flag

Lookup returns a pflag.Flag with the given name, from either the pflag or standard library `flag` CommandLine. If found in the latter, it is converted to a pflag.Flag first. If found in neither, this function returns nil.

func Parse

func Parse(fs *flag.FlagSet)

Parse wraps the standard library's flag.Parse to perform some sanity checking and issue deprecation warnings in advance of our move to pflag.

It also adjusts the global CommandLine's Usage func to print out flags with double-dashes when a user requests the help, attempting to otherwise leave the default Usage formatting unchanged.

See VEP-4, phase 1 for details: https://github.com/vitessio/enhancements/blob/c766ea905e55409cddeb666d6073cd2ac4c9783e/veps/vep-4.md#phase-1-preparation

func ParseFlagsForTest

func ParseFlagsForTest()

ParseFlagsForTest parses `go test` flags separately from the app flags. The problem is that pflag.Parse() does not handle `go test` flags correctly. We need to separately parse the test flags using goflags. Additionally flags like test.Short() require that goflag.Parse() is called first.

func Parsed

func Parsed() bool

Parsed returns true if the command-line flags have been parsed.

It is agnostic to whether the standard library `flag` package or `pflag` was used for parsing, in order to facilitate the migration to `pflag` for VEP-4 1.

func PreventGlogVFlagFromClobberingVersionFlagShorthand

func PreventGlogVFlagFromClobberingVersionFlagShorthand(fs *flag.FlagSet)

The default behavior of PFlagFromGoFlag (which is called on each flag when calling AddGoFlagSet) is to allow any flags with single-character names to be accessible both as, for example, `-v` and `--v`.

This prevents us from exposing version via `--version|-v` (pflag will actually panic when it goes to add the glog log-level flag), so we intervene to blank out the Shorthand for _just_ that flag before adding the rest of the goflags to a particular pflag FlagSet.

IMPORTANT: This must be called prior to AddGoFlagSet in both Parse and ParseFlagsForTest.

func SetUsage

func SetUsage(fs *goflag.FlagSet, opts UsageOptions)

SetUsage sets the Usage function for the given FlagSet according to the options. For VEP-4, all flags are printed in their double-dash form.

func TrickGlog

func TrickGlog()

TrickGlog tricks glog into understanding that flags have been parsed.

N.B. Do not delete this function. `glog` is a persnickity package and wants to insist that you parse flags before doing any logging, which is a totally reasonable thing (for example, if you log something at DEBUG before parsing the flag that tells you to only log at WARN or greater).

However, `glog` also "insists" that you use the standard library to parse (by checking `flag.Parsed()`), which doesn't cover cases where `glog` flags get installed on some other parsing package, in our case pflag, and therefore are actually being parsed before logging. This is incredibly annoying, because all log lines end up prefixed with:

> "ERROR: logging before flag.Parse"

So, we include this little shim to trick `glog` into (correctly, I must add!!!!) realizing that CLI arguments have indeed been parsed. Then, we put os.Args back in their rightful place, so the parsing we actually want to do can proceed as usual.

func Usage

func Usage()

Usage invokes the current CommandLine's Usage func, or if not overridden, "prints a simple header and calls PrintDefaults".

Types

type UsageOptions

type UsageOptions struct {
	// Preface determines the beginning of the help text, before flag usages
	// and defaults. If this function is nil, the Usage will print "Usage of <os.Args[0]:\n".
	Preface func(w io.Writer)
	// Epilogue optionally prints text after the flag usages and defaults. If
	// this function is nil, the flag usage/defaults will be the end of the
	// Usage text.
	Epilogue func(w io.Writer)
	// FlagFilter allows certain flags to be omitted from the flag usage and
	// defaults. If non-nil, flags for which this function returns false are
	// omitted.
	FlagFilter func(f *goflag.Flag) bool
}

UsageOptions controls the custom behavior when overriding the Usage for a FlagSet.