This file is indexed.

/usr/share/perl5/ExtUtils/XSpp/Plugin.pod is in libextutils-xspp-perl 0.1602-3.

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
=head1 NAME

ExtUtils::XSpp::Plugin - XS++ plugin interface

=head1 DESCRIPTION

The XS++ plugin interface is B<EXPERIMENTAL> and subject to change.
If you still want to use it, read the source of this module.

=begin internal

=head1 SYNTAX

    %loadplugin{MyPlugin};

    int foo(int y) %FuncTag{Foo};

    class klass
    {
        %ClassTag{Klass};

        void bar() %MethodTag{Bar};
    };

There are two ways a plugin can modify the code emitted by XS++: it
can run after the parsing completes and modify the expression tree
before it is emitted or it can handle custom annotation tags
associated with a class/function/method.

A custom tag can have either positional or named parameters:

    # positional
    %Foo{Id}{% multi
               line
               block %}{AnotherId};

    # named
    %Bar{
        %AParam{Id};
        %AnotherParam{% block %};
        %AThirdParam{AnotherId};
    };

No check is performed on parameter names/types/count.  The parser only
gives an error if the annotation is not handled by any plugin.

Positional parameters are passed to tag handlers as an array reference
in the C<any_positional_arguments> parameter; named handlers are passed as
an hash reference in the C<any_named_arguments> parameter.

The value of a special block parameter is an array reference with an
element for each line in the special block.  For consistency, the
value of an identifier parameter is a single-element array reference.

=head1 XS++ METHODS

These methods are defined in the parser object.

=head2 add_post_process_plugin

    $parser->add_post_process_plugin( plugin => $instance );

Registers a post-processing plugin to be called after the parsing
finishes.

=head2 add_function_tag_plugin

    $parser->add_function_tag_plugin( plugin => $instance,
                                      # optional
                                      tag    => $tag,
                                      );

Add a plugin to handle functions annotated with tags.

=head2 add_class_tag_plugin

    $parser->add_class_tag_plugin( plugin => $instance,
                                   # optional
                                   tag    => $tag,
                                   );

Add a plugin to handle classes annotated with tags.

=head2 add_method_tag_plugin

    $parser->add_method_tag_plugin( plugin => $instance,
                                    # optional
                                    tag    => $tag,
                                    );

Add a plugin to handle methods annotated with tags.

=head2 add_toplevel_tag_plugin

    $parser->add_toplevel_tag_plugin( plugin => $instance,
                                      # optional
                                      tag    => $tag,
                                      );

Add a plugin to handle top-level directives.

=head1 PLUGIN METHODS

These methods can be defined by the plugin to modify the emitted code.

=head2 register_plugin

    sub register_plugin {
        my( $class, $parser ) = @_;

        # call the various add_*_plugin methods to register the plugin
    }

This method is called once for each loaded plugin, the first time the
parser sees the C<%loadplugin> directive.

TODO add another method that is called once for each C<%loadplugin>
declaration, and allow passing parameters to the plugin.

=head2 post_process

    sub post_process {
        my( $self, $nodes ) = @_;

        # process and mutate the list of nodes
    }

=head2 handle_function_tag

    sub handle_function_tag {
        my( $self, $function, $tag, %args ) = @_;

        # do something useful
    }

C<$function> is a C<Function> node.  C<$tag> is the tag string,
without the C<%> prefix.  C<%args> are the arguments passed to the
tag.

If the method handles the tag, it must return C<1> to the caller.

=head2 handle_class_tag

    sub handle_class_tag {
        my( $self, $class, $tag, %args ) = @_;

        # do something useful
    }

C<$class> is a C<Class> node.  C<$tag> is the tag string, without the
C<%> prefix.  C<%args> are the arguments passed to the tag.  The
handler for the class is called after the handlers for its methods.

If the method handles the tag, it must return C<1> to the caller.

=head2 handle_method_tag

    sub handle_method_tag {
        my( $self, $method, $tag, %args ) = @_;

        # do something useful
    }

C<$method> is a C<Method> node.  C<$tag> is the tag string, without
the C<%> prefix.  C<%args> are the arguments passed to the tag.

If the method handles the tag, it must return C<1> to the caller.

=head2 handle_toplevel_tag

    sub handle_toplevel_tag {
        my( $self, undef, $tag, %args ) = @_;

        # do something useful
    }

C<$tag> is the tag string, without the C<%> prefix.  C<%args> are the
arguments passed to the tag.  The C<undef> value is for uniformity
with other tag handlers.

If the method handles the tag, it must return C<1> to the caller.

=end internal

=cut