Debian Codegraph @

README

raw
1 NAME
2 Getopt::Complete - programmable shell completion for Perl apps
3
4 VERSION
5 This document describes Getopt::Complete v0.9.
6
7 SYNOPSIS
8 In the Perl program "myprogram":
9
10 use Getopt::Complete (
11 'frog' => ['ribbit','urp','ugh'],
12 'fraggle' => sub { return ['rock','roll'] },
13 'quiet!' => undef,
14 'name' => undef,
15 'age=n' => undef,
16 'outfile=s@' => 'files',
17 'outdir' => 'directories'
18 'runthis' => 'commands',
19 'username' => 'users',
20 '<>' => 'directories',
21 );
22
23 print "the frog says " . $ARGS{frog} . "\n";
24
25 In ~/.bashrc or ~/.bash_profile, or directly in bash:
26
27 function _getopt_complete () {
28 COMPREPLY=($( COMP_CWORD=$COMP_CWORD perl `which ${COMP_WORDS[0]}` ${COMP_WORDS[@]:0} ));
29 }
30 complete -F _getopt_complete myprogram
31
32 Thereafter in the terminal (after next login, or sourcing the updated
33 .bashrc):
34
35 $ myprogram --f<TAB>
36 $ myprogram --fr
37
38 $ myprogram --fr<TAB><TAB>
39 frog fraggle
40
41 $ myprogram --fro<TAB>
42 $ myprogram --frog
43
44 $ myprogram --frog <TAB>
45 ribbit urp ugh
46
47 $ myprogram --frog r<TAB>
48 $ myprogram --frog ribbit
49
50 DESCRIPTION
51 This module makes it easy to add custom command-line completion to Perl
52 applications. It also does additional validation of arguments, when the
53 program is actually executed, based on completion lists.
54
55 Support is also present for apps which are an entry point for a
56 hierarchy of sub-commands (in the style of cvs and git).
57
58 Getopt::Complete also wraps the standard options processing and exports
59 it as a %ARGS hash at compile time, making using the arguments
60 hassle-free.
61
62 The completion features currently work with the bash shell, which is the
63 default on most Linux and Mac systems. Patches for other shells are
64 welcome.
65
66 OPTIONS PROCESSING
67 Getopt::Complete processes the command-line options at compile time.
68
69 The results are avaialble in the %ARGS hash, which is intended as a
70 companion to the @ARGV array generated natively by Perl.
71
72 use Getopt::Complete (
73 'mydir' => 'd',
74 'myfile' => 'f',
75 '<>' = ['monkey', 'taco', 'banana']
76 );
77
78 for $opt (keys %ARGS) {
79 $val = $ARGS{$opt};
80 print "$opt has value $val\n";
81 }
82
83 Errors in shell argumentes result in messages to STDERR via warn(), and
84 cause the program to exit during "use" call. Getopt::Complete verifies
85 that the option values specified match their own completion list, and
86 will otherwise add additional errors explaining the problem.
87
88 The %ARGS hash is an alias for %Getopt::Complete::ARGS. The alias is not
89 created in the caller's namespaces if a hash named %ARGS already exists
90 with data, but the results are always available from
91 %Getopt::Complete::ARGS.
92
93 They keys of the hash are the option names, minus any specifiers like
94 "=s" or "!". The key is only present if the option was specified on the
95 command-line.
96
97 The values of the hash are the values from the command-line. For
98 multi-value options the hash value is an arrayref.
99
100 OBJECT API
101 An object $ARGS is also created in the caller's namespace (class
102 Getopt::Complete::Args) with a more detailed API for argument
103 interrogation. See the documentation for that module, and also for the
104 underlying Getopt::Complete::Options module.
105
106 It is possible to override any part of the default process, including
107 doing custom parsing, doing processing at run-time, and and preventing
108 exit when there are errors.
109
110 See OVERRIDING COMPILE-TIME OPTION PARSING for more information.
111
112 PROGRAMMABLE COMPLETION BACKGROUND
113 The bash shell supports smart completion of words when the <TAB> key is
114 pressed. By default, after the program name is specified, bash will
115 presume the word the user is typing a is a file name, and will attempt
116 to complete the word accordingly. Where completion is ambiguous, the
117 shell will go as far as it can and beep. Subsequent completion attempts
118 at that position result in a list being shown of possible completions.
119
120 Bash can be configured to run a specific program to handle the
121 completion task, allowing custom completions to be done for different
122 appliations. The "complete" built-in bash command instructs the shell
123 as-to how to handle tab-completion for a given command.
124
125 This module allows a program to be its own word-completer. It detects
126 that the COMP_LINE and COMP_POINT environment variables are set,
127 indicating that it is being used as a completion program, and responds
128 by returning completion values suitable for the shell _instead_ of
129 really running the application.
130
131 See the manual page for "bash", the heading "Programmable Completion"
132 for full details on the general topic.
133
134 HOW TO CONFIGURE PROGRAMMABLE COMPLETION
135 1 Put a "use Getopt::Complete" statement into your app as shown in the
136 synopsis. The key-value pairs describe the command-line options
137 available, and their completions.
138
139 This should be at the TOP of the app, before any real processing is
140 done. The only modules used before it should be those needed for
141 custom callbacks, if there are any. No code should print to standard
142 output during compile time, or it will confuse bash.
143
144 Subsequent code can use %ARGS or the $ARGS object to check on
145 command-line option values.
146
147 Existing apps using Getopt::Long should use their option spec in the
148 use declaration instead. If they bind variables directly the code
149 should to be updated to get values from the %ARGS hash instead.
150
151 2 Put the following in your .bashrc or .bash_profile:
152
153 function _getopt_complete () {
154 COMPREPLY=($( COMP_CWORD=$COMP_CWORD perl `which ${COMP_WORDS[0]}` ${COMP_WORDS[@]:0} ));
155 }
156 complete -F _getopt_complete myprogram
157
158 3 New logins will automatically run the above and become aware that
159 your program has programmable completion. For shells you already
160 have open, run this to alert bash to your that your program has
161 custom tab-completion.
162
163 source ~/.bashrc
164
165 Type the name of your app ("myprogram" in the example), and experiment
166 with using the <TAB> key to get various completions to test it. Every
167 time you hit <TAB>, bash sets certain environment variables, and then
168 runs your program. The Getopt::Complete module detects these variables,
169 responds to the completion request, and then forces the program to exit
170 before really running your regular application code.
171
172 IMPORTANT: Do not do steps #2 and #3 w/o doing step #1, or your
173 application will actually run "normally" every time you press <TAB> with
174 it on the command-line! The module will not be present to detect that
175 this is not a "real" execution of the program, and you may find your
176 program is running when it should not.
177
178 KEYS IN THE OPTIONS SPECIFICATION
179 Each key in the list decribes an option which can be completed. Any key
180 usable in a Getopt:::Long GetOptions specification works here, (except
181 as noted in BUGS below):
182
183 an option name
184 A normal word is interpreted as an option name. The '=s' specifier
185 is presumed if no specifier is present.
186
187 'p1' => [...]
188
189 a complete option specifier
190 Any specification usable by Getopt::Long is valid as the key. For
191 example:
192
193 'p1=s' => [...] # the same as just 'p1'
194 'p2=s@' => [...] # expect multiple values
195
196 the '<>' symbol for "bare arguments"
197 This special key specifies how to complete non-option (bare)
198 arguments. It presumes multiple values are possible (like '=s@'):
199
200 Have an explicit list: '<>' = ['value1','value2','value3']
201
202 Do normal file completion: '<>' = 'files'
203
204 Take arbitrary values with no expectations: '<>' = undef
205
206 If there is no '<>' key specified, bare arguments will be treated as
207 an error.
208
209 a sub-command specifier, starting with '>'
210 When a key in the options specification starts with '>', it
211 indicates a that word maps to a distinct sub-command with its own
212 options. The array to the right is itself a full options
213 specification, following the same format as the one above it,
214 including possible further sub-commands.
215
216 See SUB-COMMAND TREES for more details.
217
218 VALUES IN THE OPTIONS SPECIFICATION
219 Each value describes how the option in question should be completed.
220
221 array reference
222 An array reference expliciitly lists the valid values for the
223 option.
224
225 In the app:
226
227 use Getopt::Complete (
228 'color' => ['red','green','blue'],
229 );
230
231 In the shell:
232
233 $ myprogram --color <TAB>
234 red green blue
235
236 $ myprogram --color blue
237 (runs with no errors)
238
239 The list of value is also used to validate the user's choice after
240 options are processed:
241
242 myprogram --color purple
243 ERROR: color has invalid value purple: select from red green blue
244
245 See below for details on how to permit values which aren't shown in
246 completions to be used and not generate errors.
247
248 undef
249 An undefined value indicates that the option is not completable. No
250 completions will be offered by the application, though any value
251 provided by the user will be considered valid.
252
253 Note that this is distinct from returning an empty arrayref from a
254 callback, which implies that there ARE known completions but the
255 user has failed to match any of them.
256
257 Also note: this is the only valid completion for boolean parameters,
258 since there is no value to specify on the command-line.
259
260 use Getopt::Complete (
261 'name' => undef, # take --name "anyting"
262 'perky!' => undef, # take --perky or --no-perky
263 );
264
265 subroutine callback
266 When the list of valid values must be determined dynamically, a
267 subroutine reference or name can be specified. If a name is
268 specified, it should be fully qualified. (If it is not, it will be
269 presumed to refer to one of the bash builtin completions types. See
270 BUILTIN COMPLETION TYPES below.)
271
272 The subroutine will be called, and is expected to return an arrayref
273 of possiible matches. The arrayref will be treated as though it were
274 specified directly in the specification.
275
276 As with explicit values, an empty arrayref indicated that there are
277 no valid matches for this option, given the other params on the
278 command-line, and the text already typed. An undef value indicates
279 that any value is valid for this parameter.
280
281 Parameters to the callback are described below.
282
283 WRITING SUBROUTINE CALLBACKS
284 A subroutine callback is useful when the list of options to match must
285 be dynamically generated.
286
287 It is also useful when knowing what the user has already typed helps
288 narrow the search for valid completions, or when iterative completion
289 needs to occur (see PARTIAL COMPLETIONS below).
290
291 The callback is expected to return an arrayref of valid completions. If
292 it is empty, no completions are considered valid. If an undefined value
293 is returned, no completions are specified, but ANY arbitrary value
294 entered is considered valid as far as error checking is concerned.
295
296 The callback registerd in the completion specification will receive the
297 following parameters:
298
299 command name
300 Contains the name of the command for which options are being parsed.
301 This is $0 in most cases, though hierarchical commands may have a
302 name "svn commit" or "foo bar baz" etc.
303
304 current word
305 This is the word the user is trying to complete. It may be an empty
306 string, if the user hits <Tab> without typing anything first.
307
308 option name
309 This is the name of the option for which we are resolving a value.
310 It is typically ignored unless you use the same subroutine to
311 service multiple options.
312
313 A value of '<>' indicates an unnamed argument (a.k.a "bare argument"
314 or "non-option" argument).
315
316 other opts
317 It is the hashref resulting from Getopt::Long processing of all of
318 the OTHER arguments. This is useful when one option limits the valid
319 values for another option.
320
321 In some cases, the options which should be available change
322 depending on what other options are present, or the values available
323 change depending on other options or their values.
324
325 The environment variables COMP_LINE and COMP_POINT have the exact text
326 of the command-line and also the exact character position, if more
327 detail is needed in raw form than the parameters provide.
328
329 The return value is a list of possible matches. The callback is free to
330 narrow its results by examining the current word, but is not required to
331 do so. The module will always return only the appropriate matches.
332
333 EXAMPLE
334 This app takes 2 parameters, one of which is dependent on the other:
335
336 use Getopt::Complete (
337 type => ['names','places','things'],
338 instance => sub {
339 my ($command, $value, $option, $other_opts) = @_;
340 if ($other_opts{type} eq 'names') {
341 return [qw/larry moe curly/],
342 }
343 elsif ($other_opts{type} eq 'places') {
344 return [qw/here there everywhere/],
345 }
346 elsif ($other_opts{type} eq 'things') {
347 return [ query_database_matching("${value}%") ]
348 }
349 elsif ($otper_opts{type} eq 'surprsing') {
350 # no defined list: take anything typed
351 return undef;
352 }
353 else {
354 # invalid type: no matches
355 return []
356 }
357 }
358 );
359
360 $ myprogram --type people --instance <TAB>
361 larry moe curly
362
363 $ myprogram --type places --instance <TAB>
364 here there everywhere
365
366 $ myprogram --type surprising --instance <TAB>
367 (no completions appear)
368
369 BUILTIN COMPLETIONS
370 Bash has a list of built-in value types which it knows how to complete.
371 Any of the default shell completions supported by bash's "compgen" are
372 supported by this module.
373
374 The list of builtin types supported as-of this writing are:
375
376 files
377 directories
378 commands
379 users
380 groups
381 environment
382 services
383 aliases
384 builtins
385
386 To indicate that an argument's valid values are one of the above, use
387 the exact string after Getopt::Complete:: as the completion callback.
388 For example:
389
390 use Getopt::Complete (
391 infile => 'Getopt::Complete::files',
392 outdir => 'Getopt::Complete::directories',
393 myuser => 'Getopt::Complete::users',
394 );
395
396 The full name is alissed as the single-character compgen parameter name
397 for convenience. Further, because Getopt::Complete is the default
398 namespace during processing, it can be ommitted from callback function
399 names.
400
401 The following are all equivalent. They effectively produce the same list
402 as 'compgen -f':
403
404 file1 => \&Getopt::Complete::files
405 file1 => \&Getopt::Complete::f
406 file1 => 'Getopt::Complete::files'
407 file1 => 'Getopt::Complete::f'
408 file1 => 'files'
409 file1 => 'f'
410
411 See Getopt::Complete::Compgen for specifics on using builtin
412 completions.
413
414 See "man bash", in the Programmable Complete secion, and the "compgen"
415 builtin command for more details.
416
417 UNLISTED VALID VALUES
418 If there are options which should not be part of completion lists, but
419 still count as valid if passed-into the app, they can be in a final
420 sub-array at the end. This list doesn't affect the completion system at
421 all, just prevents errors in the ERRORS array described above.
422
423 use Getopt::Complete (
424 'color' => ['red','green','blue', ['yellow','orange']],
425 );
426
427 myprogram --color <TAB>
428 red green blue
429
430 myprogram --color orange
431 # no errors
432
433 myprogram --color purple
434 # error
435
436 PARTIAL COMPLETIONS
437 BASICS
438 Any returned value ending in a <TAB> character ("\t") will be
439 considered a "partial" completion. This means that the shell will be
440 instructed to leave the cursor at the end of that word even if there
441 is no ambiguity in the rest of the returned list.
442
443 Partial completions are only usable from callbacks. From a
444 hard-coded array of values, it would be impossible to ever fuly
445 complete the partial completion.
446
447 BACKGROUND
448 Sometimes, the entire list of completions is too big to reasonable
449 resolve and return. The most obvious example is filename completion
450 at the root of a large filesystem. In these cases, the completion of
451 is handled in pieces, allowing the user to gradually "drill down" to
452 the complete value directory by directory. It is even possible to
453 hit <TAB> to get one completion, then hit it again and get more
454 completion, in the case of single-sub-directory directories.
455
456 The Getopt::Complete module supports iterative drill-down
457 completions from any parameter configured with a callback. It is
458 completely valid to complete "a" with "aa" "ab" and "ac", but then
459 to complete "ab" with yet more text.
460
461 Unless the shell knows, however that your "aa", "ab", and "ac"
462 completions are in fact only partial completions, an inconvenient
463 space will be added after the word on the terminal line, as the
464 shell happily moves on to helping the user enter the next argument.
465
466 DETAILS
467 Because partial completions are indicated in Getopt::Complete by
468 adding a "\t" tab character to the end of the returned string, an
469 application can return a mix of partial and full completions, and it
470 will respect each correctly.
471
472 Note: The "\t" is actually stripped-off before going to the shell
473 and internal hackery is used to force the shell to not put a space
474 where it isn't needed. This is not part of the bash programmable
475 completion specification, but is used to simulate features typically
476 only available with bash for builtin completions like
477 files/directories.
478
479 SUB-COMMAND TREES
480 It is common for a given appliction to actually be an entry point for
481 several different tools. Popular exmples are the big version control
482 suites (cvs,svn,svk,git), which use the form:
483
484 cvs SUBCOMMAND [ARGS]
485
486 Each sub-command has its own options specification. Those may in turn
487 have further sub-commands.
488
489 Sub-commands are identified by an initial '>' in the options
490 specification key. The value is interpreted as a complete, isolated
491 options spec, using the same general syntax. This applies recursively.
492
493 EXAMPLE COMMAND TREE SPEC
494 use Getopt::Complete (
495 '>animal' => [
496 '>dog' => [
497 '>bark' => [
498 'ferocity' => ['yip','wail','ruf','grrrr'],
499 'count' => ['1','2','one too many'],
500 ],
501 '>drool' => [
502 'buckets=n' => undef,
503 'lick' => 'users',
504 ],
505 'list!' => undef,
506 ],
507 '>cat' => [
508 '>purr' => [],
509 '>meow' => [
510 'volume=n' => undef,
511 'bass' => ['low','medium','high'],
512 ]
513 ],
514 ],
515 '>plant' => [
516 '>taters' => [
517 '>fry' => [
518 'greasiness' => ['crispy','drippy'],
519 'width' => ['fat','thin','frite'],
520 ],
521 '>bake' => [
522 'hard!' => undef,
523 'temp=n' => undef,
524 ],
525 ],
526 '>dasies' => [
527 '>pick' => [
528 '<>' => ['mine','yours','theirs'],
529 ],
530 '>plant' => [
531 'season' => ['winter','spring','summer','fall'],
532 'seeds=n' => undef,
533 'deep!' => undef,
534 ]
535 ]
536 ]
537 );
538
539 my ($word1,$word2,$word3) = $ARGS->parent_sub_commands;
540 # (the above is also in $ARGS{'>'} for non-OO access)
541
542 # your program probably has something smarter to decide where to go
543 # for a given command
544 if ($word1 eq 'animal') {
545 if ($word2 eq 'dog') {
546 if ($word3 eq 'bark') {
547 # work with %ARGS for barking dogs...
548 # ....
549 }
550 }
551 }
552 elsif ($path[0] eq 'plant') {
553 ...
554 }
555
556 The above example specifies two sub-commands "animal" and "plant, each
557 of which has its own two sub-commands, dog/cat and taters/dasies. Each
558 of those, in turn, have two sub-commands, for a total of 8 complete
559 commands possible, each with different arguments. Each of the 8 has
560 thier own options specification.
561
562 When the program executes, the %ARGS hash contains option/value pairs
563 for the specific command chosen. The the series of sub-command choices
564 in $ARGS{'>'}, separate from the regular bare arguments in '<>'. (The
565 method name on an $ARGS object for this is "parent_sub_commands", a
566 companion to the "bare_args" method.
567
568 The method to determine the next available sub-commands is just
569 "sub_commands".)
570
571 Note that, since the user can hit <ENTER> at any time, it is possible
572 that the parent_sub_commands will be a partial drill-down. It isn't
573 uncommon to have something like this in place:
574
575 if (my @next = $ARGS->sub_commands) {
576 print STDERR "Please select a sub-command:\n";
577 print STDERR join("\n", @sub_commands),"\n";
578 exit 1;
579 }
580
581 The above checking is not done automatically, since a sub-command may
582 have further sub-commands, but still also be used directly, possibly
583 with other option and bare arguments.
584
585 THE LONE DASH
586 A lone dash is often used to represent using STDIN instead of a file for
587 applications which otherwise take filenames.
588
589 This is supported by all options which complete with the "files"
590 builtin, though it does not appear in completion hint displays.
591
592 To disable this, set $Getopt::Complete::LONE_DASH = 0.
593
594 OVERRIDING COMPILE-TIME OPTION PARSING
595 Getopt::Complete makes a lot of assumptions in order to be easy to use
596 in the default case. Here is how to override that behavior if it's not
597 what you want.
598
599 OPTION 1: DOING CUSTOM ERROR HANDLING
600 To prevent Getopt::Complete from exiting at compile time if there
601 are errors, the EXIT_ON_ERRORS flag should be set to 0 first, at
602 compile time, before using the Getopt::Complete module as follows:
603
604 BEGIN { $Getopt:Complete::EXIT_ON_ERRORS = 0; }
605
606 This should not affect completions in any way (it will still exit if
607 it realizes it is talking to bash, to prevent accidentally running
608 your program).
609
610 Errors are retained in:
611
612 $Getopt::Complete::ARGS->errors;
613
614 It is then up to the application to not run with invalid parameters.
615
616 OPTION 2: RE-PROCESS @ARGV
617 This module restores @ARGV to its original state after processing,
618 so independent option processing can be done if necessary. The full
619 spec imported by Getopt::Complete is stored as:
620
621 $Getopt::Complete::ARGS->option_specs;
622
623 This is an easy option when upgrading old applications.
624
625 Combined with disabling the EXIT_ON_ERROS flag above, set, you can
626 completely ignore, or partially ignore, the options processing which
627 happens automatically.
628
629 OPTION 3: CHANGING COMPILE-TIME PROCESSING
630 You can also adjust how option processing happens inside of
631 Getopt::Complete. Getopt::Complete wraps Getopt::Long to do the
632 underlying option parsing. It uses GetOptions(\%h, @specification)
633 to produce the %ARGS hash. Customization of Getopt::Long should
634 occur in a BEGIN block before using Getopt::Complete.
635
636 OPTION 4: USE THE OBJECTS AND WRITE YOUR OWN LOGIC
637 The logic in import() is very short, and is simple to modify. It is
638 best to do it in a BEGIN {} block so that bash can use 'perl -c
639 myprogram' to get completions at compile time.
640
641 BEGIN {
642
643 my $options = Getopt::Complete::Options->new(
644 'myfile' => 'f',
645 'mychoice' => ['small','medium','huge']
646 );
647
648 $options->handle_shell_completion();
649
650 my $args = Getopt::Complete::Args->new(
651 options => $options,
652 argv => [@ARGV]
653 );
654
655 if (my @errors = $ARGS->errors) {
656 for my $error ($ARGS->errors) {
657 chomp $error;
658 warn __PACKAGE__ . ' ERROR:' . $error . "\n";
659 }
660 exit 1;
661 }
662
663 # make the %ARGS available to all of the app
664 $args->__install_as_default__;
665
666 # if you also want %ARGS and $ARGS here when you're finished...
667 Getopt:Complete->export_aliases(__PACKAGE__);
668 };
669
670 EXTENSIVE USAGE EXAMPLE
671 Cut-and-paste this into a script called "myprogram" in your path, make
672 it executable, and then run this in the shell: complete -C myprogram
673 myprogram. Then try it out. It does one of everything, besides command
674 trees.
675
676 #!/usr/bin/env perl
677 use strict;
678 use warnings;
679
680 use Getopt::Complete (
681 # list the explicit values which are valid for this option
682 'frog' => ['ribbit','urp','ugh'],
683
684 # you can add any valid Getopt::Long specification to the key on the left
685 # ...if you put nothing: "=s" is assumed
686 'names=s@' => ['eenie','meanie','miney'],
687
688 # support for Bash "compgen" builtins is present with some pre-made callbacks
689 'myfile' => 'Getopt::Complete::Compgen::files',
690 'mydir' => 'Getopt::Complete::Compgen::directories',
691
692 # the plain name or first letter of the compgen builtins also work
693 'myfile2' => 'files',
694 'myfile3' => 'f',
695
696 # handle unnamed arguments from the command-line ("non-option" arguments) with a special key:
697 '<>' => ['some','raw','words'],
698
699 # CODE callbacks allow a the completion list to be dynamically resolved
700 'fraggle' => sub { return ['rock','roll','fried fish','fried taters','fries and squid'] },
701
702 # callbacks get extra info to help them, including the part of the
703 # word already typed, and the remainder of the options already processed for context
704 'type' => ['people','places'],
705 'instance'=> sub {
706 my ($command, $partial_word, $option_name, $other_opts_hashref) = @_;
707 # be lazy and ignore the partial word: bash will compensate
708 if (my $type = $other_opts_hashref->{type}) {
709 if ($type eq 'people') {
710 return [qw/larry moe curly/]
711 }
712 elsif ($type eq 'places') {
713 return [qw/here there everywhere/],
714 }
715 }
716 return [];
717 },
718
719 # undef means we don't know how to complete the value: any value specified will do
720 # this will result in no shell ompletions, but will still expect a value to be entered
721 'name=s' => undef,
722
723 # boolean values never have a completion list, and will yell if you are that foolish
724 # this will give you --no-fast for free as well
725 'fast!' => undef,
726
727 );
728
729 use Data::Dumper;
730 print "The arguments are: " . Dumper(\%ARGS);
731
732 DEVELOPMENT
733 Patches are welcome.
734
735 http://github.com/sakoht/Getopt--Complete-for-Perl/
736
737 git clone git://github.com/sakoht/Getopt--Complete-for-Perl.git
738
739 As are complaints. Help us find bugs by sending an email to the address
740 below, or using CPAN's bug tracking system:
741
742 https://rt.cpan.org/
743
744 The latest version of this module is always availabe on CPAN:
745
746 http://search.cpan.org/search?query=Getopt%3A%3AComplete&mode=all
747
748 And is readily installable with the CPAN shell on Mac, Linux, and other
749 Unix-like systems:
750
751 sudo cpan Getopt::Complete
752
753 BUGS
754 Completions with whitespace work, but they do so by escaping whitespace
755 characters instead of quoting. Support should be present for completing
756 quoted text. It should also be the default, since it is more attractive.
757
758 The logic to "shorten" the completion options shown in some cases is
759 still in development. This means that filename completion shows full
760 paths as options instead of just the last word in the file path.
761
762 Some uses of Getopt::Long will not work currently: multi-name options
763 (though standard shortening works), +, :, %.
764
765 Currently this module only supports bash, though other shells could be
766 added easily.
767
768 There is logic in development to have the tool possibly auto-update the
769 user's .bashrc / .bash_profile, but this is incomplete.
770
771 SEE ALSO
772 Getopt::Complete::Args
773 the object API for the option/value argument set
774
775 Getopt::Complete::Options
776 the object API for the options specification
777
778 Getopt::Complete::Compgen
779 supplies builtin completions like file lists
780
781 Getopt::Long
782 the definitive options parser, wrapped by this module
783
784 bash
785 the manual page for bash has lots of info on how tab-completion
786 works
787
788 COPYRIGHT
789 Copyright 2009 Scott Smith and Washington University School of Medicine
790
791 AUTHORS
792 Scott Smith (sakoht at cpan .org)
793
794 LICENSE
795 This program is free software; you can redistribute it and/or modify it
796 under the same terms as Perl itself.
797
798 The full text of the license can be found in the LICENSE file included
799 with this module.
800