NAME

Term::Bash::Completion::Generator - Generate bash completion scripts

SYNOPSIS

  # use default bash completion options
  generate_bash_completion_function('my_command', ['option1', ''option2']) ;
        
  # fine tune with the bash completion options
  generate_bash_completion_function('my_command', ['option1', ''option2'], '-*', 0, '-o plusdirs')

DESCRIPTION

Generate bash completion functions or perl scripts to dynamically provide completion for an application.

DOCUMENTATION

If you application or scripts have more than one or two options and you run a bash shell, it is advisable you provide a completion file for your application.

A completion file provides information to bash so when your user presses [tab], on the command line, possible completion is provided to the user.

This module provide you with subroutines to create the completion scripts. The completion scripts are either simple bash functions or scripts that allow you to dynamically generate completion. The scripts can be written in any language. This module generate scripts that are written in perl.

The perl scripts can be generated by calling the subroutine i this module or by running the generate_perl_completion_script script installed with this module.

The generated scripts can provide completion for applications written in any language. A good place to generate completion is in your Build.PL or Makefile.PL. Remember to test your completions too.

BASH COMPLETION DOCUMENTATION

Run 'man bash' on your prompt and search for 'Programmable Completion'.

bash-completion-20060301.tar.gz library, an older but useful archive of completion functions for common commands.

SUBROUTINES/METHODS

generate_perl_completion_script($command, \@completion_list)

Generates a perl script that can be used to dynamically generate completion for the bash command line.

Tree::Trie is used in the script to do the basic look-up. Tree::Trie was installed as dependency to this module. Modify the generated script to implement your completion logic.

You can also use the generate_perl_completion_script script to create the perl completion script from the command line.

Arguments

$command - a string containing the command name
\@completion_list - list of options to create completion for
the options can be simple strings or a Getopt::Long specifications

Returns - an array containing:

a string containing the bash completion command
a string containing the perl script

Exceptions - carps if $command is not defined

source the following line in your ~/.bashrc:

EOC

$perl_completion_script .= <<"EOC" ; complete $bash_completion_arguments

EOC

$perl_completion_script .= <<'EOC' ; Replace perl_completion_script with the name you saved the script under. The script has to be executable and somewhere in the path.

The script will receive these arguments from bash:

@ARGV |- 0 = command |- 1 = word_to_complete `- 2 = word_before_the_word_to_complete

You return possible completion you want separated by \n. Return nothing if you want the default bash completion to be run which is possible because of the <-o defaul> passed to the complete command.

Note! You may have to re-run the complete command after you modify your perl script.

generate_bash_completion_function($command, \@completion_list, $completion_prefix, $single_and_double_dash, $complete_options)

Generates a bash function that provides completion for the options passed as parameter. The options can be simple strings like 'output_directory' or 'a' or Getopt::Long specifications like 'j|jobs=i', 'd|display_documentation:s', or 'o'.

Note that the options do not have any dash at the start.

Arguments

$command - a string containing the command name
\@completion_list - list of options to create completion for
the options can be simple strings or a Getopt::Long specifications
$completion_prefix - see bash manual ; default is '-*'
$single_and_double_dash - boolean variable ; default is 1
0 - single dash for single letter options, double dash for multiple letters options 1 - all options have single and double dash
$complete_options - string containing the options passed to complete ; default is '-o default'

Returns - a string containing the bash completion script

Exceptions - carps if $command is not defined

de_getop_ify_list(\@completion_list)

Split Getopt::Long option definitions and remove type information

Arguments

•: \@completion_list - list of options to create completion for
the options can be simple strings or a Getopt::Long specifications

Returns - an array reference

Exceptions - carps if $completion_list is not defined

BUGS AND LIMITATIONS

None so far.

AUTHOR

        Nadim ibn hamouda el Khemir
        CPAN ID: NH
        mailto: nadim@cpan.org

LICENSE AND COPYRIGHT

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

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Term::Bash::Completion::Generator

You can also look for information at:

AnnoCPAN: Annotated CPAN documentation
<http://annocpan.org/dist/Term-Bash-Completion-Generator>
RT: CPAN's request tracker
Please report any bugs or feature requests to L <bug-term-bash-completion-generator@rt.cpan.org>.

We will be notified, and then you'll automatically be notified of progress on your bug as we make changes.
Search CPAN
<http://search.cpan.org/dist/Term-Bash-Completion-Generator>