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

perl v5.34.0                                       2022-06-17                                 Reply::Plugin(3pm)