Documentation
¶
Overview ¶
Package flags pkg/flags/cloud.go c0-com-util
The cloud in the rain.
On a terminal wide enough to have room to spare beside the help text, the Skycoin cloud appears in it — not drawn over the rain but made of it. Cells inside the silhouette are lit to a dim floor with the glyph the rain already holds at that position, so the mark is the same alphabet scrambling in the same streams, and the streams still fall visibly brighter through it.
Brightening the rain that was already there does not work, and the reason is worth keeping: the rain is mostly gaps and its streams are vertical, so scaling only the lit cells traces the streams rather than the shape. Filling the silhouette to a floor is what makes it findable.
The shape is Skycoin's own, from the logo skycoin/skycoin serves in its block explorer — a cloud cut by diagonal slashes. The slashes are what distinguish it from any other cloud, and they are also what costs the resolution: see gencloud for why there is no small variant.
It costs nothing when there is no room. The whole thing is gated on width: the help text is wrapped to a hardcoded 80 columns (see HelpWidth), which is what makes "everything past column 86 is free" a fact rather than a guess, and below that width the mask hands every cell back exactly as the rain had it.
Package flags pkg/flags/cmdblock.go c0-com-util
The subcommand listing, rendered here for the same reason the flag block is — cobra pads the name into a column and then appends the Short description with no idea how much room is left. A command with a long Short runs off the right edge and the terminal folds it back to column zero, where it lines up under the command names and reads as another command.
Package flags pkg/flags/flagblock.go c0-com-util
The flag block of the help screen, rendered here rather than by pflag.FlagUsages, for three reasons that all come back to the same one: the help screen is read in a terminal, and pflag's renderer does not know how wide one is.
It wraps. cobra asks pflag for FlagUsages(), which is FlagUsagesWrapped(0) — zero meaning "do not wrap". A long description therefore runs off the right edge of an 80-column terminal and is folded by the terminal itself, back to column zero, underneath the flag names where it reads as another flag.
It puts the default on its own line. pflag appends "(default x)" to the end of the description, which is where the eye is least likely to find it and where it is most likely to be the part that overflows.
It colors every line it emits. coloredcobra colors the block by splitting each line on runs of two-or-more spaces and expecting exactly three pieces; the moment a line does not have that shape the whole line goes uncolored. Wrapping makes that failure the common case rather than a rare one, since a continuation line has no flag name and so never has three pieces. See FlagBlock for the other two shapes it misses.
Package flags pkg/flags/flags.go c0-com-util
Package flags pkg/flags/helpall.go c0-com-util
InstallHelp replaces cobra's default (auto-generated) help subcommand with a flag-aware version that consolidates three previously-separate concerns — printing every subcommand's help in one pass, rendering the subcommand tree, and regenerating markdown docs — into the same `help` command users already reach for. Three mutually-exclusive mode flags (-r / -t / -d) pick between the variants.
Why not a separate `help-all`? `help` already exists at every level of a cobra tree, invocation is universally understood, and overloading it avoids cluttering the top-level command list with a near-duplicate.
Package flags pkg/flags/rain.go
InitRain prints the help screen over a still frame of the Matrix code rain, seeded from the clock so it is different every time. It is decoration and nothing else, and it is confined to the one screen where decoration costs nothing: help is printed once, read, and scrolled past. Nothing parses it.
It is off in every case where the output is not a person reading a terminal — see rainOptions.
Package flags pkg/flags/seckey.go c0-com-util
Secret keys given on the command line are visible to every other process on the machine — `ps` shows a full argv — and they land in shell history. The repository already has the file to keep one in: the skyenv file that `skywire autoconfig` writes, whose SK entry is the visor's own key. This fills an unset secret-key flag from it.
Opt-in, by design. The fallback applies only when SKYENV names a file, not whenever /etc/skywire.conf happens to exist, because adopting the visor's key automatically would be the wrong default in a way that is hard to see: two dmsg clients sharing a public key race for one dmsg-discovery entry. dmsgpty-host's --sk-from-visor refuses that combination outright for the same reason. Setting SKYENV is the operator saying "this file is my identity", which is exactly when it is what they want.
Index ¶
- Constants
- func CmdRow(name, short string, pad int) string
- func FlagBlock(fs *pflag.FlagSet) string
- func InitFlags(cmd *cobra.Command, usage bool)
- func InitRain(cmd *cobra.Command)
- func InitStyle(cmd *cobra.Command)
- func InstallHelp(root *cobra.Command)
- func InstallHelpTree(root *cobra.Command)
- func PrintCommandDocs(root *cobra.Command)
- func PrintCommandTree(root *cobra.Command)
- func PrintHelpAll(root *cobra.Command, recursive bool)
- func WithPlainHelp(fn func())
Constants ¶
const HelpWidth = 80
HelpWidth is the column the flag block wraps at.
Hardcoded rather than read from the terminal, deliberately. Help output is piped, redirected into bug reports, captured into golden files and read back on a different terminal than it was produced on; a width that changes with the window makes all of those differ for no reason the reader can see. 80 is the width every terminal still opens at.
const NoRainEnv = "SKYWIRE_NO_HELP_RAIN"
NoRainEnv turns the backdrop off while leaving the help colored. NO_COLOR turns off both, which is what NO_COLOR is for; this is for someone who wants the colors and not the rain.
Variables ¶
This section is empty.
Functions ¶
func CmdRow ¶
CmdRow renders one line of a subcommand listing: the name in its column, the short description wrapped into the rest of the width and indented to stay in its own column.
mux-bw Multiplexed-route bandwidth + queueing-delay probe
(human output by default)
pad is cobra's .NamePadding — the longest sibling name, or 11, whichever is larger — so every row in a listing lines up.
Coloring is done here, per emitted line, rather than by coloredcobra's template rewriting. cc matches `{{rpad .Name .NamePadding}}` in the template text and wraps it in a style function, which forces the template to pad by `.NamePadding + 12` to make room for escape codes the padding would otherwise count as visible characters. Doing both here means the width arithmetic is done on plain strings, where it is simply the length.
func FlagBlock ¶
FlagBlock renders fs as the Flags: section of a help screen.
The shape, for a flag whose description does not fit:
-j, --jq string filter JSON output through a jq/gojq
expression (implies --json)
(default "none")
Colors are applied per emitted line rather than per matched substring, which is what makes them survive. The three shapes coloredcobra's split misses are a continuation line (no flag name, so two pieces not three), a description containing a run of two or more spaces (four pieces), and a description mentioning a --flag of its own — that last one gets colored as if it were the flag being described, and the reset that ends it also ends the description color, leaving the rest of the line bare. Emitting the color around whole lines here means there is nothing inside to terminate it.
func InitRain ¶
InitRain makes cmd, and every command under it, print its help over the code rain.
Call it on the root, and call it once the tree is assembled: it walks the commands rather than leaving cobra's inheritance to carry the help function down, so a subcommand added afterwards gets the backdrop only by inheritance and only if nothing in its own subtree installs a help function. See eachDeepestFirst.
Deliberately not part of InitFlags. That runs for every binary in this repository, including the services, and this is meant for the one people read help in.
func InitStyle ¶
InitStyle sets the usage + help templates and runs coloredcobra on cmd WITHOUT adding flags or a help command. Use this for subcommand roots (like scli.RootCmd when embedded under the skywire binary) that need colors but already inherit --help from their parent.
func InstallHelp ¶
InstallHelp installs a flag-aware help command on root. Replaces cobra's auto-generated help command for that scope. Safe to call on multiple roots — each gets its own closure-captured flag state.
Modes (mutually exclusive):
(default) print root's help (or [command]'s if an arg is given) -r/--recursive print root + every descendant's help -t/--tree print the subcommand tree only (no help text) -d/--doc print markdown documentation
With an argument (`cmd help <subcmd>`), the flags apply to the named subcommand's subtree rather than the root's, matching the intuition of `help <subcmd>`.
func InstallHelpTree ¶
InstallHelpTree installs the flag-aware `help` on root and on every command beneath it that has subcommands of its own.
Without it, `help` is a real command only on the few roots InstallHelp was called on, and at any greater depth it only appears to work: cobra prints a command's help for any argument it cannot resolve, so `visor help` and `visor zzzz` are the same code path. The flags are the tell — `visor help -t` fails with "unknown shorthand flag: 't'" because nothing is parsing them.
Descendants get it only if they have visible subcommands of their own. A leaf takes positional arguments, and giving it a `help` child would capture an argument that was meant for it; a parent that already prints help for an unrecognized argument loses nothing by having the word resolve properly instead. Root is exempt from that rule — a binary's own root gets `help` whether or not it has subcommands, which is what InstallHelp has always done for it.
That leaves the commands which are both a parent and runnable, where the word is genuinely ambiguous, and the answer there is the POSIX one rather than a special case: `cmd -- help` passes it through as an argument. Cobra stops looking for subcommands at `--` (stripFlags breaks out of its loop), so the argument reaches the command and is rejected or used on its own terms. Sniffing for args[0] == "help" somewhere instead would claim the word just as firmly, only in a place with no flags parsed and no way to opt out.
Call it once the tree is assembled, and before anything that wraps help functions (InitRain, tui.Install), so the commands it adds are wrapped too.
func PrintCommandDocs ¶
PrintCommandDocs emits a Markdown document describing every command in the tree rooted at root. Headings deepen with nesting (root = H1, direct children = H2, etc.), capped at H6 to stay within CommonMark. The help text is wrapped in fenced code blocks.
func PrintCommandTree ¶
PrintCommandTree writes an ASCII tree of the command hierarchy rooted at root. Kept dependency-free (no pterm / tablewriter) so the utilities package stays lightweight.
func PrintHelpAll ¶
PrintHelpAll writes root.Help() followed by each subcommand's Help(). With recursive=true, every descendant is included.
Plain: this produces text to keep rather than to look at, and a frame of help-rain per command in the tree is not that. See withPlainHelp.
func WithPlainHelp ¶
func WithPlainHelp(fn func())
WithPlainHelp runs fn with the backdrop suppressed, and is what anything that captures help text rather than showing it should use.
The docs and recursive modes above are the obvious callers. The other is a program that renders help into a pane of its own — an interactive browser over the command tree — which wants cobra's help exactly as it is, colors and all, and will decide for itself what goes behind it.
Types ¶
This section is empty.
Source Files
Directories