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

VERSION
    This document describes version 0.15 of Getopt::Long::Complete (from
    Perl distribution Getopt-Long-Complete), released on 2014-11-29.

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. 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};
             if ($type eq 'optval' && $opt eq '--on-fail') {
                 return complete_array_elem(words=>[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, fish, tcsh and zsh are supported.

    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/fish/zsh) or COMMAND_LINE (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/profile", "/etc/bash.bashrc", "~/.bash_profile", or
    "~/.bashrc"). Replace "delete-user" with the actual script name:

     complete -C delete-user delete-user

    Or you can also use bash-completion-prog.

    To activate tab completion in fish, put your script somewhere in "PATH"
    and run this:

     begin; set -lx COMP_SHELL fish; set -lx COMP_MODE gen_command; delete-user; end > $HOME/.config/fish/completions/delete-user.fish

    Or use "/etc/fish/completions/delete-user.fish" if you want to install
    globally.

    To activate tab completion in tcsh, put your script somewhere in "PATH"
    and execute this in the shell or put it into your bash startup file
    (e.g. "/etc/csh.cshrc" or "~/.tcshrc"):

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

    To activate tab completion in zsh, put your script somewhere in "PATH"
    and execute this in the shell or put it into your bash startup file
    (e.g. "/etc/zsh/zshrc" or "~/.zshrc"):

     _delete_user() { read -l; local cl="$REPLY"; read -ln; local cp="$REPLY"; reply=(`COMP_LINE="$cl" COMP_POINT="$cp" delete-user`) }

     compctl -K _delete_user delete-user

FUNCTIONS
  GetOptions([\%hash, ]@spec)
    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. I believe this a sane default.

  GetOptionsWithCompletion(\&completion, [\%hash, ]@spec)
    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.

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

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

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

    App::BashCompletionProg

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

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

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.

AUTHOR
    perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2014 by 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.

