cli

Documentation

Overview

Package cli implements sq's CLI. The spf13/cobra library provides the core command processing.

Although cobra provides excellent functionality, it has some issues. Most prominently, its documentation suggests reliance upon package-level constructs for initializing the command tree (bad for testing).

Thus, this cmd package deviates from cobra's suggested usage pattern by eliminating all pkg-level constructs (which makes testing easier).

All interaction with cobra should happen inside this package, or via the utility cli/cobraz package. That is to say, the spf13/cobra package should not be imported anywhere outside this package and cli/cobraz.

The entry point to this pkg is the Execute function.

Index

• Variables
• func Execute(ctx context.Context, stdin *os.File, stdout, stderr io.Writer, args []string) error
• func ExecuteWith(ctx context.Context, ru *run.Run, args []string) (err error)
• func FinishRunInit(ctx context.Context, ru *run.Run) error
• func PrintError(ctx context.Context, ru *run.Run, err error)
• func RegisterDefaultOpts(reg *options.Registry)
• type LogLevelOpt
  • func NewLogLevelOpt(key string, defaultVal slog.Level, usage, help string) LogLevelOpt
  • func (op LogLevelOpt) DefaultAny() any
  • func (op LogLevelOpt) Get(o options.Options) slog.Level
  • func (op LogLevelOpt) GetAny(o options.Options) any
  • func (op LogLevelOpt) Process(o options.Options) (options.Options, error)

Variables

var (
	OptLogEnabled = options.NewBool(
		"log",
		nil,
		false,
		"Enable logging",
		"Enable logging.",
	)

	OptLogFile = options.NewString(
		"log.file",
		nil,
		getDefaultLogFilePath(),
		nil,
		"Log file path",
		`Path to log file. Empty value disables logging.`,
	)

	OptLogLevel = NewLogLevelOpt(
		"log.level",
		slog.LevelDebug,
		`Log level, one of: DEBUG, INFO, WARN, ERROR`,
		"Log level, one of: DEBUG, INFO, WARN, ERROR.",
	)

	OptLogFormat = format.NewOpt(
		"log.format",
		nil,
		format.Text,
		func(f format.Format) error {
			if f == format.Text || f == format.JSON {
				return nil
			}

			return errz.Errorf("option {log.format} allows only %q or %q", format.Text, format.JSON)
		},
		"Log output format (text or json)",
		fmt.Sprintf(
			`Log output format. Allowed formats are %q (human-friendly) or %q.`, format.Text, format.JSON),
	)
)

var (
	OptPrintHeader = options.NewBool(
		"header",
		nil,
		true,
		"Print header row",
		`Controls whether a header row is printed. This applies only to certain formats,
such as "text" or "csv".`,
		options.TagOutput,
	)

	OptFormat = format.NewOpt(
		"format",
		&options.Flag{Short: 'f'},
		format.Text,
		nil,
		"Specify output format",
		`Specify the output format. Some formats are only implemented for a subset of
sq's commands. If the specified format is not available for a particular
command, sq falls back to "text". Available formats:

  text, csv, tsv, xlsx,
  json, jsona, jsonl,
  markdown, html, xlsx, xml, yaml, raw`,
	)

	OptErrorFormat = format.NewOpt(
		"error.format",
		nil,
		format.Text,
		func(f format.Format) error {
			if f == format.Text || f == format.JSON {
				return nil
			}

			return errz.Errorf("option {error.format} allows only %q or %q", format.Text, format.JSON)
		},
		"Error output format",
		fmt.Sprintf(`The format to output errors in. Allowed formats are %q or %q.`, format.Text, format.JSON),
	)

	OptErrorStack = options.NewBool(
		"error.stack",
		&options.Flag{Short: 'E'},
		false,
		"Print error stack trace to stderr",
		`Print error stack trace to stderr. This only applies when error.format is
"text"; when error.format is "json", the stack trace is always printed.`,
		options.TagOutput,
	)

	OptVerbose = options.NewBool(
		"verbose",
		&options.Flag{Short: 'v'},
		false,
		"Print verbose output",
		`Print verbose output.`,
		options.TagOutput,
	)

	OptMonochrome = options.NewBool(
		"monochrome",
		&options.Flag{Short: 'M'},
		false,
		"Don't print color output",
		`Don't print color output.`,
		options.TagOutput,
	)

	OptRedact = options.NewBool(
		"redact",
		&options.Flag{
			Name:   "no-redact",
			Invert: true,
			Usage:  "Don't redact passwords in output",
		},
		true,
		"Redact passwords in output",
		`Redact passwords in output.`,
		options.TagOutput,
	)

	OptDebugTrackMemory = options.NewDuration(
		"debug.stats.frequency",
		nil,
		0,
		"Memory usage sampling interval.",
		`Memory usage sampling interval. If non-zero, peak memory usage is periodically
sampled, and reported on exit. If zero, memory usage sampling is disabled.`,
	)

	OptCompact = options.NewBool(
		"compact",
		&options.Flag{Short: 'c'},
		false,
		"Compact instead of pretty-printed output",
		`Compact instead of pretty-printed output.`,
		options.TagOutput,
	)

	OptDatetimeFormat = options.NewString(
		"format.datetime",
		nil,
		"RFC3339",
		nil,
		"Timestamp format: constant such as RFC3339 or a strftime format",
		`Timestamp format. This can be one of several predefined constants such as
"RFC3339" or "Unix", or a strftime format such as "%Y-%m-%d %H:%M:%S".

`+timeLayoutsList,
		options.TagOutput,
	)

	OptDatetimeFormatAsNumber = options.NewBool(
		"format.datetime.number",
		nil,
		true,
		"Render numeric datetime value as number instead of string",
		`Render numeric datetime value as number instead of string, if possible. If
format.datetime renders a numeric value (e.g. a Unix timestamp such as
"1591843854"), that value is typically rendered as a string. For some output
formats, such as JSON, it can be useful to instead render the value as a naked
number instead of a string. Note that this option is no-op if the rendered value
is not an integer.

  format.datetime.number=false
  [{"first_name":"PENELOPE","last_update":"1591843854"}]
  format.datetime.number=true
  [{"first_name":"PENELOPE","last_update":1591843854}]
`,
		options.TagOutput,
	)

	OptDateFormat = options.NewString(
		"format.date",
		nil,
		"DateOnly",
		nil,
		"Date format: constant such as DateOnly or a strftime format",
		`Date format. This can be one of several predefined constants such as "DateOnly"
or "Unix", or a strftime format such as "%Y-%m-%d". Note that date values are
sometimes programmatically indistinguishable from datetime values. In that
situation, use format.datetime instead.

`+timeLayoutsList,
		options.TagOutput,
	)

	OptDateFormatAsNumber = options.NewBool(
		"format.date.number",
		nil,
		true,
		"Render numeric date value as number instead of string",
		`Render numeric date value as number instead of string, if possible. If
format.date renders a numeric value (e.g. a year such as "1979"), that value is
typically rendered as a string. For some output formats, such as JSON, it can be
useful to instead render the value as a naked number instead of a string. Note
that this option is no-op if the rendered value is not an integer.

  format.date.number=false
  [{"first_name":"PENELOPE","birth_year":"1979"}]
  format.date.number=true
  [{"first_name":"PENELOPE","birth_year":1979}]
`,
		options.TagOutput,
	)

	OptTimeFormat = options.NewString(
		"format.time",
		nil,
		"TimeOnly",
		nil,
		"Time format: constant such as TimeOnly or a strftime format",
		`Time format. This can be one of several predefined constants such as "TimeOnly"
or "Unix", or a strftime format such as "%Y-%m-%d". Note that time values are
sometimes programmatically indistinguishable from datetime values. In that
situation, use format.datetime instead.

`+timeLayoutsList,
		options.TagOutput,
	)

	OptTimeFormatAsNumber = options.NewBool(
		"format.time.number",
		nil,
		true,
		"Render numeric time value as number instead of string",
		`Render numeric time value as number instead of string, if possible. If format.time
renders a numeric value (e.g. "59"), that value is typically rendered as a string.
For some output formats, such as JSON, it can be useful to instead render the
value as a naked number instead of a string. Note that this option is no-op if
the rendered value is not an integer.

  format.time.number=false
  [{"first_name":"PENELOPE","favorite_minute":"59"}]
  format.time.number=true
  [{"first_name":"PENELOPE","favorite_minute":59}]
`,
		options.TagOutput,
	)
)

var OptDiffDataFormat = format.NewOpt(
	"diff.data.format",
	&options.Flag{Name: "format", Short: 'f'},
	format.Text,
	func(f format.Format) error {
		switch f {
		case format.Text, format.CSV, format.TSV,
			format.JSON, format.JSONA, format.JSONL,
			format.Markdown, format.HTML, format.XML, format.YAML:
			return nil
		default:
			return errz.Errorf("diff does not support output format {%s}", f)
		}
	},
	"Output format (json, csv…) when comparing data",
	`Specify the output format to use when comparing table data.

Available formats:

  text, csv, tsv,
  json, jsona, jsonl,
  markdown, html, xml, yaml`,
)

var OptDiffHunkMaxSize = options.NewInt(
	"diff.max-hunk-size",
	nil,
	5000,
	"Maximum size of individual diff hunks",
	`Maximum size of individual diff hunks. A hunk is a segment of a diff that
contains differing lines, as well as non-differing context lines before and
after the difference. A hunk must be loaded into memory in its entirety; this
setting prevents excessive memory usage. If a hunk would exceed this limit, it
is split into multiple hunks; this still produces a well-formed diff.`,
	options.TagOutput,
)

var OptDiffNumLines = options.NewInt(
	"diff.lines",
	&options.Flag{Name: "unified", Short: 'U'},
	3,
	"Generate diffs with <n> lines of context",
	`Generate diffs with <n> lines of context, where n >= 0.`,
	options.TagOutput,
)

