Shell::AutoComplete::Command

Raw, ordered log of every flag occurrence matched during parse: the spelling exactly as typed (dashes kept, aliases not canonicalized) and the raw value consumed from argv or after =, or nil when none was consumed (switches and forced-value shortcut flags). Positionals are not logged — they preserve their own order. Empty until parse runs.

Raw, ordered log of every flag occurrence matched during parse: the spelling exactly as typed (dashes kept, aliases not canonicalized) and the raw value consumed from argv or after =, or nil when none was consumed (switches and forced-value shortcut flags). Positionals are not logged — they preserve their own order. Empty until parse runs.

Registers a block to run on the parsed command instance after parsing and before run — for setup that must happen once before the command executes: resolving an inherited flag into shared state, opening a connection, configuring a global, or cross-flag validation a single flag's validator can't express.

Shell::AutoComplete.command Db, name: "db", description: "..." do
  flag dsn : String?, "--dsn", "Connection string"
  getter! pool : DB::Database

  before_run do
    target = dsn || ENV["DATABASE_URL"]?
    raise ArgumentError.new("no --dsn and DATABASE_URL is unset") unless target
    @pool = DB.open(target)
  end
end

Hooks are collected down the class hierarchy and run parent-first, so a parent:-derived subcommand inherits its base's hooks automatically without super. The block runs on the instance (all properties are in scope) and takes no arguments. An ArgumentError raised from it becomes a clean ParseError carrying the command path, the same as a parse-time failure. Hooks run during dispatch, only for the command whose run executes; multiple hooks in one class run in declaration order.

Declares a flag that captures a run of raw argv tokens into a collection, ending at a delimiter token (default --, discarded). Every token between the flag and the delimiter is appended verbatim, so flag-looking tokens in the captured run are taken literally:

Shell::AutoComplete.command Tool, name: "tool", description: "..." do
  delimited_flag command : Array(String), "--command", "Command to run"
  flag json : Bool = false, "--json", "JSON output"
end

# tool --command echo hello -- --json path
#   @command => ["echo", "hello"]
#   @json    => true          (parsing resumes after the delimiter)

The captured value is built by calling .new on the declared type and appending each token with <<(String), so the type only has to answer those two — Array(String), Set(String), or any custom type. Parsing resumes normally after the discarded delimiter, so a following --json is a flag, not a positional. If the delimiter never appears, capture runs to the end of argv. When the flag is absent the property holds an empty .new (or nil, if the declared type is nilable).

The delimiter is configurable with delimiter:. Only the space-separated capture form is supported; --command=x is not a delimited invocation.

external_command: true marks the captured value as an external command for completion: inside the capture, the shell completes the first word as a command name and the rest with that command's own completion (falling back to file completion). It does not change parsing.

Disables the automatic --version intercept for this command (and, via inheritance, its parent:-derived subcommands). Declaring a flag that claims the --version spelling disables the intercept on its own; this macro is for turning it off without claiming the spelling.

Adds a version subcommand that prints the same <name> <version> line as the --version flag.

Enables git-style external subcommands on a root command: when a subcommand word matches no declared subcommand, PATH is searched for an executable named <command_name>-<word>, and if found the current process is replaced (exec) with it, passing every argument after the subcommand word. No parameters are defined for the external command — it is a blind handoff, so anything after the word (flags included) goes through untouched.

Shell::AutoComplete.command Tool, name: "tool", description: "..." do
  external_subcommands
  subcommand Build
end

# tool build ...   -> the declared Build subcommand
# tool deploy a b  -> exec's `tool-deploy a b` if found on PATH

Declared subcommands always win over the PATH lookup. A word containing a path separator is never looked up (only a bare tool-<word> on PATH is), and when nothing is found the usual unknown subcommand error is raised.

search_path: restricts the lookup to a fixed, colon-separated list of directories instead of PATH. A relative entry is resolved against the directory holding the running binary (via Process.executable_path), so search_path: "commands:../lib/commands:/etc/tool/commands" for a binary at /opt/tool/bin/tool searches /opt/tool/bin/commands, /opt/tool/lib/commands, and /etc/tool/commands, in that order, regardless of the caller's PATH. Both the exec handoff and completion use it.

Only valid on a root command: declaring it on a parent:-derived command is a compile error, since the executable name is built from one tool prefix.

Imports named flags previously defined with Shell::AutoComplete.common_flag, replaying each catalogued flag declaration in this command's context. An unknown name is a compile error (undefined macro method).

Declares a group of value-taking long options whose occurrences are delivered, in command-line order, to the block — for rsync/tar-style tagged rule lists where interleaving between spellings is the semantics (--include a --exclude b --include c means exactly that sequence).

ordered_flag_group "Filter rules (applied in command-line order)",
  {"--include" => "PATTERN: include matching files",
   "--exclude" => "PATTERN: exclude matching files"} do |key, value|
  @rules << {key, value} # key arrives with "--" stripped
end

The block runs at parse time on the fresh instance, once per occurrence, in argv order — it should record into properties and do nothing else. An ArgumentError raised from the block converts to a clean ParseError carrying the matched spelling, giving these flags parse-time per-item validation. Group spellings register in the duplicate-name checker, render in help, and complete like any flag.

Override the default --shell-completion flag name for this command class. Place this inside a Shell::AutoComplete.command block before any flag declarations.

Sets the program name shown by --version (and the version subcommand). Defaults to the command's name, which itself defaults to the basename of PROGRAM_NAME. Read back via .version_name.

Sets the version string shown by --version (and the version subcommand), e.g. tool_version "1.0.0". When not set, the nearest VERSION constant visible from the command class (the class itself, its enclosing namespaces, the top level, or an inherited command) is used; failing that, Shell::AutoComplete::SHARDS_PROJECT_VERSION, the compiling project's version captured once at compile time. Read back via .version_string.