NAME
    Getopt::Long::Complete - A drop-in replacement for Getopt::Long, with
    shell tab completion

VERSION
    This document describes version 0.316 of Getopt::Long::Complete (from
    Perl distribution Getopt-Long-Complete), released on 2021-08-24.

SYNOPSIS
  First example (simple)
    You just replace "use Getopt::Long" with "use Getopt::Long::Complete"
    and your program suddenly supports tab completion. This works for
    most/many programs (see "INCOMPATIBILITIES". For example, below is
    source code for "delete-user".

     use Getopt::Long::Complete;
     my %opts;
     GetOptions(
         'help|h'     => sub { ... },
         'on-fail=s'  => \$opts{on_fail},
         'user|U=s'   => \$opts{name},
         'force'      => \$opts{force},
         'verbose!'   => \$opts{verbose},
     );

    Several shells are supported. To activate completion, see "DESCRIPTION".
    After activation, tab completion works:

     % delete-user <tab>
     --force --help --noverbose --no-verbose --on-fail --user --verbose -h
     % delete-user --h<tab>

  Second example (additional completion)
    The previous example only provides completion for option names. To
    provide completion for option values as well as arguments, you need to
    provide more hints. Instead of "GetOptions", use
    "GetOptionsWithCompletion". It's basically the same as "GetOptions" but
    accepts an extra coderef in the first argument. The code will be invoked
    when completion to option value or argument is needed. Example:

     use Getopt::Long::Complete qw(GetOptionsWithCompletion);
     use Complete::Unix qw(complete_user);
     use Complete::Util qw(complete_array_elem);
     my %opts;
     GetOptionsWithCompletion(
         sub {
             my %args  = @_;
             my $word  = $args{word}; # the word to be completed
             my $type  = $args{type}; # 'optname', 'optval', or 'arg'
             my $opt   = $args{opt}; # can be an array of options if ambiguous, e.g. ['--on-fail', '--on-full']
             if ($type eq 'optval' && $opt eq '--on-fail') {
                 return complete_array_elem(array=>[qw/die warn ignore/], word=>$word);
             } elsif ($type eq 'optval' && ($opt eq '--user' || $opt eq '-U')) {
                 return complete_user(word=>$word);
             } elsif ($type eq 'arg') {
                 return complete_user(word=>$word);
             }
             [];
         },
         'help|h'     => sub { ... },
         'on-fail=s'  => \$opts{on_fail},
         'user=s'     => \$opts{name},
         'force'      => \$opts{force},
         'verbose!'   => \$opts{verbose},
     );

DESCRIPTION
    This module provides a quick and easy way to add shell tab completion
    feature to your scripts, including scripts already written using the
    venerable Getopt::Long module. Currently bash and tcsh are directly
    supported; fish and zsh are also supported via shcompgen.

    This module is basically just a thin wrapper for Getopt::Long. Its
    "GetOptions" function just checks for COMP_LINE/COMP_POINT environment
    variable (in the case of bash) or COMMAND_LINE (in the case of tcsh)
    before passing its arguments to "Getopt::Long"'s "GetOptions". If those
    environment variable(s) are defined, completion reply will be printed to
    STDOUT and then the program will exit. Otherwise, Getopt::Long's
    GetOptions is called.

    To keep completion quick, you should do "GetOptions()" or
    "GetOptionsWithCompletion()" as early as possible in your script.
    Preferably before loading lots of other Perl modules.

    To activate tab completion in bash, put your script somewhere in "PATH"
    and execute this in the shell or put it into your bash startup file
    (e.g. "/etc/bash.bashrc" or "~/.bashrc"). Replace "delete-user" with the
    actual script name:

     complete -C delete-user delete-user

    For tcsh:

     complete delete-user 'p/*/`delete-user`/'

    For other shells (but actually for bash too) you can use shcompgen.

VARIABLES
    Because we are "bound" by providing a Getopt::Long-compatible function
    interface, these variables exist to allow configuring
    Getopt::Long::GetOptions. You can use Perl's "local" to localize the
    effect.

  $opt_permute
    Bool. Default: 1 (or 0 if POSIXLY_CORRECT). Not exported.

  $opt_pass_through
    Bool. Default: 0. Not exported.

  $opt_bundling
    Bool. Default: 1. Not exported.

  $REQUIRE_ORDER
    Integer. Constant. Value is 0. Exported by default, to be compatible
    with Getopt::Long.

  $PERMUTE
    Integer. Constant. Value is 1. Exported by default, to be compatible
    with Getopt::Long.

  $RETURN_IN_ORDER
    Integer. Constant. Value is 2. Exported by default, to be compatible
    with Getopt::Long.

INCOMPATIBILITIES
    Getopt::Long::Complete (GLC) provides all the same exports as
    Getopt::Long (GL), for example "GetOptions" (exported by default),
    "GetOptionsFromArray", "Configure", etc.

    Aside from GetOptions which has an extra behavior to support completion,
    all the other routines of GLC behave exactly the same as GL.

    However, there are some incompatibilities or unsupported features:

    *   GLC does not allow passing configure options during import

    *   GLC's GetOptions only supports running under a specific set of
        modes: "bundling", "no_ignore_case".

        Other non-default settings have not been tested and probably not
        supported.

FUNCTIONS
  GetOptions
    Usage:

     GetOptions([ \%hash, ] @spec)

    Exported by default. Will call Getopt::Long's GetOptions, except when
    COMP_LINE environment variable is defined, in which case will print
    completion reply to STDOUT and exit.

    Note: Will temporarily set Getopt::Long configuration as follow:
    bundling, no_ignore_case, gnu_compat, no_getopt_compat, permute (if
    POSIXLY_CORRECT environment is false). I believe this a sane default.
    You can turn off bundling via $opt_bundling. You can turn on/off permute
    explicitly by via $opt_permute. You can turn on pass_through via
    $opt_pass_through.

  GetOptionsWithCompletion
    Usage:

     GetOptionsWithCompletion(\&completion, [ \%hash, ] @spec)

    Exported on demand. Just like "GetOptions", except that it accepts an
    extra first argument "\&completion" containing completion routine for
    completing option *values* and arguments. This will be passed as
    "completion" argument to Complete::Getopt::Long's "complete_cli_arg".
    See that module's documentation on details of what is passed to the
    routine and what return value is expected from it.

  GetOptionsFromArray
    Exported on demand. Will just call Getopt::Long's version.

  GetOptionsFromString
    Exported on demand. Will just call Getopt::Long's version.

  Configure
    Exported on demand. Will just call Getopt::Long's version.

  HelpMessage
    Exported on demand. Will just call Getopt::Long's version.

  VersionMessage
    Exported on demand. Will just call Getopt::Long's version.

HOMEPAGE
    Please visit the project's homepage at
    <https://metacpan.org/release/Getopt-Long-Complete>.

SOURCE
    Source repository is at
    <https://github.com/perlancar/perl-Getopt-Long-Complete>.

SEE ALSO
    Getopt::Long::More, another drop-in replacement for Getopt::Long with
    tab completion support and more stuffs: default value, required value,
    summary in auto_help.

    Complete::Getopt::Long (the backend for this module), Complete::Bash,
    Complete::Tcsh.

    Getopt::Long::Subcommand also supports tab completion, in addition to
    subcommands.

    Other option-processing modules featuring shell tab completion:
    Getopt::Complete.

    Perinci::CmdLine - an alternative way to easily create command-line
    applications with completion feature.

    shcompgen

    Pod::Weaver::Section::Completion::GetoptLongComplete

AUTHOR
    perlancar <perlancar@cpan.org>

CONTRIBUTOR
    Steven Haryanto (on Asus Zenbook) <stevenharyanto@gmail.com>

CONTRIBUTING
    To contribute, you can send patches by email/via RT, or send pull
    requests on GitHub.

    Most of the time, you don't need to build the distribution yourself. You
    can simply modify the code, then test via:

     % prove -l

    If you want to build the distribution (e.g. to try to install it locally
    on your system), you can install Dist::Zilla,
    Dist::Zilla::PluginBundle::Author::PERLANCAR, and sometimes one or two
    other Dist::Zilla plugin and/or Pod::Weaver::Plugin. Any additional
    steps required beyond that are considered a bug and can be reported to
    me.

COPYRIGHT AND LICENSE
    This software is copyright (c) 2021, 2020, 2017, 2016, 2015, 2014 by
    perlancar <perlancar@cpan.org>.

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

BUGS
    Please report any bugs or feature requests on the bugtracker website
    <https://rt.cpan.org/Public/Dist/Display.html?Name=Getopt-Long-Complete>

    When submitting a bug or request, please include a test-file or a patch
    to an existing test-file that illustrates the bug or desired feature.