Documentation
¶
Overview ¶
Package cliout renders skywire-cli command results.
A command produces ONE value. This package decides how it is written: as JSON for a machine, or as text for a person. That is the whole idea, and it is a correction of what came before — PrintOutput took a JSON value AND a pre-rendered human string as separate arguments, so nothing connected them. Two arguments describing one fact drift: `visor info` printed "DMSG Latency: 0s" from the human side while the JSON side carried the same unmeasured zero, because each was written on its own.
So the value renders itself. Its struct tags are the machine contract; its Human method is the terminal rendering of the same fields. Neither can be updated without the other being right there.
Shape ¶
The printer is one method over a writer, after kubernetes' ResourcePrinter (`PrintObj(runtime.Object, io.Writer) error`): a command hands over a value and never learns which format was chosen, so a new format is a new printer rather than an edit to 387 commands.
TTY handling follows gh: indented for a terminal, compact when piped, since the second case is a parser and the first is a person. gh reaches this through iostreams.IsStdoutTTY(); here the writer is inspected directly, to avoid threading a stream object through a CLI that does not have one yet.
Errors ¶
Print returns them. It does not exit. PrintFatalError's os.Exit(1) runs no deferred close, flush or unlock, and cannot be tested without a subprocess. A command's RunE returns the error and the root renders it once.
Package cliout pkg/cliout/filter.go
Output post-processors shared by every command that renders through Print, plus the flag registration and the --help --json hook so a single call wires them onto any root command (the top-level `skywire` binary and the standalone `skywire-cli` both need them):
--jq <filter> run the JSON value through gojq (already vendored) before
printing. Implies --json. Lets a caller pull one field out
of a large payload instead of dumping it.
--shape print the output type's SKELETON — every field at its zero
value, omitempty forced visible — instead of live data, so
the schema is discoverable without a populated response.
Index ¶
- Constants
- func ApplyJQ(src []byte, filter string) (string, error)
- func ApplyJQCompact(src []byte, filter string) ([]string, error)
- func Fprint(w io.Writer, jsonMode bool, v interface{}) error
- func IsTerminal(w io.Writer) bool
- func JQFilter(cmd *cobra.Command) string
- func JSONMode(cmd *cobra.Command) bool
- func MachineMode(cmd *cobra.Command) bool
- func Print(cmd *cobra.Command, v interface{}) error
- func RegisterOutputFlags(cmd *cobra.Command)
- func SetJSONHelp(root *cobra.Command)
- func ShapeMode(cmd *cobra.Command) bool
- func Skeleton(v interface{}) interface{}
- type Output
Constants ¶
const ( JQFlag = "jq" ShapeFlag = "shape" )
JQFlag / ShapeFlag are the persistent flags added by RegisterOutputFlags.
const JSONFlag = "json"
JSONFlag is the persistent flag that selects machine output.
Variables ¶
This section is empty.
Functions ¶
func ApplyJQ ¶
ApplyJQ runs filter over the JSON in src and returns the printed results (one per line). Object/array results are pretty-printed; scalars print as their JSON literal, matching jq's default (non -r) behavior.
func ApplyJQCompact ¶
ApplyJQCompact runs filter over the JSON in src and returns each result as a COMPACT (single-line) JSON string — the NDJSON-friendly counterpart of ApplyJQ, which pretty-prints. A filter that yields several values returns several strings (each a valid standalone JSON line). Used by streaming (`--watch`) callers so a filtered tick stays one line.
func Fprint ¶
Fprint is Print against an explicit writer, for callers that are not a cobra command — tests above all, which is the other thing the old helper made hard by writing to os.Stdout through fmt.Print.
func IsTerminal ¶
IsTerminal reports whether w is a character device, i.e. a person is probably reading it. Checking the file mode keeps this dependency-free; anything that is not an *os.File (a buffer in a test, a pipe) is not a terminal, which is the answer those callers want anyway.
func JSONMode ¶
JSONMode reports whether machine output was requested.
It searches the inherited flags too. The old helper called GetBool on the command's own set and discarded the error, so a command whose set did not carry the flag silently produced human text for `--json` — indistinguishable from the user not having asked.
func MachineMode ¶
MachineMode reports whether any machine-output flag was set, which is to say whether Help will print a schema for something else to consume rather than help for someone to read.
func Print ¶
Print writes v to the command's output in whichever format was asked for.
The value is the single source of truth: its json tags define the machine shape, its Human method (when it has one) the text.
func RegisterOutputFlags ¶
RegisterOutputFlags adds --json, --jq and --shape as persistent flags on cmd, so every subcommand inherits them. Call it once per root command.
func SetJSONHelp ¶
SetJSONHelp installs a help function on root that, in machine mode (--json/--jq/--shape), prints the command's machine-readable description (clihelp.Of) instead of the human help text. cobra hands the help function down to every child, so one call covers the whole tree.
func Skeleton ¶
func Skeleton(v interface{}) interface{}
Skeleton returns a shape skeleton for v's type: every exported field at its zero value, omitempty ignored so nothing is hidden. Types with a custom MarshalJSON (cipher.PubKey, time.Time, uuid.UUID, …) render as their zero marshaled form rather than being recursed into. Native-only (the CLI is never built under TinyGo), so reflect is fine here.
Types ¶
type Output ¶
type Output interface {
// Human writes the terminal rendering. Trailing newline included.
Human(w io.Writer) error
}
Output is a command result that can render itself for a person.
Implementing it is optional: a value without it still prints as JSON, and still prints in text mode via its Go representation, which is a reasonable last resort for a command whose result is a bare string or count.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cliconfig is the output shape of the `skywire cli config` commands.
|
Package cliconfig is the output shape of the `skywire cli config` commands. |
|
Package clihelp is the machine-readable shape of `skywire cli --help`.
|
Package clihelp is the machine-readable shape of `skywire cli --help`. |
|
Package clihv is the output shape of the `skywire cli hv` commands that return a value.
|
Package clihv is the output shape of the `skywire cli hv` commands that return a value. |
|
Package climdisc is the output shape of the `skywire cli mdisc` commands, which read the dmsg discovery.
|
Package climdisc is the output shape of the `skywire cli mdisc` commands, which read the dmsg discovery. |
|
Package cliproxy is the output shape of the `skywire cli proxy` commands.
|
Package cliproxy is the output shape of the `skywire cli proxy` commands. |
|
Package clirewards is the output shape of the `skywire cli rewards` commands, which collect the data the reward system is computed from.
|
Package clirewards is the output shape of the `skywire cli rewards` commands, which collect the data the reward system is computed from. |
|
Package cliroute is the output shape of the `skywire cli route` commands.
|
Package cliroute is the output shape of the `skywire cli route` commands. |
|
Package clisvc is the output shape of the `skywire cli svc` and `skywire cli resolver` commands.
|
Package clisvc is the output shape of the `skywire cli svc` and `skywire cli resolver` commands. |
|
Package clitp is the output shape of the `skywire cli tp` commands.
|
Package clitp is the output shape of the `skywire cli tp` commands. |
|
Package clitps is the output shape of the `skywire cli tps` commands, which manage the transport-setup-node key.
|
Package clitps is the output shape of the `skywire cli tps` commands, which manage the transport-setup-node key. |
|
Package clivisor is the output shape of the `skywire cli visor` commands.
|
Package clivisor is the output shape of the `skywire cli visor` commands. |