NAME

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

VERSION

version 0.008

SYNOPSIS

    ## 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));
    }
    1;

DESCRIPTION

    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.

ATTRIBUTES

args

An list reference with plugin arguments.

METHODS

new

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

args: A list reference with parameters to this plugin.

should_activate

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 )];
    }

generate_bash_setup

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.

AUTHOR

Pedro Melo <melo@cpan.org>

COPYRIGHT AND LICENSE

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)