view release on metacpan or  search on metacpan

README  view on Meta::CPAN

NAME
    Complete::Getopt::Long - Complete command-line argument using
    Getopt::Long specification

VERSION
    This document describes version 0.481 of Complete::Getopt::Long (from
    Perl distribution Complete-Getopt-Long), released on 2022-08-28.

SYNOPSIS
    See Getopt::Long::Complete for an easy way to use this module.

DESCRIPTION
FUNCTIONS
  complete_cli_arg
    Usage:

     complete_cli_arg(%args) -> hash|array

    Complete command-line argument using Getopt::Long specification.

    This routine can complete option names, where the option names are
    retrieved from Getopt::Long specification. If you provide completion
    routine in "completion", you can also complete *option values* and
    *arguments*.

    Note that this routine does not use Getopt::Long (it does its own
    parsing) and currently is not affected by Getopt::Long's configuration.
    Its behavior mimics Getopt::Long under these configuration:
    "no_ignore_case", "bundling" (or "no_bundling" if the "bundling" option
    is turned off). Which I think is the sensible default. This routine also
    does not currently support "auto_help" and "auto_version", so you'll
    need to add those options specifically if you want to recognize
    "--help/-?" and "--version", respectively.

    This function is not exported by default, but exportable.

    Arguments ('*' denotes required arguments):

    *   bundling => *bool* (default: 1)

        If you turn off bundling, completion of short-letter options won't
        support bundling (e.g. "-b<tab>" won't add more single-letter
        options), but single-dash multiletter options can be recognized.
        Currently only those specified with a single dash will be completed.
        For example if you have "-foo=s" in your option specification,
        "-f<tab>" can complete it.

        This can be used to complete old-style programs, e.g. emacs which
        has options like "-nw", "-nbc" etc (but also have double-dash
        options like "--no-window-system" or "--no-blinking-cursor").

    *   completion => *code*

        Completion routine to complete option value/argument.

        Completion code will receive a hash of arguments (%args) containing
        these keys:

        *   "type" (str, what is being completed, either "optval", or "arg")

        *   "word" (str, word to be completed)

        *   "cword" (int, position of words in the words array, starts from
            0)

        *   "opt" (str, option name, e.g. "--str"; undef if we're completing
            argument)

        *   "ospec" (str, Getopt::Long option spec, e.g. "str|S=s"; undef
            when completing argument)

        *   "argpos" (int, argument position, zero-based; undef if
            type='optval')

        *   "nth" (int, the number of times this option has seen before,
            starts from 0 that means this is the first time this option has
            been seen; undef when type='arg')

        *   "seen_opts" (hash, all the options seen in "words")

        *   "parsed_opts" (hash, options parsed the standard/raw way)

        as well as all keys from "extras" (but these won't override the
        above keys).

        and is expected to return a completion answer structure as described
        in "Complete" which is either a hash or an array. The simplest form
        of answer is just to return an array of strings. The various
        "complete_*" function like those in Complete::Util or the other
        "Complete::*" modules are suitable to use here.

        Completion routine can also return undef to express declination, in
        which case the default completion routine will then be consulted.
        The default routine completes from shell environment variables
        ($FOO), Unix usernames ("~foo"), and files/directories.

        Example:

         use Complete::Unix qw(complete_user);
         use Complete::Util qw(complete_array_elem);
         complete_cli_arg(
             getopt_spec => [
                 'help|h'   => sub{...},
                 'format=s' => \$format,
                 'user=s'   => \$user,
             ],
             completion  => sub {
                 my %args  = @_;
                 my $word  = $args{word};
                 my $ospec = $args{ospec};