NAME

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

VERSION

version 0.001

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 the Bash::Completion manpage 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 the Bash::Completion::Utils manpage 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.

complete

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

The the Bash::Completion::Utils manpage 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 software is Copyright (c) 2010 by Pedro Melo.

This is free software, licensed under:

  The Artistic License 2.0