module

Shell::AutoComplete

Constants

SHARDS_PROJECT_VERSION = "2.6.1"

The version of the project being compiled — not this shard's own, which is VERSION above. It is the last-resort fallback for --version when a command has no tool_version and no VERSION constant in scope.

Captured once, here, because shards version is a subprocess run during macro expansion: two independent invocations in one compile read shard.yml at two different moments, and disagree if the file changes in between — which is exactly what happens while cutting a release. Every consumer, Command.version_string and the specs alike, reads this constant so the value cannot differ within a build.

VERSION = "2.6.1"

Macros

command(type, **opts, &block)

Defines a command class. parent: names another command class to inherit from (issue #22): the new command gains every flag the parent declares — properties, parsing, help (under an "Inherited options" heading), and completion — and may redeclare one with override: true. Routing is still declared separately with subcommand on the parent, so inheritance and routing compose but neither implies the other.

Source
common_flag(name, decl, *flag_strings, **opts)

Defines a named, reusable flag in a catalog, outside any command. Pull selected entries into a command with import_flags. The flag expands in the importing command's own context, so it registers in that command's name registry, participates in duplicate detection and override:, and appears in that command's help and completion exactly as a directly declared flag would. Different commands can import different subsets of the catalog.

Shell::AutoComplete.common_flag :format,
  format : String?, "--format", "Pretty-print with a Go template", placeholder: "TEMPLATE"
Shell::AutoComplete.common_flag :quiet,
  quiet : Bool = false, "--quiet", "-q", "Only display IDs"

Shell::AutoComplete.command Ps, name: "ps", description: "List containers" do
  import_flags :format, :quiet

  def run
    ...
  end
end

Implemented as a macro that defines a uniquely-named macro per catalog entry; import_flags invokes those, so the catalogued declaration is replayed verbatim — type, default, spellings, and options — in each importing command.

Source

Nested types