This file is indexed.

/usr/share/perl5/Mason/Manual/Plugins.pod is in libmason-perl 2.24-1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
__END__

=pod

=head1 NAME

Mason::Manual::Plugins - Mason plugins

=head1 DESCRIPTION

A Mason plugin modifies behavior in one or more of Mason's main classes
simultaneously, using Moose roles. Many Mason features, even some that might be
considered "core", are implemented with plugins.

=head1 FINDING PLUGINS

By convention plugins live in the "Mason::Plugin::*" namespace, and plugin
bundles live in the "Mason::PluginBundle::*" namespace. You can find both with
this search:

    http://search.cpan.org/search?query=Mason%3A%3APlugin&mode=all

=head1 USING PLUGINS

Pass a list of plugin specs to the Mason constructor:

    Mason->new(plugins =>
            [
             'OnePlugin', 
             'AnotherPlugin',
             '+My::Mason::Plugin::AThirdPlugin',
             '@APluginBundle',
             '+My::Mason::PluginBundle::AnotherBundle',
             '-PluginIDontLike',
            ]);

Each plugin spec can be one of the following;

=over

=item *

A simple name, which will have "Mason::Plugin::" prepended to it.

=item *

A bundle name, prefixed with '@', which will have "Mason::PluginBundle::"
prepended to it.

=item *

A full plugin or bundle class name prefixed with '+'.

=item *

Any spec prefixed with '-', which means do not include these plugin(s) in the
final list.

=back

See Mason::t::Plugins::test_plugin_specs in the Mason distribution for some
examples.

=head1 DEFAULT PLUGINS

Mason will always add the L<@Default|Mason::PluginBundle::Default> bundle
regardless of whether you pass your own list. You can remove individual default
plugins that you don't like:

    plugins => ['-DollarDot', ...]

or the whole list:

    plugins => ['-@Default', ...]

=head1 CREATING PLUGINS

Note: If you want to modify behavior for a particular application only, it
might be more convenient to create L<subclasses|Mason::Manual::Subclasses>.

A plugin consists of the main plugin class and one or more roles. The main
class currently looks like this:

    package Mason::Plugin::MyPlugin;
    use Moose;
    with 'Mason::Plugin';

    # Optional: declare other plugin dependencies
    method requires_plugins { qw(A @D) }

    1;

    __END__

    =pod

    =head1 NAME

    Mason::Plugin::MyPlugin - My plugin

    ....

Its main responsibilities are to include the role 'Mason::Plugin' and document
itself. It may also specify a C<requires_plugins> that returns a list of
dependencies with the same syntax as the C<plugins> parameter to C<Mason->new>.

The real action is in the role classes, which live underneath, and each modify
a single Mason class:

    package Mason::Plugin::MyPlugin::Interp;
    use Mason::PluginRole;

    # Modify Mason::Interp

    ...

    package Mason::Plugin::MyPlugin::Compilation;
    use Mason::PluginRole;

    # Modify Mason::Compilation

    ...

When a plugin is applied, each of its roles will be automatically applied to
the appropriate Mason class. For example, in the example above
C<Mason::Plugin::MyPlugin::Interp> and C<Mason::Plugin::MyPlugin::Compilation>
will be applied to Mason::Interp and Mason::Compilation respectively.

=head2 Pluggable Mason classes

As of this writing the following Mason classes can be modified with plugins:

    Mason::CodeCache
    Mason::Compilation
    Mason::Component
    Mason::Component::ClassMeta
    Mason::Component::Import
    Mason::Component::Moose
    Mason::Interp
    Mason::Request
    Mason::Result

=head2 Extra classes in plugin

If you have extra classes in your plugin that aren't automatically providing a
role to a Mason class, put them in C<Extra.pm> or the C<Extra> subdirectory,
e.g.

   package Mason::Plugin::MyPlugin::Extra::Utils;
   ...

That will ensure that your classname will not conflict with a future Mason
class name.

=head1 CREATING PLUGIN BUNDLES

A plugin bundle just collects one or more plugins and/or other bundles. It
looks like this:

    package Mason::PluginBundle::MyBundle
    use Moose;
    with 'Mason::PluginBundle';
    
    sub requires_plugins {
        return (
            'A',
            'B',
            '+My::Plugin::C',
            '@D',
            '+My::PluginBundle::E',
            );
    }
    
    1;
    
    __END__
    
    =pod
    
    =head1 NAME
    
    Mason::PluginBundle::MyBundle - My plugin bundle
    
    =head1 INCLUDED PLUGINS
    
    =over
    
    =item A
    =item B
    =item +My::Plugin::C
    =item @D
    =item +My::PluginBundle::E
    
    =back
    
    ....

The C<requires_plugins> method returns a list of entries, with the same syntax
as the C<plugins> parameter to C<Mason->new>.

=head1 ACKNOWLEDGEMENTS

Thanks to Ricardo Signes <rjbs@cpan.org> for L<Dist::Zilla|Dist::Zilla> and
L<Pod::Weaver|Pod::Weaver>, which got me thinking in plugins and lent the
plugin and bundle name syntax.

=head1 SEE ALSO

L<Mason|Mason>

=head1 AUTHOR

Jonathan Swartz <swartz@pobox.com>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Jonathan Swartz.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut