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) error
• func FinishRunInit(ctx context.Context, ru *run.Run) 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",
		"",
		0,
		false,
		"Enable logging",
		"Enable logging.",
	)

	OptLogFile = options.NewString(
		"log.file",
		"",
		0,
		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.",
	)
)

var (
	OptPrintHeader = options.NewBool(
		"header",
		"",
		0,
		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",
		"format",
		'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",
		"",
		0,
		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),
	)

	OptVerbose = options.NewBool(
		"verbose",
		"",
		'v',
		false,
		"Print verbose output",
		`Print verbose output.`,
		options.TagOutput,
	)

	OptMonochrome = options.NewBool(
		"monochrome",
		"",
		'M',
		false,
		"Don't print color output",
		`Don't print color output.`,
		options.TagOutput,
	)

	OptCompact = options.NewBool(
		"compact",
		"",
		'c',
		false,
		"Compact instead of pretty-printed output",
		`Compact instead of pretty-printed output.`,
		options.TagOutput,
	)

	OptTuningFlushThreshold = options.NewInt(
		"tuning.flush-threshold",
		"",
		0,
		1000,
		"Output writer buffer flush threshold in bytes",
		`Size in bytes after which output writers should flush any internal buffer.
Generally, it is not necessary to fiddle this knob.`,
		options.TagTuning,
	)

	OptDatetimeFormat = options.NewString(
		"format.datetime",
		"",
		0,
		"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",
		"",
		0,
		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",
		"",
		0,
		"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",
		"",
		0,
		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",
		"",
		0,
		"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",
		"",
		0,
		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",
	"format",
	'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 OptDiffNumLines = options.NewInt(
	"diff.lines",
	"unified",
	'U',
	3,
	"Generate diffs with <n> lines of context",
	`Generate diffs with <n> lines of context, where n >= 0.`,
	options.TagOutput,
)

var OptPingCmdTimeout = options.NewDuration(
	"ping.timeout",
	"",
	0,
	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 OptShellCompletionTimeout = options.NewDuration(
	"shell-completion.timeout",
	"",
	0,
	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.`,
)

OptShellCompletionTimeout determines how long to wait until for long-running shell completion operations (such as fetching table names from a DB) before giving up.

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) error

ExecuteWith invokes the cobra CLI framework, ultimately resulting in a command being executed. The caller must invoke ru.Close.

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 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.