NAME

       Reply::Plugin - base class for Reply plugins

VERSION

       version 0.42

SYNOPSIS

         package Reply::Plugin::Foo;
         use strict;
         use warnings;

         use base 'Reply::Plugin';

         # ...

DESCRIPTION

       A Reply plugin is an object which adds some functionality to a Reply instance by
       implementing some specific methods which the Reply object will call at various points
       during execution. Plugins may implement as many callback 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 three potential calling conventions:

       wrapped
           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.

       chained
           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.

       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.

   CALLBACKS
       prompt
           Called to determine the prompt to use when reading the next line. Takes no arguments,
           and returns a single string to use as the prompt. The default implementation returns
           ">"

       read_line
           Called to actually read a line from the user. Takes no arguments, and returns a single
           string. The default implementation uses the "<>" operator to read a single line from
           "STDIN".

       command_$name (chained)
           If the line read from the user is of the form "#foo args...", then plugins will be
           searched for a callback method named "command_foo". This callback takes a single
           string containing the provided arguments, and returns a new line to evaluate instead,
           if any.

       mangle_line (chained)
           Modifies the line read from the user before it's evaluated. Takes the line as a string
           and returns the modified line.

       compile
           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 Eval::Closure to compile the given string.

           The hash of extra parameters is passed directly to "eval_closure".

       execute
           Executes the coderef which has just been compiled. Takes the coderef and a list of
           parameters to pass to it, and returns the list of results returned by calling the
           coderef. The default implementation just calls the coderef directly.

       mangle_error (chained)
           If the "compile" or "execute" callbacks throw an exception, this callback will be
           called to modify the exception before it is passed to "print_error".  It receives the
           exception and returns the modified exception.

       print_error
           If the "compile" or "execute" callbacks throw an exception, this callback will be
           called to display it to the user. It receives the exception and returns nothing. The
           default implementation just uses "print" to print it to the screen.

       mangle_result (chained)
           This callback is used to modify the result of evaluating the line of code before it is
           displayed. It receives the list of results and returns a modified list of results.

       print_result
           This callback displays to the user the results of evaluating the given line of code.
           It receives the list of results, and returns nothing. The default implementation just
           uses "print" to print them to the screen.

       loop (chained)
           This callback is called at the end of each evaluation. It receives whether the repl
           has been requested to terminate so far, and returns whether the repl should terminate.

       Reply plugins can also communicate among each other via a pub/sub mechanism. By calling
       the "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:

       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.

       lexical_environment
           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 "$self->publish('lexical_environment')", and then merging together all
           of the hashrefs which are returned.

       package
           Plugins which wish to modify the currently active package should do so by implementing
           this message, which should return the name of the current package.  Then, to access
           the currently active package, a plugin can call "($self->publish('package'))[-1]".

       Your plugins, however, are not limited to these messages - you can use whatever messages
       you want to communicate.

METHODS

   publish ($name, @args)
       Publish a message to other plugins which respond to it. All loaded plugins which implement
       a method named $name will have it called with @args as the parameters. Returns a list of
       everything that each plugin responded with.

   commands
       Returns the names of the "#" commands that this plugin implements. This can be used in
       conjunction with "publish" - "$plugin->publish('commands')" will return a list of all
       commands which are available in the current Reply session.

AUTHOR

       Jesse Luehrs <doy@tozt.net>

COPYRIGHT AND LICENSE

       This software is Copyright (c) 2016 by Jesse Luehrs.

       This is free software, licensed under:

         The MIT (X11) License