/ 
Bash-Completion-0.008
River stage one • 8 direct dependents • 9 total dependents
/ Bash::Completion::Plugin

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.

complete

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 software is Copyright (c) 2011 by Pedro Melo.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)