1Reply::Plugin(3)      User Contributed Perl Documentation     Reply::Plugin(3)
2
3
4

NAME

6       Reply::Plugin - base class for Reply plugins
7

VERSION

9       version 0.42
10

SYNOPSIS

12         package Reply::Plugin::Foo;
13         use strict;
14         use warnings;
15
16         use base 'Reply::Plugin';
17
18         # ...
19

DESCRIPTION

21       A Reply plugin is an object which adds some functionality to a Reply
22       instance by implementing some specific methods which the Reply object
23       will call at various points during execution. Plugins may implement as
24       many callback methods as necessary to implement their functionality
25       (although the more callbacks a given plugin implements, the more likely
26       it is that the plugin may be more useful as multiple independent
27       plugins).
28
29       Callback methods have three potential calling conventions:
30
31       wrapped
32           Wrapped callbacks receive a coderef as their first argument (before
33           any arguments to the callback itself), and that coderef can be used
34           to call the next callback in the list (if more than one plugin
35           implements a given callback). In particular, this allows calling
36           the next plugin multiple times, or not at all if necessary. Wrapped
37           plugins should always call their coderef in list context. All
38           plugins listed below are wrapped plugins unless indicated
39           otherwise.
40
41       chained
42           Chained callbacks receive a list of arguments, and return a new
43           list of arguments which will be passed to the next plugin in the
44           chain. This allows each plugin a chance to modify a value before
45           it's actually used by the repl.
46
47       concatenate
48           Concatenate callbacks receive a list of arguments, and return a
49           list of response values. Each plugin that implements the given
50           callback will be called with the same arguments, and the results
51           will be concatenated together into a single list, which will be
52           returned. Callbacks for published messages are of this type.
53
54   CALLBACKS
55       prompt
56           Called to determine the prompt to use when reading the next line.
57           Takes no arguments, and returns a single string to use as the
58           prompt. The default implementation returns ">"
59
60       read_line
61           Called to actually read a line from the user. Takes no arguments,
62           and returns a single string. The default implementation uses the
63           "<>" operator to read a single line from "STDIN".
64
65       command_$name (chained)
66           If the line read from the user is of the form "#foo args...", then
67           plugins will be searched for a callback method named "command_foo".
68           This callback takes a single string containing the provided
69           arguments, and returns a new line to evaluate instead, if any.
70
71       mangle_line (chained)
72           Modifies the line read from the user before it's evaluated. Takes
73           the line as a string and returns the modified line.
74
75       compile
76           Compiles the string of Perl code into a coderef. Takes the line of
77           code as a string and a hash of extra parameters, and returns the
78           coderef to be executed.  The default implementation uses
79           Eval::Closure to compile the given string.
80
81           The hash of extra parameters is passed directly to "eval_closure".
82
83       execute
84           Executes the coderef which has just been compiled. Takes the
85           coderef and a list of parameters to pass to it, and returns the
86           list of results returned by calling the coderef. The default
87           implementation just calls the coderef directly.
88
89       mangle_error (chained)
90           If the "compile" or "execute" callbacks throw an exception, this
91           callback will be called to modify the exception before it is passed
92           to "print_error".  It receives the exception and returns the
93           modified exception.
94
95       print_error
96           If the "compile" or "execute" callbacks throw an exception, this
97           callback will be called to display it to the user. It receives the
98           exception and returns nothing. The default implementation just uses
99           "print" to print it to the screen.
100
101       mangle_result (chained)
102           This callback is used to modify the result of evaluating the line
103           of code before it is displayed. It receives the list of results and
104           returns a modified list of results.
105
106       print_result
107           This callback displays to the user the results of evaluating the
108           given line of code. It receives the list of results, and returns
109           nothing. The default implementation just uses "print" to print them
110           to the screen.
111
112       loop (chained)
113           This callback is called at the end of each evaluation. It receives
114           whether the repl has been requested to terminate so far, and
115           returns whether the repl should terminate.
116
117       Reply plugins can also communicate among each other via a pub/sub
118       mechanism. By calling the "publish" method, all plugins which respond
119       to the given message (implement a method of the given name) will have
120       that method called with the given arguments, and all of the responses
121       will be collected and returned. Some messages used by the default
122       plugins are:
123
124       tab_handler ($line)
125           Plugins can publish this message when they want to attempt tab
126           completion.  Plugins that respond to this message should return a
127           list of potential completions of the line which is passed in.
128
129       lexical_environment
130           Plugins which wish to modify the lexical environment should do so
131           by implementing this message, which should return a hashref of
132           variable names (including sigils) to value references. There can be
133           more than one lexical environment (each maintained by a different
134           plugin), so plugins that wish to inspect the lexical environment
135           should do so by calling "$self->publish('lexical_environment')",
136           and then merging together all of the hashrefs which are returned.
137
138       package
139           Plugins which wish to modify the currently active package should do
140           so by implementing this message, which should return the name of
141           the current package.  Then, to access the currently active package,
142           a plugin can call "($self->publish('package'))[-1]".
143
144       Your plugins, however, are not limited to these messages - you can use
145       whatever messages you want to communicate.
146

METHODS

148   publish ($name, @args)
149       Publish a message to other plugins which respond to it. All loaded
150       plugins which implement a method named $name will have it called with
151       @args as the parameters. Returns a list of everything that each plugin
152       responded with.
153
154   commands
155       Returns the names of the "#" commands that this plugin implements. This
156       can be used in conjunction with "publish" -
157       "$plugin->publish('commands')" will return a list of all commands which
158       are available in the current Reply session.
159

AUTHOR

161       Jesse Luehrs <doy@tozt.net>
162
164       This software is Copyright (c) 2016 by Jesse Luehrs.
165
166       This is free software, licensed under:
167
168         The MIT (X11) License
169
170
171
172perl v5.38.0                      2023-07-21                  Reply::Plugin(3)
Impressum