From 5b9076b09b5da1f415299309f16dff21b54a62f0 Mon Sep 17 00:00:00 2001 From: Jesse Luehrs Date: Wed, 10 Jul 2013 02:45:48 -0400 Subject: docs --- lib/Reply/Plugin.pm | 63 ++++++++++++++++++++----------- lib/Reply/Plugin/Autocomplete/Commands.pm | 13 +++++++ 2 files changed, 53 insertions(+), 23 deletions(-) diff --git a/lib/Reply/Plugin.pm b/lib/Reply/Plugin.pm index f17b135..14cfcc8 100644 --- a/lib/Reply/Plugin.pm +++ b/lib/Reply/Plugin.pm @@ -24,24 +24,33 @@ methods as necessary to implement their functionality (although the more callbacks a given plugin implements, the more likely it is that the plugin may be more useful as multiple independent plugins). -Callback methods have two potential calling conventions: +Callback methods have three potential calling conventions: =over 4 =item wrapped -Wrapped plugins receive a coderef as their first argument (before any arguments -to the callback itself), and that coderef can be used to call the next callback -in the list (if more than one plugin implements a given callback). In -particular, this allows calling the next plugin multiple times, or not at all -if necessary. Wrapped plugins should always call their coderef in list context. -All plugins listed below are wrapped plugins unless indicated otherwise. +Wrapped callbacks receive a coderef as their first argument (before any +arguments to the callback itself), and that coderef can be used to call the +next callback in the list (if more than one plugin implements a given +callback). In particular, this allows calling the next plugin multiple times, +or not at all if necessary. Wrapped plugins should always call their coderef in +list context. All plugins listed below are wrapped plugins unless indicated +otherwise. =item chained -Chained plugins receive a list of arguments, and return a new list of arguments -which will be passed to the next plugin in the chain. This allows each plugin a -chance to modify a value before it's actually used by the repl. +Chained callbacks receive a list of arguments, and return a new list of +arguments which will be passed to the next plugin in the chain. This allows +each plugin a chance to modify a value before it's actually used by the repl. + +=item concatenate + +Concatenate callbacks receive a list of arguments, and return a list of +response values. Each plugin that implements the given callback will be called +with the same arguments, and the results will be concatenated together into a +single list, which will be returned. Callbacks for published messages are of +this type. =back @@ -135,23 +144,22 @@ Plugins can publish this message when they want to attempt tab completion. Plugins that respond to this message should return a list of potential completions of the line which is passed in. -=item lexical_environment ($name, $env) +=item lexical_environment -Plugins which wish to modify the lexical environment should do so by publishing -this message. This will register it with the repl itself, as well as allowing -other plugins which introspect the lexical environment to see it. +Plugins which wish to modify the lexical environment should do so by +implementing this message, which should return a hashref of variable names +(including sigils) to value references. There can be more than one lexical +environment (each maintained by a different plugin), so plugins that wish to +inspect the lexical environment should do so by calling +C<< $self->publish('lexical_environment') >>, and then merging together all of +the hashrefs which are returned. -There can be more than one lexical environment, which are all merged together -when the line is evaluated. C is the primary environment (typically -corresponding to the user's code). All other environments should typically have -unique names, and are used to add additonal variables to the environment that -won't be overridden if a plugin decides to replace the default environment. - -=item package ($name) +=item package Plugins which wish to modify the currently active package should do so by -publishing this message. This will register it with the repl itself, as well as -allowing other plugins which introspect the current package to see it. +implementing this message, which should return the name of the current package. +Then, to access the currently active package, a plugin can call +C<< ($self->publish('package'))[-1] >>. =back @@ -185,6 +193,15 @@ sub publish { $self->{publisher}->(@_); } +=method commands + +Returns the names of the C<#> commands that this plugin implements. This can +be used in conjunction with C - C<< $plugin->publish('commands') >> +will return a list of all commands which are available in the current Reply +session. + +=cut + sub commands { my $self = shift; diff --git a/lib/Reply/Plugin/Autocomplete/Commands.pm b/lib/Reply/Plugin/Autocomplete/Commands.pm index ec86208..e3b653d 100644 --- a/lib/Reply/Plugin/Autocomplete/Commands.pm +++ b/lib/Reply/Plugin/Autocomplete/Commands.pm @@ -1,9 +1,22 @@ package Reply::Plugin::Autocomplete::Commands; use strict; use warnings; +# ABSTRACT: tab completion for reply commands use base 'Reply::Plugin'; +=head1 SYNOPSIS + + ; .replyrc + [ReadLine] + [Autocomplete::Commands] + +=head1 DESCRIPTION + +This plugin registers a tab key handler to autocomplete Reply commands. + +=cut + sub tab_handler { my $self = shift; my ($line) = @_; -- cgit v1.2.3-54-g00ecf