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
- Variables
- func AddPageFlags(cmd *cobra.Command, pf *PageFlags, defaultPageSize, defaultMaxItems int)
- func CheckQuery(cmd *cobra.Command) error
- func Confirm(prompt string, yes bool) (bool, error)
- func Deref[T any](p *T) T
- func DerefOr[T any](p *T, fallback T) T
- func Format(cmd *cobra.Command) string
- func Human(cmd *cobra.Command) bool
- func Print(cmd *cobra.Command, value any) error
- func Renamed(cmd *cobra.Command, newPath string) *cobra.Command
- func Run(fn RunFunc) func(*cobra.Command, []string) error
- func Stderr(cmd *cobra.Command) io.Writer
- type FetchFunc
- type Page
- type PageFlags
- type RunFunc
Constants ¶
const AnnotationRenamedTo = "norcube/renamed-to"
AnnotationRenamedTo records where a renamed command moved.
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 ¶
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 ¶
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 ¶
CheckQuery fails with a usage error when --query doesn't parse, before the command does any work.
func Confirm ¶ added in v0.17.0
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 Human ¶
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 ¶
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
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.
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 ¶
Paginate fetches one page, or with --all-pages every page up to --max-items. Items is never nil, so an empty list prints as [].
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>.