/usr/share/perl5/ExtUtils/XSpp/Plugin.pod is in libextutils-xspp-perl 0.1800-2.
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 | =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<positional> parameter; named handlers are passed as
an hash reference in the C<named> 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,
method => 'post_process',
);
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,
method => 'handle_function_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,
method => 'handle_class_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,
method => 'handle_method_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,
method => 'handle_toplevel_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.
If the return value is a list, the first element is the
handled/not-handled flag, remaining elements are a list of nodes to
add to the node list returned by the parser.
The method is called after parsing of the function completes.
=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.
If the return value is a list, the first element is the
handled/not-handled flag, remaining elements are a list of nodes to
add to the node list in the class.
The method is called after parsing of the class completes, and after the
handlers for methods contained in the class.
=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.
If the return value is a list, the first element is the
handled/not-handled flag, remaining elements are a list of nodes to
add to the node list in the containing class.
The method is called after the method has been added to the class and
before the handler for class tags.
=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.
If the return value is a list, the first element is the
handled/not-handled flag, remaining elements are a list of nodes to
add to the node list returned by the parser.
The method is called after the parsing of the tag completes.
=end internal
=cut
|