Scroll::CLI
Inherits Shell::AutoComplete::Command < Reference < Object
Constants
Compile-time flag-name registry (issue #10). The flag macro appends
every spelling a declaration produces (canonical, aliases, short form,
generated negations, enum shortcut switches) plus the owning property
name, and raises on collision. override: true tombstones the prior
owner's entries and records its property in OVERRIDDEN_FLAG_IVARS,
which every generator consults to skip the replaced declaration.
When the command inherits another command (parent: on the command
macro), the registries seed from the parent's completed registries —
interpolation re-parses the parent's array literal into fresh nodes,
so later macro-time mutation of the child's copy never touches the
parent. Inherited-vs-own collisions and override: true of an
inherited flag then fall out of the issue #10 logic unchanged.
Macro-time-readable list of this command's direct subcommand classes,
parallel to SUBCOMMANDS (which is built at runtime and so can't be
enumerated during macro expansion). The subcommand macro pushes each
class node here; dispatch reads it to learn subcommand flag arities
for routing past a subcommand-only flag (issue #22 follow-up).
Constructors
Class methods
Auto follows the display: color when STDERR is a terminal, unless NO_COLOR is set or $TERM says the terminal cannot show it.
Alternate names this command answers to when routed as a subcommand,
declared with aliases: on the command macro (e.g. aliases: ["mv", "rename"] on a move command). Each alias routes to this
command exactly as its canonical name does, is offered in completion,
and is listed beside the name in the parent's help. The canonical name
is not repeated here.
Generates the shell completion script. executable, when given, is the
command the generated callback invokes for __complete — pass an
absolute path so completion runs a specific binary regardless of PATH
(useful for a dev build); the command name still registers the
completion. Defaults to the command name.
Translate the shorthand tokens the parser has no notion of: a bare -N
(e.g. -20) into --lines N, and -c/-C into --color on/--color off.
Everything else is passed through untouched.
A completion callback (__complete <cword> <words...>, emitted by the
generated bash/zsh/fish wrappers) is passed through untouched. Rewriting one
token into two would shift every word after it without moving cword, so the
shell would be offered candidates for the wrong word.
Directories searched for external subcommands (external_subcommands).
With search_path: set, the configured entries are resolved once —
relative ones against the running binary's directory — so the lookup is
independent of PATH. Otherwise the PATH directories are used, git
style. Returns an empty list when the feature is off.
External subcommand names (the <word> in <command_name>-<word>)
discovered on the search path, prefix-filtered, deduplicated, in
search-path order. Used to offer external subcommands in completion.
Resolves an external subcommand word to an executable path, or nil. A
word with a path separator is never looked up. With search_path: the
configured dirs are scanned in order; otherwise PATH is used.
Builds this command's fully qualified path. With no parent_prefix
the command is the root, so its bare command_name is the whole path;
otherwise the parent's path is prepended (e.g. "hf scrape").
Resolves a token to a subcommand class by its canonical name or any
of its declared aliases:. A canonical-name match on any subcommand
wins over an alias match, so an alias can never shadow another
command's real name.
Parse a --size value into a byte count: an integer, or a decimal with a
1024-based suffix (100b, 1.1k, 2.5GiB).
Parse a --sort-by SPEC into a SortKey. A fully slash-delimited /.../
value is a PCRE2 regex; anything else must be a 1-based integer column.
The program name shown by --version and the version subcommand;
set with the tool_name macro (a TOOL_NAME constant, inherited
through parent:), defaulting to the command's name — itself
defaulting to the basename of PROGRAM_NAME.
The version string shown by --version and the version subcommand.
Resolution order: the tool_version macro's TOOL_VERSION constant
(inherited through parent:); then the nearest VERSION constant
visible from this class (the class itself, each enclosing namespace,
the top level, or an inherited command) — emitted as a plain
constant reference so Crystal's own lexical lookup picks the nearest
one; finally the project's shards version, captured at compile
time.
Instance methods
Run the cross-flag rules after parsing, before run. As a hook they cannot
be forgotten by a future entry point the way an explicit call at the top of
run can.
Path-typed, so the generated completions delegate to the shell's own filesystem completion for this flag's value.
Path-typed, so the generated completions delegate to the shell's own filesystem completion for this flag's value.
True when following a file. Passed to Runner as the "mode implies null" input so file mode is silent on STDOUT unless --no-null re-enables teeing.
Whether the named flag (by declaration name) was explicitly given on
the command line, under any of its spellings: canonical, aliases,
short form, generated --no- negations, and enum shortcut switches.
Distinguishes an explicit value (even one equal to the default, or an
explicit --no-x) from the flag being left untouched.
Bool predicates, so the rest of the codebase reads config.force? rather
than the plain property the macro generates.
A Path rather than a String so the shells complete it as a filename; any string is a valid Path, so an arbitrary label still parses.
A Path rather than a String so the shells complete it as a filename; any string is a valid Path, so an arbitrary label still parses.
Tri-state: unset (nil), --null (true), --no-null (false). Resolved in Runner against any mode that implies null, so --no-null can override --file.
Tri-state: unset (nil), --null (true), --no-null (false). Resolved in Runner against any mode that implies null, so --no-null can override --file.
Invokes every before_run hook in the class hierarchy, parent-first,
on this instance. Called by dispatch between parse and run.
The three size options all turn --progress on, the way --sort-by turns on --sort: naming a size is only useful to the progress line.
The three size options all turn --progress on, the way --sort-by turns on --sort: naming a size is only useful to the progress line.
Tri-state, like --null: nil asks the terminal what it is, true and false settle it without asking. --no-terminal-progress therefore also means "do not query the terminal at all".
Tri-state, like --null: nil asks the terminal what it is, true and false settle it without asking. --no-terminal-progress therefore also means "do not query the terminal at all".
Cross-flag rules the per-flag types cannot express. Raises ParseError so
dispatch reports it the same way it reports a bad flag value.