cmdutil

package
v0.18.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 29, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Overview

Package cmdutil is the one path from a command's result to stdout. A command returns its value; cmdutil applies --query and renders it in the format -o selected. stdout carries only that value: progress, hints and confirmations go to stderr.

Index

Constants

View Source
const AnnotationRenamedTo = "norcube/renamed-to"

AnnotationRenamedTo records where a renamed command moved.

View Source
const EnvDeprecationWarnings = "NORCUBE_DEPRECATION_WARNINGS"

EnvDeprecationWarnings turns on notes about renamed commands. Off by default until v1.0, so renames don't add noise to existing scripts.

Variables

View Source
var ErrCancelled = errors.New("cancelled by user")

ErrCancelled is returned by interactive helpers when the user dismisses a prompt. Commands report it as "Cancelled." instead of an error.

Functions

func AddPageFlags

func AddPageFlags(cmd *cobra.Command, pf *PageFlags, defaultPageSize, defaultMaxItems int)

AddPageFlags registers --page-size (alias --limit), --cursor, --all-pages and --max-items. A defaultPageSize of 0 means the API picks the page size, and --page-size isn't offered.

func CheckQuery

func CheckQuery(cmd *cobra.Command) error

CheckQuery fails with a usage error when --query doesn't parse, before the command does any work.

func Confirm added in v0.17.0

func Confirm(prompt string, yes bool) (bool, error)

Confirm asks a yes/no question. yes answers it without prompting; without a terminal it fails with a usage error that asks for --yes, so a script never deletes anything by accident.

func Deref added in v0.17.0

func Deref[T any](p *T) T

Deref returns *p, or the zero value for nil (generated API models use pointers for optional fields).

func DerefOr added in v0.17.0

func DerefOr[T any](p *T, fallback T) T

DerefOr returns *p, or fallback for nil.

func Format

func Format(cmd *cobra.Command) string

Format is the output format of the running command.

func Human

func Human(cmd *cobra.Command) bool

Human reports whether the output is for a person (table), so commands may add notes to stderr that a script wouldn't want.

func Print

func Print(cmd *cobra.Command, value any) error

Print renders value to the command's stdout. Tables page through $PAGER on a terminal unless --no-pager.

func Renamed added in v0.17.0

func Renamed(cmd *cobra.Command, newPath string) *cobra.Command

Renamed marks cmd as the old name of a command that moved to newPath (e.g. "norcube backup jobs list"). The old name keeps working but is hidden from help and the reference docs; with NORCUBE_DEPRECATION_WARNINGS=1 it prints a one-line note to stderr.

func Run

func Run(fn RunFunc) func(*cobra.Command, []string) error

Run adapts fn to cobra: the result goes through Print.

func Stderr

func Stderr(cmd *cobra.Command) io.Writer

Stderr is where progress, hints and confirmations go.

Types

type FetchFunc

type FetchFunc[T any] func(ctx context.Context, cursor string, pageSize int) (items []T, next string, err error)

FetchFunc gets one page starting at cursor ("" for the first).

type Page

type Page[T any] struct {
	Items []T
	// NextCursor continues where Items stop; empty on the last page.
	NextCursor string
	// Truncated: --all-pages stopped at the --max-items cap.
	Truncated bool
	Cap       int
}

Page is what Paginate collected.

func Paginate

func Paginate[T any](ctx context.Context, pf PageFlags, fetch FetchFunc[T]) (Page[T], error)

Paginate fetches one page, or with --all-pages every page up to --max-items. Items is never nil, so an empty list prints as [].

func (Page[T]) Note

func (p Page[T]) Note(cmd *cobra.Command)

Note writes the "more results" note for the page to stderr.

func (Page[T]) Print

func (p Page[T]) Print(cmd *cobra.Command, view any) error

Print prints the page's items through view (a table over them) and the "more results" note on stderr.

type PageFlags

type PageFlags struct {
	PageSize int
	Cursor   string
	AllPages bool
	MaxItems int
	// contains filtered or unexported fields
}

PageFlags are the pagination flags every list command takes.

Lists print as plain arrays (the JSON shape scripts already rely on); when more results exist the next cursor goes to stderr: a sentence on a table, `nextCursor=<cursor>` for json, yaml and text, so a script can capture it with 2>.

type RunFunc

type RunFunc func(cmd *cobra.Command, args []string) (any, error)

RunFunc is a command body that returns its result instead of printing. A nil result prints nothing (and is not "null").

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL