1Pod::Readme::Plugin(3)User Contributed Perl DocumentationPod::Readme::Plugin(3)
2
3
4

NAME

6       Pod::Readme::Plugin - Plugin role for Pod::Readme
7

DESCRIPTION

9       Pod::Readme v1.0 and later supports plugins that extend the
10       capabilities of the module.
11

WRITING PLUGINS

13       Writing plugins is straightforward. Plugins are Moo::Role modules in
14       the "Pod::Readme::Plugin" namespace.  For example,
15
16         package Pod::Readme::Plugin::myplugin;
17
18         use Moo::Role;
19
20         sub cmd_myplugin {
21             my ($self, @args) = @_;
22             my $res = $self->parse_cmd_args( [qw/ arg1 arg2 /], @args );
23
24             ...
25         }
26
27       When Pod::Readme encounters POD with
28
29         =for readme plugin myplugin arg1 arg2
30
31       the plugin role will be loaded, and the "cmd_myplugin" method will be
32       run.
33
34       Note that you do not need to specify a "cmd_myplugin" method.
35
36       Any method prefixed with "cmd_" will be a command that can be called
37       using the "=for readme command" syntax.
38
39       A plugin parses arguments using the "parse_cmd_arguments" method and
40       writes output using the write methods noted above.
41
42       See some of the included plugins, such as Pod::Readme::Plugin::version
43       for examples.
44
45       Any attributes in the plugin should be prefixed with the name of the
46       plugin, to avoid any conflicts with attribute and method names from
47       other plugins, e.g.
48
49         use Types::Standard qw/ Int /;
50
51         has 'myplugin_heading_level' => (
52           is      => 'rw',
53           isa     => Int,
54           default => 1,
55           lazy    => 1,
56         );
57
58       Attributes should be lazy to ensure that their defaults are properly
59       set.
60
61       Be aware that changing default values of an attribute based on
62       arguments means that the next time a plugin method is run, the defaults
63       will be changed.
64
65       Custom types in Pod::Readme::Types may be useful for attributes when
66       writing plugins, e.g.
67
68         use Pod::Readme::Types qw/ File HeadingLevel /;
69
70         has 'myplugin_file' => (
71           is      => 'rw',
72           isa     => File,
73           coerce  => sub { File->coerce(@_) },
74           default => 'Changes',
75           lazy => 1,
76         );
77
78         # We add this file to the list of dependencies
79
80         around 'depends_on' => sub {
81           my ($orig, $self) = @_;
82           return ($self->myplugin_file, $self->$orig);
83         };
84

ATTRIBUTES

86   "verbatim_indent"
87       The number of columns to indent a verbatim paragraph.
88

METHODS

90   "parse_cmd_args"
91         my $hash_ref = $self->parse_cmd_args( \@allowed_keys, @args);
92
93       This command parses arguments for a plugin and returns a hash reference
94       containing the argument values.
95
96       The @args parameter is a list of arguments passed to the command method
97       by Pod::Readme::Filter.
98
99       If an argument contains an equals sign, then it is assumed to take a
100       string.  (Strings containing whitespace should be surrounded by
101       quotes.)
102
103       Otherwise, an argument is assumed to be boolean, which defaults to
104       true. If the argument is prefixed by "no-" or "no_" then it is given a
105       false value.
106
107       If the @allowed_keys parameter is given, then it will reject argument
108       keys that are not in that list.
109
110       For example,
111
112         my $res = $self->parse_cmd_args(
113                     undef,
114                     'arg1',
115                     'no-arg2',
116                     'arg3="This is a string"',
117                     'arg4=value',
118         );
119
120       will return a hash reference containing
121
122         {
123            arg1 => 1,
124            arg2 => 0,
125            arg3 => 'This is a string',
126            arg4 => 'value',
127         }
128
129   "write_verbatim"
130         $self->write_verbatim($text);
131
132       A utility method to write verbatim text, indented by "verbatim_indent".
133
134   "write_para"
135         $self->write_para('This is a paragraph');
136
137       Utility method to write a POD paragraph.
138
139   "write_head1"
140   "write_head2"
141   "write_head3"
142   "write_head4"
143   "write_over"
144   "write_item"
145   "write_back"
146   "write_begin"
147   "write_end"
148   "write_for"
149   "write_encoding"
150   "write_cut"
151   "write_pod"
152         $self->write_head1($text);
153
154       Utility methods to write POD specific commands to the "output_file".
155
156       These methods ensure the POD commands have extra newlines for
157       compatibility with older POD parsers.
158
159
160
161perl v5.32.1                      2021-01-27            Pod::Readme::Plugin(3)
Impressum