var OptDiffStopAfter = options.NewInt(
	"diff.stop",
	&options.Flag{Name: "stop", Short: 'n'},
	3,
	"Stop after <n> differences",
	`Stop after <n> differences are found. If n <= 0, no limit is applied.`,
	options.TagOutput,
)

var OptPingCmdTimeout = options.NewDuration(
	"ping.timeout",
	nil,
	time.Second*10,
	"ping command timeout duration",
	"How long the ping command waits before timeout occurs. Example: 500ms or 2m10s.",
)

OptPingCmdTimeout controls timeout for the ping command. This timeout applies only to the "sq ping" command: this is a different value from driver.OptConnOpenTimeout, which applies to generic ping operations.

var OptProgress = options.NewBool(
	"progress",
	&options.Flag{
		Name:   "no-progress",
		Invert: true,
		Usage:  "Don't show progress bar",
	},
	true,
	"Show progress bar",
	`Show progress bar for long-running operations.`,
	options.TagOutput,
)

var OptProgressDelay = options.NewDuration(
	"progress.delay",
	nil,
	time.Second*2,
	"Progress bar render delay",
	`Delay before showing a progress bar.`,
	options.TagOutput,
)

var OptProgressMaxBars = options.NewInt(
	"progress.max-bars",
	nil,
	progress.DefaultMaxBars,
	"Max concurrent progress bars shown in terminal",
	`Limit the number of progress bars shown concurrently in the terminal. When the
threshold is reached, further progress bars are grouped into a single group bar.
If zero, no progress bar is rendered.`,

	options.TagOutput,
)

var OptShellCompletionGroupFilter = options.NewBool(
	"shell-completion.group-filter",
	nil,
	true,
	"Shell completion initial source suggestions from active group only",
	`When true, shell completion initially suggests only sources within the active
group. When false, all sources are suggested. However, note that if the user
continues to input a source handle that is outside the active group, completion
will suggest all matching sources, regardless of this option's value.`,
)

var OptShellCompletionLog = options.NewBool(
	"shell-completion.log",
	nil,
	false,
	"Enable logging of shell completion activity",
	`Enable logging of shell completion activity. This is really only useful for
debugging shell completion functionality. It's disabled by default, because it's
frequently the case that shell completion handlers will trigger work (such as
inspecting the schema) that doesn't complete by the shell completion timeout.
This can result in the logs being filled with uninteresting junk when the
timeout triggers logging of errors.`,
)

var OptShellCompletionTimeout = options.NewDuration(
	"shell-completion.timeout",
	nil,
	time.Millisecond*500,
	"Shell completion timeout",
	`How long shell completion should wait before giving up. This can become relevant
when shell completion inspects a source's metadata, e.g. to offer a list of
tables in a source.`,
)

Functions

func Execute

func Execute(ctx context.Context, stdin *os.File, stdout, stderr io.Writer, args []string) error

Execute builds a Run using ctx and default settings, and invokes ExecuteWith.

func ExecuteWith

func ExecuteWith(ctx context.Context, ru *run.Run, args []string) (err error)

ExecuteWith invokes the cobra CLI framework, ultimately resulting in a command being executed. This function always closes ru.

func FinishRunInit

func FinishRunInit(ctx context.Context, ru *run.Run) error

FinishRunInit finishes setting up ru.

TODO: This run.Run initialization mechanism is a bit of a mess. There's logic in newRun, preRun, FinishRunInit, as well as testh.Helper.init. Surely the init logic can be consolidated.

func PrintError

func PrintError(ctx context.Context, ru *run.Run, err error)

PrintError is the centralized function for printing and logging errors. This func has a lot of (possibly needless) redundancy; ultimately err will print if non-nil (even if ctx, or ru, or any of ru's fields are nil).

func RegisterDefaultOpts

func RegisterDefaultOpts(reg *options.Registry)

RegisterDefaultOpts registers the options.Opt instances that the CLI knows about.

Types

type LogLevelOpt

type LogLevelOpt struct {
	options.BaseOpt
	// contains filtered or unexported fields
}

LogLevelOpt is an options.Opt for slog.Level.

func NewLogLevelOpt

func NewLogLevelOpt(key string, defaultVal slog.Level, usage, help string) LogLevelOpt

NewLogLevelOpt returns a new LogLevelOpt instance.

func (LogLevelOpt) DefaultAny

func (op LogLevelOpt) DefaultAny() any

DefaultAny implements options.Opt.

func (LogLevelOpt) Get

func (op LogLevelOpt) Get(o options.Options) slog.Level

Get returns op's value in o. If o is nil, or no value is set, op's default value is returned.

func (LogLevelOpt) GetAny

func (op LogLevelOpt) GetAny(o options.Options) any

GetAny implements options.Opt.

func (LogLevelOpt) Process

func (op LogLevelOpt) Process(o options.Options) (options.Options, error)

Process implements options.Processor. It converts matching string values in o into slog.Level. If no match found, the input arg is returned unchanged. Otherwise, a clone is returned.