1Pod::Readme::Plugin(3)User Contributed Perl DocumentationPod::Readme::Plugin(3)
2
6 Pod::Readme::Plugin - Plugin role for Pod::Readme
7
9 Pod::Readme v1.0 and later supports plugins that extend the
10 capabilities of the module.
11
13 Writing plugins is straightforward. Plugins are Moo::Role modules in
14 the "Pod::Readme::Plugin" namespace. For example,
15 package Pod::Readme::Plugin::myplugin;
17 use Moo::Role;
19 sub cmd_myplugin {
21 my ($self, @args) = @_;
22 my $res = $self->parse_cmd_args( [qw/ arg1 arg2 /], @args );
23 ...
25 }
26 When Pod::Readme encounters POD with
28 =for readme plugin myplugin arg1 arg2
30 the plugin role will be loaded, and the "cmd_myplugin" method will be
32 run.
33 Note that you do not need to specify a "cmd_myplugin" method.
35 Any method prefixed with "cmd_" will be a command that can be called
37 using the "=for readme command" syntax.
38 A plugin parses arguments using the "parse_cmd_arguments" method and
40 writes output using the write methods noted above.
41 See some of the included plugins, such as Pod::Readme::Plugin::version
43 for examples.
44 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 use Types::Standard qw/ Int /;
50 has 'myplugin_heading_level' => (
52 is => 'rw',
53 isa => Int,
54 default => 1,
55 lazy => 1,
56 );
57 Attributes should be lazy to ensure that their defaults are properly
59 set.
60 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 Custom types in Pod::Readme::Types may be useful for attributes when
66 writing plugins, e.g.
67 use Pod::Readme::Types qw/ File HeadingLevel /;
69 has 'myplugin_file' => (
71 is => 'rw',
72 isa => File,
73 coerce => sub { File->coerce(@_) },
74 default => 'Changes',
75 lazy => 1,
76 );
77 # We add this file to the list of dependencies
79 around 'depends_on' => sub {
81 my ($orig, $self) = @_;
82 return ($self->myplugin_file, $self->$orig);
83 };
84
86 "verbatim_indent"
87 The number of columns to indent a verbatim paragraph.
88
90 "parse_cmd_args"
91 my $hash_ref = $self->parse_cmd_args( \@allowed_keys, @args);
92 This command parses arguments for a plugin and returns a hash reference
94 containing the argument values.
95 The @args parameter is a list of arguments passed to the command method
97 by Pod::Readme::Filter.
98 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 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 If the @allowed_keys parameter is given, then it will reject argument
108 keys that are not in that list.
109 For example,
111 my $res = $self->parse_cmd_args(
113 undef,
114 'arg1',
115 'no-arg2',
116 'arg3="This is a string"',
117 'arg4=value',
118 );
119 will return a hash reference containing
121 {
123 arg1 => 1,
124 arg2 => 0,
125 arg3 => 'This is a string',
126 arg4 => 'value',
127 }
128 "write_verbatim"
130 $self->write_verbatim($text);
131 A utility method to write verbatim text, indented by "verbatim_indent".
133 "write_para"
135 $self->write_para('This is a paragraph');
136 Utility method to write a POD paragraph.
138 "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 Utility methods to write POD specific commands to the "output_file".
155 These methods ensure the POD commands have extra newlines for
157 compatibility with older POD parsers.
158perl v5.32.0 2020-07-28 Pod::Readme::Plugin(3)