From e5a7afe08c7dcad0245ca97eb1394bb5221960cd Mon Sep 17 00:00:00 2001
From: Jesse Luehrs <doy@tozt.net>
Date: Thu, 27 Jun 2013 18:58:14 -0400
Subject: update docs

---
 lib/Reply/Plugin.pm                       | 63 ++++++++++++++++++++++---------
 lib/Reply/Plugin/Autocomplete/Keywords.pm |  5 ---
 lib/Reply/Plugin/Autocomplete/Lexicals.pm |  6 ---
 lib/Reply/Plugin/Autocomplete/Packages.pm |  5 ---
 lib/Reply/Plugin/Defaults.pm              |  1 -
 5 files changed, 46 insertions(+), 34 deletions(-)

(limited to 'lib/Reply')

diff --git a/lib/Reply/Plugin.pm b/lib/Reply/Plugin.pm
index c0746d1..ed3efbb 100644
--- a/lib/Reply/Plugin.pm
+++ b/lib/Reply/Plugin.pm
@@ -77,23 +77,7 @@ Compiles the string of Perl code into a coderef. Takes the line of code as a
 string and a hash of extra parameters, and returns the coderef to be executed.
 The default implementation uses L<Eval::Closure> to compile the given string.
 
-The extra parameters can be anything that C<eval_closure> supports, as well as
-these additional parameters:
-
-=over 4
-
-=item package
-
-The package to use to evaluate the code within. Defaults to C<main>.
-
-=item environments
-
-A hashref of additional lexical environments to be merged with the main lexical
-environment in the C<environment> key. This allows plugins to ensure that their
-extra additions to the lexical scope remain visible, even if other plugins
-change what "the current lexical scope" means.
-
-=back
+The hash of extra parameters is passed directly to C<eval_closure>.
 
 =item execute
 
@@ -135,6 +119,43 @@ should terminate.
 
 =back
 
+Reply plugins can also communicate among each other via a pub/sub mechanism. By
+calling the C<publish> method, all plugins which respond to the given message
+(implement a method of the given name) will have that method called with the
+given arguments, and all of the responses will be collected and returned. Some
+messages used by the default plugins are:
+
+=over 4
+
+=item tab_handler ($line)
+
+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)
+
+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.
+
+There can be more than one lexical environment, which are all merged together
+when the line is evaluated. C<default> 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)
+
+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.
+
+=back
+
+Your plugins, however, are not limited to these messages - you can use whatever
+messages you want to communicate.
+
 =cut
 
 sub new {
@@ -148,6 +169,14 @@ sub new {
     }, $class;
 }
 
+=method publish ($name, @args)
+
+Publish a message to other plugins which respond to it. All loaded plugins
+which implement a method named C<$name> will have it called with C<@args> as
+the parameters. Returns a list of everything that each plugin responded with.
+
+=cut
+
 sub publish {
     my $self = shift;
 
diff --git a/lib/Reply/Plugin/Autocomplete/Keywords.pm b/lib/Reply/Plugin/Autocomplete/Keywords.pm
index b3ec05a..1742b87 100644
--- a/lib/Reply/Plugin/Autocomplete/Keywords.pm
+++ b/lib/Reply/Plugin/Autocomplete/Keywords.pm
@@ -32,9 +32,4 @@ sub tab_handler {
     return grep { $_ =~ $re } @Functions, @Barewords;
 }
 
-=for Pod::Coverage
-  tab_handler
-
-=cut
-
 1;
diff --git a/lib/Reply/Plugin/Autocomplete/Lexicals.pm b/lib/Reply/Plugin/Autocomplete/Lexicals.pm
index 7c4a771..b49c4c6 100644
--- a/lib/Reply/Plugin/Autocomplete/Lexicals.pm
+++ b/lib/Reply/Plugin/Autocomplete/Lexicals.pm
@@ -72,10 +72,4 @@ sub tab_handler {
     return @results;
 }
 
-=for Pod::Coverage
-  tab_handler
-  lexical_environment
-
-=cut
-
 1;
diff --git a/lib/Reply/Plugin/Autocomplete/Packages.pm b/lib/Reply/Plugin/Autocomplete/Packages.pm
index e414e4a..d247baa 100644
--- a/lib/Reply/Plugin/Autocomplete/Packages.pm
+++ b/lib/Reply/Plugin/Autocomplete/Packages.pm
@@ -46,9 +46,4 @@ sub tab_handler {
     return @results;
 }
 
-=for Pod::Coverage
-  tab_handler
-
-=cut
-
 1;
diff --git a/lib/Reply/Plugin/Defaults.pm b/lib/Reply/Plugin/Defaults.pm
index 0124b4c..ca3c047 100644
--- a/lib/Reply/Plugin/Defaults.pm
+++ b/lib/Reply/Plugin/Defaults.pm
@@ -118,7 +118,6 @@ sub loop {
 
   new
   command_q
-  lexical_environment
 
 =end Pod::Coverage
 
-- 
cgit v1.2.3-54-g00ecf