Bash::Completion::Plugin - base class for Bash::Completion plugins


version 0.008


    ## Example plugin for xpto command
    package Bash::Completion::Plugin::XPTO;
    use strict;
    use warnings;
    use parent 'Bash::Completion::Plugin';
    use Bash::Completion::Utils qw( command_in_path );
    sub should_activate {
      return [grep { command_in_path(_) } ('xpto')];
    ## Optionally, for full control of the generated bash code
    sub generate_bash_setup {
      return q{complete -C 'bash-complete complete XPTO' xpto};
    ## Use plugin arguments
    sub generate_bash_setup {
      return q{complete -C 'bash-complete complete XPTO arg1 arg2 arg3' xpto};
    ## $plugin->args will have ['arg1', 'arg2', 'arg3']
    sub complete {
      my ($self, $r) = @_;
      my @options = ('-h', '--help');
      $r->candidates(prefix_match($r->word, @options));


    WARNING: the most important class for Plugin writers is the Request
    class. Please note that the Request class interface is Alpha-quality
    software, and I will update it before 1.0.

A base class for Bash::Completion plugins that provides the default implementations for the required plugin methods.

See the "SYNOPSIS" for an example of a plugin.



An list reference with plugin arguments.



A basic plugin constructor. Accepts a list of key/values. Accepted keys:


A list reference with parameters to this plugin.


The method should_activate() is used by the automatic setup of completion rules in the .bashrc. It should return a reference to a list of commands that the plugin is can complete.

If this method returns a reference to an empty list (the default), the plugin will not be used.

A common implementation of this method is to check the PATH for the command we want to provide completion, and return the com only if that command is found.

The Bash::Completion::Utils library has a command_in_path() that can be pretty useful here.

For example:

    sub should_activate {
      return [grep { command_in_path($_) } qw( perldoc pod )];


This method receives the list of commands that where found by "should_activate" and must return a list of options to use when creating the bash complete command.

For example, if a plugin returns [qw( nospace default )], the following bash code is generated:

    complete -C 'bash-complete complete PluginName' -o nospace -o default command

By default this method returns a reference to an empty list.

Alternatively, and for complete control, you can return a string with the entire bash code to activate the plugin.


The plugin completion logic. The class Bash::Completion will call this method with a Bash::Completion::Request object, and your code should use the Request candidates() method to set the possible completions.

The Bash::Completion::Utils library has two functions, match_perl_module() and prefix_math() that can be pretty useful here.


Pedro Melo <>


This software is Copyright (c) 2011 by Pedro Melo.

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)