Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Reply::Plugin(3)      User Contributed Perl Documentation     Reply::Plugin(3)

       Reply::Plugin - base class for Reply plugins

       version 0.42

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

	 use base 'Reply::Plugin';

	 # ...

       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

       Callback	methods	have three potential calling conventions:

	   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

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

	   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 ">"

	   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.

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

	   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.

	   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.

	   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.

	   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.

	   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.

   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.

       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.

       Jesse Luehrs <>

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

       This is free software, licensed under:

	 The MIT (X11) License

perl v5.32.1			  2016-08-24		      Reply::Plugin(3)


Want to link to this manual page? Use this URL:

home | help