head

OO::Plugin – framework for working with OO plugins.


use OO::Plugin;
use OO::Plugin::Manager;


class Foo is pluggable {
    has $.attr;
    method bar is pluggable {
        return 42;
    }
}


plugin Fubar {
    method a-bar ( $msg ) is plug-around( Foo => 'bar' ) {
        $msg.set-rc( pi ); # Will override &Foo::bar return value and prevent its execution.
    }
}


my $manager = OO::Plugin::Manager.new.initialize;
my $instance = $manager.create( Foo, attr => 'some value' );
say $instance.bar;  # 3.141592653589793


With this framework any application can have highly flexible and extensible plugin subsystem with which plugins would be
capable of:


item

Not yet supported but planned for the future is plugin compatibility management.


L<C<OO::Plugin::Manual>>,
L<C<OO::Plugin>>,
L<C<OO::Plugin::Manager>>,
L<C<OO::Plugin::Class>>


AUTHOR

root

para

L<Examples| file:../examples/index.podlite>


L<Download |file:../download/index.podlite>


React

=begin React :component<HeaderCol> :id<menu> 
=para L<Documentation|/doc/introduction>
=para L<Modules| /mods>
=para L<Examples| file:../examples/index.podlite>
=para L<Download |file:../download/index.podlite>
=para L<About|file:../about/index.podlite>
=para 🔍 K<⌘K>/K<ctrl-K>
=end React


HEADER

FOOTER

README

code

Html

Plugin

This document is provinding the reader with in-depth explanation of how C<OO::Plugin> framework works. Technical details
are provided in respective modules.


This framework is intended to provide a mechanizm of extending an application functionality through use of third-party
provided plugins. The following functionality is provided for a plugin:


Also supported are automatic plugin module loading, and managing of plugin dependencies and priorities.


All work is done through a plugin manager. It is generally recommended to have a single instance of plugin manager per
application. The application, in turn, is supposed to delegate it's object creation functionality to the manager. I.e.,
where usually we create an instance with this line of code:


my $foo = $plugin-manager.create( Foo, attr => 'a value' );


Alternatively, if one needs a class to work with but still capable of supporting plugins, he can do the following:


my \foo-class = $plugin-manager.class( Foo );


What happens under the hood is that the manager takes your class, considers what plugins are requesting to modify its
behavior, and then creates a new class for you which will delegate some of its functionality to the plugins. This is
somewhat simplified description of what is happening but it is only intended to explain why the delegation is necessary.


All the above also means that the creation of a plugin manager object is one of the first thing an application must do
before anything else. Typically, the code would look like this:


class MyApp {
    has OO::Plugin::Manager $!plugin-manager;


submethod TWEAK {
    $!plugin-manager .= new( base => 'MyApp' );
    $!plugin-manager.load-plugins;
    $!plugin-manager.initialize( app => self );
}
}


Of these three steps invocation of the C<load-plugins> method is optional. This is where automatic pre-loading of
plugins from external modules is happening. Refer to corresponding section below to find out more about this process.


By invocing C<initialize> we actually make the manager ready to do its job. The point for having all these stages is to
allow an application to perfom some extra additional steps before plugins are activated. Those are:


Future versions of the framework may have some additional functionality and this more things could be done before we
start using the manager.


B<NOTE> I<Though plugin disabling and changes to the ordering are not prohibited after the manager is initialized,
they're not recommended due to possible unwanted side effect. Moreover, ordering is only done while manager is
initializing.>


A thing in the above code which worth mentioning here is the parameters to the C<initialize> method call. The method
itself doesn't take any. Whatever it receives is getting passed to the constructors of newly created plugin objects
(this subject will be covered later). In my code what happens is that application object informs its plugins about
itself allowing direct interaction between plugins and the application. By providing special API an application could
get even more from its plugins that what is covered by the manager. Consider the following sample plugin:


plugin MyPlugin {
    has MyApp:D $.app is required;


submethod TWEAK (|) {
    $.app.register-macro( "some_macro", self.^find_method('my-macro') );
}


method my-macro ( $param ) { "$param is now expanded" }
}


Whatever other extensible subsystem is provided by application is then left up to the application and its plugins, the
manager is not involved and thus leaves more space for developer's imagination.


When the manager is created it's C<base> attribute can be defined. This attribute defines a namespace prefix to be used
when looking for plugins in external modules. For the example above the manager will try to load all modules with names
starting with I<MyApp::Plugin::> or I<MyApp::Plugins::>. Upon loading all classes contained in these modules and defined
using C<plugin> keyword will register themselves with the framework. This allows a single module to define more than one
plugin:


As a result of compiling this module the framework will know about two new plugins C<Plugin1> and C<Plugin2>. Yet, it
must be noted that though we're referring to them here with their short names, the framework will know them by their
fully qualified names (FQN): C<MyApp::Plugins::MySet::Plugin1> and C<MyApp::Plugins::MySet::Plugin2>. This is to prevent
name clashes when accidentally plugins from different packages are given same names.


It is possible for a two more plugins to be handling same method, class, or callback. In this case it becomes very
important to define the order in which their respective handlers are used. When ordering plugins the manager takes into
consideration a couple of plugin attributes such as:


Priorities could be of three different levels: I<first>, I<normal>, and I<last>. Their names suggest that user wants
a plugin to be one of the first in the list, one of the last, or in the middle. The latter is the default.


Within each priority a user can define in what particular order he wants the plugins. See
L<section|#user-defined-ordering> below.


To simplify user's life we don't want to make it his responsibility to find out if a I<Plugin1> only works if it
follows, say, I<Plugin2>. The framework lets plugins define these kind of relations. More than that, it is also possible
to specify wether the relation is desirable or it is demanded. Consider the following code:


plugin Plugin1 after Plugin2 before Plugin3 demands Plugin4, Plugin5 {
    ...
}


Though rather unlikely to be met in real life, this code demonstrates what can be specified for a plugin. Here traits
C<after> and C<before> (B<note> that C<before> is just a reverse of C<after>. I.e. C<Plugin1 before Plugin2> is the same
as C<Plugin2 after Plugin1>) define desirable relations. In other words, no fatalities would happen if these relations
are broken. 'Broken' means here that either I<Plugin2> or I<Plugin3> are missing; or together with I<Plugin1> and,
possibly with some other plugins too, they form a circular dependency (see below about sorting).


On the  other hand, C<demand> means that if it can't be fulfilled then the only way to resolve the situation is to
disable this plugin.


It is possible for a user to specifically set the wanted order of plugins within each priority. E.g., for a set of
plugins  I<P1, P2, P3, P4, P5, P6, P7, P8, P9, P10> a user can specify that:


For user-ordered plugins there is a rule that they will go first within their priority if they belong to I<first> or
I<normal>; and they will go after unordered ones within I<last>.


B<NOTE> Read the followin section carefully as the resulting order might differ from user expectations.


The manager will do its best to conform all the ordering parameters. But due to the complexity of the matter the only
rule which can be taken for granted is:


All other relations, including user-defined, are considered voluntary. Though they're prioritized in the following order
(from more prioritized down to less):


Manual

The Raku Knowledge Base


=begin React :component<HeaderCol> :id<footer>  
=begin nested :!nested
=item1 B<Language>
    =item2 L<Get started|file:../getting-started/getting-started.podlite>
    =item2 L<Why Raku?|/doc/language/faq#Why-should-I-learn-Raku-What's-so-great-about-it>
    =item2 L<Try Raku|https://glot.io/new/raku>
    =item2 L<Raku cheat sheet|https://github.com/Raku/mu/blob/master/docs/Perl6/Cheatsheet/cheatsheet.txt>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<Raku on Exercism|https://exercism.org/tracks/raku>
    =item2 L<Wikipedia|https://en.wikipedia.org/wiki/Raku_(programming_language)>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=begin nested :!nested

=item1 B<L<Documentation|/doc>>
    =item2 L<Getting started, Migration guides from other languages, & Tutorials | file:../doc/introduction.podlite>
    =item2 L<Language References|file:../doc/reference.podlite>
    =item2 L<Type Reference| file:../doc/types.podlite>
    =item2 L<Miscellaneous| file:../doc/miscellaneous.podlite>
    =item2 L<FAQs (Frequently Asked Questions)|/doc/language/faq>
    =item2 L<Community|/doc/language/community>
    =item2 L<The list of all documents|file:../doc/index.podlite>

=item1 B<Resources>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>

=end nested
=begin nested :!nested

=item1 B<Resoures>
    =item2 L<Download | file:../download/index.podlite>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=item1 B<Learning>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Wikibook |https://en.wikibooks.org/wiki/Raku_Programming>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>
    =item2 L<Learn Raku in Y minutes|https://learnxinyminutes.com/docs/raku/>
    =item2 L<Golfing |https://github.com/AlexDaniel/raku-golf-cheatsheet>
=end nested
=begin nested :!nested

=item1 B<Explore>
    =item2 L<Raku Blog Aggregator|https://planet.raku.org/>
    =item2 L<Rakudo Weekly|https://rakudoweekly.blog/>
    =item2 L<The Weekly Challenge |https://perlweeklychallenge.org/>
    =item2 L<Raku Advent Calendar|https://raku-advent.blog/>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=end React


=begin React :component<CookieConsent> :id<CookieConsent> :buttonCaption("Got it!")
=para
This website uses cookies for analytics.
=end React


README

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO

AUTHOR

OO::Plugin v0.0.8

Authors

License

Dependencies

Test Dependencies

Provides

Documentation