/ 
Getopt-Pad-0.04
/ Getopt::Pad::Completion

NAME

Getopt::Pad::Completion - Shell completion scripts and their answers (internal)

DESCRIPTION

This module is internal to Getopt::Pad. It is not part of the public API and can change without notice. Programs use "GetOptions" in Getopt::Pad; this page is for people working on Getopt::Pad itself.

Both halves of shell completion for one spec. How users install and use completion is described in "SHELL COMPLETION" in Getopt::Pad.

The script

renderScript($shell) returns the bash or zsh script that --create-completions prints. The script is a thin function: on every tab press it runs the program again with the environment variable GETOPT_PAD_COMPLETE set to the shell name, GETOPT_PAD_COMPLETE_INDEX set to the index of the word under the cursor, and the words after the program name as arguments, and hands what the program prints to the shell.

The answer

When GETOPT_PAD_COMPLETE is set, GetOptions prints renderCandidates($words, $index) and exits instead of parsing. The answer is a directive line, files, dirs or none, telling the shell which of its own path completions to add, followed by one candidate per line.

The candidates come from replaying the words before the cursor through the spec: command names descend into a command's level, and options that take a value swallow the next word. They are, depending on the position:

  • the command names of the level;

  • the visible option spellings of the level, inherited options included, with --no-NAME for negatable options whose name is longer than one letter;

  • the values of an option's valid list (static or from its coderef); for a hash or objectlist option after the KEY= the user typed, for a csv option after the last comma;

  • the type's own path completion, through the directive.

METHODS

new(spec => $spec, programName => $name)

programName defaults to the file name of $0.

renderScript($shell)

The completion script for bash or zsh.

renderCandidates($words, $index), candidates($words, $index)

The answer as text, or as a list (directive first).

SHELLS, SHELL_VARIABLE, INDEX_VARIABLE

The supported shells and the names of the two environment variables.

SEE ALSO

"SHELL COMPLETION" in Getopt::Pad

AUTHOR

davenonymous <perl@davenonymous.com>

COPYRIGHT AND LICENSE

Copyright 2026 davenonymous

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.